feat(angular): Log warning if SDK is used with an older Angular version than officially supported (#4964)

introduces a check in the Angular SDK's init function to check if the Angular version it is used with is older than our minimum supported version (Angular 10). In case it is, a warning will be logged.

adjusts the migration and readme docs to reflect better our officially supported Angular versions and what to do if users are using an older Angular version if they experience problems (i.e. stay on v6).


Co-authored-by: Luca Forstner <[email protected]>

Author: 2 people

MIGRATION.md

@@ -129,7 +129,11 @@ The Sentry Angular SDK (`@sentry/angular`) is now compiled with the Angular comp
 
 ### Angular Version Compatibility
 
-Given the forward compatibility of the Angular compiler, v7 of our SDK will only work with Angular 10 and above. Previously, it was possible to use the SDK with versions <10, although we officially only supported Angular 10-13 as peer dependencies. If you are using Angular <10 in your project, we recommend staying on the latest 6.x version until you can upgrade your Angular version.
+As in v6, we continue to list Angular 10-13 in our peer dependencies, meaning that these are the Angular versions we officially support.
+If you are using v7 with Angular <10 in your project and you experience problems, we recommend staying on the latest 6.x
+version until you can upgrade your Angular version. As v7 of our SDK is compiled with the Angular 10 compiler and we upgraded
+our Typescript version, the SDK will work with Angular 10 and above. Tests have shown that Angular 9 seems to work as well
+(use at your own risk) but we recommend upgrading to a more recent Angular version.
 
 ### Import Changes
 

packages/angular/README.md

@@ -14,8 +14,7 @@
 
 ## Angular Version Compatibility
 
-For Angular 10-13 use the latest version of the Sentry Angular SDK. In case
-you are using an Angular 9 or earlier, use version 6.x of the SDK as newer versions do not support Angular <10.
+The latest version of this SDK officially supports Angular 10-13. If you are using an older version of Angular and experience problems with the Angular SDK, we recommend downgrading the SDK to version 6.x.
 
 ## General
 

packages/angular/src/constants.ts

@@ -3,3 +3,8 @@ export const ANGULAR_ROUTING_OP = 'ui.angular.routing';
 export const ANGULAR_INIT_OP = 'ui.angular.init';
 
 export const ANGULAR_OP = 'ui.angular';
+
+/**
+ * Minimum Angular version this SDK supports
+ */
+export const ANGULAR_MINIMUM_VERSION = 10;

packages/angular/src/sdk.ts

@@ -1,4 +1,9 @@
+import { VERSION } from '@angular/core';
 import { BrowserOptions, init as browserInit, SDK_VERSION } from '@sentry/browser';
+import { logger } from '@sentry/utils';
+
+import { ANGULAR_MINIMUM_VERSION } from './constants';
+import { IS_DEBUG_BUILD } from './flags';
 
 /**
  * Inits the Angular SDK
@@ -15,5 +20,20 @@ export function init(options: BrowserOptions): void {
     ],
     version: SDK_VERSION,
   };
+  checkAngularVersion();
   browserInit(options);
 }
+
+function checkAngularVersion(): void {
+  if (VERSION && VERSION.major) {
+    const major = parseInt(VERSION.major, 10);
+    if (major < ANGULAR_MINIMUM_VERSION) {
+      IS_DEBUG_BUILD &&
+        logger.warn(
+          `The Sentry SDK does not officially support Angular ${major}.`,
+          `This version of the Sentry SDK supports Angular ${ANGULAR_MINIMUM_VERSION} and above.`,
+          'Please consider upgrading your Angular version or downgrading the Sentry SDK.',
+        );
+    }
+  }
+}