@revenuecat/purchases-js-hybrid-mappings (~512 KB web SDK) included in iOS/Android bundles

[salvooddsjam]

Problem

react-native-purchases statically requires @revenuecat/purchases-js-hybrid-mappings (v17.10.0) via dist/browser/nativeModule.js, which gets bundled into iOS and Android JavaScript bundles even though it is never executed on native platforms.

This adds ~512 KB of dead code (Svelte runtime, DOM manipulation, RevenueCat web billing SDK) to every native app using this library.

Root cause

1. dist/purchases.js unconditionally requires ./browser/nativeModule at the module level
2. browser/nativeModule.js does require("@revenuecat/purchases-js-hybrid-mappings")
3. Metro bundles all static require() calls regardless of runtime conditions
4. The shouldUseBrowserMode() guard only prevents execution, not bundling

Additionally, @revenuecat/purchases-js-hybrid-mappings/package.json has a browser field but no react-native field, so Metro resolves the UMD browser build instead of main:

{
  "main": "dist/index.js",
  "browser": "dist/index.umd.js"
}

Impact

The vast majority of react-native-purchases users are building native iOS/Android apps and do not use web billing. They are paying a ~512 KB bundle size penalty for a feature they never use.

Current workaround

We are using a Metro resolveRequest override to return { type: "empty" } for this package on non-web platforms:

// metro.config.js
if (
  platform !== "web" &&
  (moduleName === "@revenuecat/purchases-js-hybrid-mappings" ||
    moduleName.startsWith("@revenuecat/purchases-js-hybrid-mappings/"))
) {
  return { type: "empty" };
}

This is safe because shouldUseBrowserMode() guarantees the browser code path is never reached on native, but it should not be necessary.

Suggested solutions

Any of these would fix it for all users without manual workarounds:

1. Lazy require: Change browser/nativeModule.js to use require() inside the functions instead of at the top level, so Metro can tree-shake it when unused
2. Conditional require: Only require("@revenuecat/purchases-js-hybrid-mappings") inside the if (shouldUseBrowserMode()) branch in purchases.js
3. Add a react-native field to @revenuecat/purchases-js-hybrid-mappings/package.json pointing to a minimal stub for native platforms
4. Add exports with conditions to @revenuecat/purchases-js-hybrid-mappings/package.json:

   "exports": {
     ".": {
       "react-native": "./dist/stub.js",
       "browser": "./dist/index.umd.js",
       "default": "./dist/index.js"
     }
   }

Option 1 or 2 would be the least breaking change and would benefit every React Native user immediately.

Environment

• react-native-purchases: 9.5.4
• @revenuecat/purchases-js-hybrid-mappings: 17.10.0
• Metro bundler (via Expo SDK 55)
• Platform: iOS / Android

[KitTheRevenueCat]

This looks like a legit bundle-size footgun, and your Metro workaround makes sense for native-only apps.

One small thing I’d add for anyone trying to verify the impact locally: after adding the resolveRequest empty-module stub, compare the native JS bundle size before/after with a production bundle build instead of relying on dev mode. Metro will still happily include top-level static require() dependencies even if shouldUseBrowserMode() never executes on iOS/Android, so the key thing to measure is the release bundle artifact.

I don’t think a GitHub workaround should be the long-term answer here though. Option 1 or 2 from your issue seems like the cleanest SDK-side fix because it removes the dead native dependency without asking every app to patch Metro config.

If it helps anyone landing here from search, the underlying pattern is: runtime guards prevent execution, but they do not prevent Metro from bundling statically required modules on native.