@amplitude/analytics-core incompatible with React Native Hermes engine — getGlobalScope, btoa/atob, and document.cookie errors

[inaam-ullah]

@amplitude/analytics-core — React Native Hermes Compatibility Issues

Environment

Package	Version
react-native	0.73.6
JS Engine	Hermes
@amplitude/analytics-core	2.39.0
@amplitude/analytics-react-native	1.4.11
@amplitude/plugin-session-replay-react-native	0.4.2

---

Problems & Root Causes

1. TypeError: getGlobalScope is not a function (it is undefined)

observers/network.js imports from ".." (the package root). In React Native, Metro resolves this to the ESM version (lib/esm/index.js) instead of CJS, causing getGlobalScope to arrive as undefined and crashing the app on startup.

// network.js - problematic
var __1 = require("..");  // resolves to ESM in React Native — getGlobalScope is undefined

---

2. Property 'btoa' doesn't exist

storage/cookie.js uses btoa/atob which are browser-only APIs. The Hermes JS engine does not provide these globals, causing a crash whenever Amplitude attempts to store data in cookies.

// cookie.js - problematic
str = "".concat(key, "=").concat(btoa(encodeURIComponent(JSON.stringify(value))));

---

3. Cannot set property 'cookie' of undefined

storage/cookie.js unconditionally accesses globalScope.document.cookie, but document does not exist in React Native. The existing guard only checks if (globalScope) but not whether globalScope.document exists.

// cookie.js - problematic
if (globalScope) {
  globalScope.document.cookie = str; // crashes — document is undefined in React Native
}

---

Fix (via patch-package)

diff --git a/node_modules/@amplitude/analytics-core/lib/cjs/observers/network.js b/node_modules/@amplitude/analytics-core/lib/cjs/observers/network.js
index f3c3793..7ea8624 100644
--- a/node_modules/@amplitude/analytics-core/lib/cjs/observers/network.js
+++ b/node_modules/@amplitude/analytics-core/lib/cjs/observers/network.js
@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.networkObserver = exports.NetworkObserver = exports.NetworkEventCallback = void 0;
 var tslib_1 = require("tslib");
-var __1 = require("..");
+var __1 = require("../global-scope");
 var uuid_1 = require("../utils/uuid");
 var network_request_event_1 = require("../network-request-event");

diff --git a/node_modules/@amplitude/analytics-core/lib/cjs/storage/cookie.js b/node_modules/@amplitude/analytics-core/lib/cjs/storage/cookie.js
index 11ab90d..1599efd 100644
--- a/node_modules/@amplitude/analytics-core/lib/cjs/storage/cookie.js
+++ b/node_modules/@amplitude/analytics-core/lib/cjs/storage/cookie.js
@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isDomainEqual = exports.decodeCookieValue = exports.CookieStorage = void 0;
 var tslib_1 = require("tslib");
+var Buffer = require("buffer").Buffer;
 var global_scope_1 = require("../global-scope");
 var uuid_1 = require("../utils/uuid");
@@ -170,7 +171,7 @@ var CookieStorage = /** @class */ (function () {
-                    str = "".concat(key, "=").concat(btoa(encodeURIComponent(JSON.stringify(value))));
+                    str = "".concat(key, "=").concat(Buffer.from(encodeURIComponent(JSON.stringify(value))).toString('base64'));
@@ -186,7 +186,7 @@
-                    if (globalScope) {
+                    if (globalScope && globalScope.document) {
                         globalScope.document.cookie = str;
@@ -222,7 +222,7 @@
-        return decodeURIComponent(atob(value));
+        return decodeURIComponent(Buffer.from(value, 'base64').toString('binary'));
@@ -232,7 +232,7 @@
-        return decodeURIComponent(atob(decodeURIComponent(value)));
+        return decodeURIComponent(Buffer.from(decodeURIComponent(value), 'base64').toString('binary'));

---

Suggested Fix for the Amplitude Team

1. observers/network.js — Import directly from "../global-scope" instead of ".." to avoid ESM/CJS resolution issues in Metro bundler.
2. storage/cookie.js — Replace btoa/atob with Buffer.from() which is available in React Native via the buffer package, or add a fallback for non-browser environments.
3. storage/cookie.js — Add a globalScope.document guard before accessing document.cookie to prevent crashes in environments without a DOM.

---

This issue was created with the help of patch-package.

[Mercy811]

Hi @inaam-ullah, could you provide steps to reproduce this issue? It would help to have a minimal example for reproduction and Metro version. Are these real metro build errors or patch package static code analysis?

observers/network.js imports from ".." (the package root). In React Native, Metro resolves this to the ESM version (lib/esm/index.js) instead of CJS,

This doesn't seem right. The code below /node_modules/@amplitude/analytics-core/lib/cjs/observers/network.js suggests metro should resolves to cjs.

For the second and third one, tree shaking should delete unused code technically, so I need to reproduce these to better understand why these issues happen

[inaam-ullah]

@amplitude/analytics-core — React Native Hermes Compatibility Issues

Environment

Package	Version
react-native	0.73.6
JS Engine	Hermes
Metro	0.80.12
@amplitude/analytics-core	2.39.0
@amplitude/analytics-react-native	1.4.11
@amplitude/plugin-session-replay-react-native	0.4.2

---

Are these real runtime errors or patch-package static code analysis?

These are real runtime errors on a physical device, logged by Amplitude's own catch blocks. Not static analysis.

---

Steps to Reproduce

1. Create a React Native 0.73.6 project with Hermes enabled
2. Install dependencies:

yarn add @amplitude/analytics-react-native@1.4.11 @amplitude/plugin-session-replay-react-native@0.4.2

3. Call amplitude.init(apiKey) on app startup
4. Run on iOS or Android with Hermes engine

---

Steps:

1. Install the above packages in a React Native project with Hermes enabled
2. Call amplitude.init(API_KEY) on app startup
3. Run on a physical device or simulator with Hermes

Errors observed in order:

TypeError: 0, __1.getGlobalScope is not a function (it is undefined), js engine: hermes

Amplitude Logger [Error]: Failed to set cookie for key: AMP_TEST_xxxx. Error: Property 'btoa' doesn't exist

Amplitude Logger [Error]: Failed to set cookie for key: AMP_TEST_xxxx. Error: Cannot set property 'cookie' of undefined

---

On your point about observers/network.js resolving to CJS

You're right to flag this — I don't know exactly why __1.getGlobalScope was undefined at runtime. The file is inside /lib/cjs/ so require("..") should resolve to /lib/cjs/index.js. I cannot confirm Metro was resolving to ESM — that was my assumption. What I can confirm is:

• grep -r "0, __1.getGlobalScope" pointed to exactly this file as the crash source
• Changing require("..") to require("../global-scope") fixed the crash

The actual root cause of why __1.getGlobalScope was undefined is unclear and would need further investigation to confirm.

---

On tree shaking for btoa/atob and document.cookie

These errors only appeared after amplitude.init() was called, so the cookie storage code was definitely being executed, not tree-shaken. Amplitude's CookieStorage.isEnabled() runs as part of initialization to test which storage backend is available, which is when these errors surfaced.

[daniel-graham-amplitude]

Thanks for reporting this @inaam-ullah great reproduction steps and details. I have fixes incoming for this.