fix: Polyfill the promise library to permanently fix unhandled rejections

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - Deprecate initialScope in favor of configureScope #1963
 - Bump: Sentry Android to 5.5.1 and Sentry Cocoa to 7.7.0 #1965
+- fix: Polyfill the promise library to permanently fix unhandled rejections #1984
 
 ## 3.2.8
 

sample/package.json

@@ -29,9 +29,6 @@
   },
   "name": "sample",
   "private": true,
-  "resolutions": {
-    "promise": "^8.1.0"
-  },
   "scripts": {
     "android": "react-native run-android",
     "ios": "react-native run-ios",

src/js/integrations/reactnativeerrorhandlers.ts

@@ -9,6 +9,7 @@ import { ReactNativeClient } from "../client";
 interface ReactNativeErrorHandlersOptions {
   onerror: boolean;
   onunhandledrejection: boolean;
+  patchGlobalPromise: boolean;
 }
 
 interface PromiseRejectionTrackingOptions {
@@ -35,10 +36,11 @@ export class ReactNativeErrorHandlers implements Integration {
   private readonly _options: ReactNativeErrorHandlersOptions;
 
   /** Constructor */
-  public constructor(options?: ReactNativeErrorHandlersOptions) {
+  public constructor(options?: Partial<ReactNativeErrorHandlersOptions>) {
     this._options = {
       onerror: true,
       onunhandledrejection: true,
+      patchGlobalPromise: true,
       ...options,
     };
   }
@@ -56,68 +58,76 @@ export class ReactNativeErrorHandlers implements Integration {
    */
   private _handleUnhandledRejections(): void {
     if (this._options.onunhandledrejection) {
-      /*
-        In newer RN versions >=0.63, the global promise is not the same reference as the one imported from the promise library.
-        This is due to a version mismatch between promise versions. The version will need to be fixed with a package resolution.
-        We first run a check and show a warning if needed.
-      */
-      this._checkPromiseVersion();
-
-      const tracking: {
-        disable: () => void;
-        enable: (arg: unknown) => void;
-        // eslint-disable-next-line @typescript-eslint/no-var-requires,import/no-extraneous-dependencies
-      } = require("promise/setimmediate/rejection-tracking");
-
-      const promiseRejectionTrackingOptions = this._getPromiseRejectionTrackingOptions();
-
-      tracking.disable();
-      tracking.enable({
-        allRejections: true,
-        onUnhandled: (id: string, error: Error) => {
-          if (__DEV__) {
-            promiseRejectionTrackingOptions.onUnhandled(id, error);
-          }
+      if (this._options.patchGlobalPromise) {
+        this._polyfillPromise();
+      }
 
-          getCurrentHub().captureException(error, {
-            data: { id },
-            originalException: error,
-          });
-        },
-        onHandled: (id: string) => {
-          promiseRejectionTrackingOptions.onHandled(id);
-        },
-      });
+      this._attachUnhandledRejectionHandler();
+      this._checkPromiseAndWarn();
     }
   }
   /**
-   * Gets the promise rejection handlers, tries to get React Native's default one but otherwise will default to console.logging unhandled rejections.
+   * Polyfill the global promise instance with one we can be sure that we can attach the tracking to.
+   *
+   * In newer RN versions >=0.63, the global promise is not the same reference as the one imported from the promise library.
+   * This is due to a version mismatch between promise versions.
+   * Originally we tried a solution where we would have you put a package resolution to ensure the promise instances match. However,
+   * - Using a package resolution requires the you to manually troubleshoot.
+   * - The package resolution fix no longer works with 0.67 on iOS Hermes.
    */
-  private _getPromiseRejectionTrackingOptions(): PromiseRejectionTrackingOptions {
-    return {
-      onUnhandled: (id, rejection = {}) => {
-        // eslint-disable-next-line no-console
-        console.warn(
-          `Possible Unhandled Promise Rejection (id: ${id}):\n${rejection}`
-        );
+  private _polyfillPromise(): void {
+    /* eslint-disable import/no-extraneous-dependencies,@typescript-eslint/no-var-requires*/
+    const {
+      polyfillGlobal,
+    } = require("react-native/Libraries/Utilities/PolyfillFunctions");
+
+    // Below, we follow the exact way React Native initializes its promise library, and we globally replace it.
+    const Promise = require("promise/setimmediate/es6-extensions");
+
+    // As of RN 0.67 only done and finally are used
+    require("promise/setimmediate/done");
+    require("promise/setimmediate/finally");
+
+    polyfillGlobal("Promise", () => Promise);
+    /* eslint-enable import/no-extraneous-dependencies,@typescript-eslint/no-var-requires */
+  }
+  /**
+   * Attach the unhandled rejection handler
+   */
+  private _attachUnhandledRejectionHandler(): void {
+    const tracking: {
+      disable: () => void;
+      enable: (arg: unknown) => void;
+      // eslint-disable-next-line import/no-extraneous-dependencies,@typescript-eslint/no-var-requires
+    } = require("promise/setimmediate/rejection-tracking");
+
+    const promiseRejectionTrackingOptions = this._getPromiseRejectionTrackingOptions();
+
+    tracking.disable();
+    tracking.enable({
+      allRejections: true,
+      onUnhandled: (id: string, error: Error) => {
+        if (__DEV__) {
+          promiseRejectionTrackingOptions.onUnhandled(id, error);
+        }
+
+        getCurrentHub().captureException(error, {
+          data: { id },
+          originalException: error,
+        });
       },
-      onHandled: (id) => {
-        // eslint-disable-next-line no-console
-        console.warn(
-          `Promise Rejection Handled (id: ${id})\n` +
-            "This means you can ignore any previous messages of the form " +
-            `"Possible Unhandled Promise Rejection (id: ${id}):"`
-        );
+      onHandled: (id: string) => {
+        promiseRejectionTrackingOptions.onHandled(id);
       },
-    };
+    });
   }
   /**
    * Checks if the promise is the same one or not, if not it will warn the user
    */
-  private _checkPromiseVersion(): void {
+  private _checkPromiseAndWarn(): void {
     try {
       // eslint-disable-next-line @typescript-eslint/no-var-requires,import/no-extraneous-dependencies
-      const Promise = require("promise/setimmediate/core");
+      const Promise = require("promise/setimmediate/es6-extensions");
 
       const _global = getGlobalObject<{ Promise: typeof Promise }>();
 
@@ -135,6 +145,27 @@ export class ReactNativeErrorHandlers implements Integration {
       );
     }
   }
+  /**
+   * Gets the promise rejection handlers, tries to get React Native's default one but otherwise will default to console.logging unhandled rejections.
+   */
+  private _getPromiseRejectionTrackingOptions(): PromiseRejectionTrackingOptions {
+    return {
+      onUnhandled: (id, rejection = {}) => {
+        // eslint-disable-next-line no-console
+        console.warn(
+          `Possible Unhandled Promise Rejection (id: ${id}):\n${rejection}`
+        );
+      },
+      onHandled: (id) => {
+        // eslint-disable-next-line no-console
+        console.warn(
+          `Promise Rejection Handled (id: ${id})\n` +
+            "This means you can ignore any previous messages of the form " +
+            `"Possible Unhandled Promise Rejection (id: ${id}):"`
+        );
+      },
+    };
+  }
   /**
    * Handle errors
    */

src/js/options.ts

@@ -87,6 +87,16 @@ export interface ReactNativeOptions extends BrowserOptions {
    * @deprecated Use `Sentry.configureScope(...)`
    */
   initialScope?: CaptureContext;
+
+  /**
+   * When enabled, Sentry will overwrite the global Promise instance to ensure that unhandled rejections are correctly tracked.
+   * If you run into issues with Promise polyfills such as `core-js`, make sure you polyfill after Sentry is initialized.
+   * Read more at https://docs.sentry.io/platforms/react-native/troubleshooting/#unhandled-promise-rejections
+   *
+   * When disabled, this option will not disable unhandled rejection tracking. Set `onunhandledrejection: false` on the `ReactNativeErrorHandlers` integration instead.
+   * @default true
+   */
+  patchGlobalPromise?: boolean;
 }
 
 export interface ReactNativeWrapperOptions {

src/js/sdk.tsx

@@ -31,6 +31,7 @@ const DEFAULT_OPTIONS: ReactNativeOptions = {
   autoInitializeNativeSdk: true,
   enableAutoPerformanceTracking: true,
   enableOutOfMemoryTracking: true,
+  patchGlobalPromise: true,
 };
 
 /**
@@ -52,7 +53,9 @@ export function init(passedOptions: ReactNativeOptions): void {
 
   if (options.defaultIntegrations === undefined) {
     options.defaultIntegrations = [
-      new ReactNativeErrorHandlers(),
+      new ReactNativeErrorHandlers({
+        patchGlobalPromise: options.patchGlobalPromise,
+      }),
       new Release(),
       ...defaultIntegrations.filter(
         (i) => !IGNORED_DEFAULT_INTEGRATIONS.includes(i.name)

test/integrations/reactnativeerrorhandlers.test.ts

@@ -29,13 +29,8 @@ jest.mock("@sentry/utils", () => {
   };
 });
 
-jest.mock("promise/setimmediate/core", () => {
-  return {};
-});
-
 import { getCurrentHub } from "@sentry/core";
 import { Severity } from "@sentry/types";
-import { getGlobalObject, logger } from "@sentry/utils";
 
 import { ReactNativeErrorHandlers } from "../../src/js/integrations/reactnativeerrorhandlers";
 
@@ -107,30 +102,4 @@ describe("ReactNativeErrorHandlers", () => {
       expect(event.exception?.values?.[0].mechanism?.type).toBe("generic");
     });
   });
-
-  describe("onUnhandledRejection", () => {
-    it("Warns if promise instances are different", () => {
-      const _global = getGlobalObject<{ Promise: any }>();
-
-      _global.Promise = {};
-
-      const inst = new ReactNativeErrorHandlers();
-      inst.setupOnce();
-
-      // eslint-disable-next-line @typescript-eslint/unbound-method
-      expect(logger.warn).toBeCalled();
-    });
-
-    it("Does not warn if promise instances match", () => {
-      const _global = getGlobalObject<{ Promise: any }>();
-
-      _global.Promise = require("promise/setimmediate/core");
-
-      const inst = new ReactNativeErrorHandlers();
-      inst.setupOnce();
-
-      // eslint-disable-next-line @typescript-eslint/unbound-method
-      expect(logger.warn).not.toBeCalled();
-    });
-  });
 });