[Worklets] Bundle Mode: react-native shim breaks with resolvers that remap `react-native` (e.g. uniwind) → infinite NativeModules recursion

[ottob]

Summary

When Worklets Bundle Mode is enabled alongside any Metro resolver that remaps the react-native specifier — e.g. uniwind, which rewrites import 'react-native' → uniwind/components — the app crashes at startup with an infinite recursion:

ERROR  [runtime not ready]: RangeError: Maximum call stack size exceeded (native stack depth)
ERROR  [runtime not ready]: Invariant Violation: "main" has not been registered.

It's a get NativeModules recursion during module initialization, before AppRegistry.registerComponent runs.

Root cause

Bundle Mode's resolver redirects every react-native import to bundleMode/shims/reactNativeShim.js, and the shim obtains the real module with:

module.exports = require('react-native');

This re-requests the bare react-native specifier, which re-enters the resolver chain. Bundle Mode's own guard (context.originModulePath !== reactNativeShimPath) prevents self-redirection, but it can't stop another resolver from intercepting the request. uniwind's resolver (which wraps Bundle Mode's) rewrites the shim's require('react-native') → uniwind/components; and uniwind/components' internal require('react-native') is then redirected by Bundle Mode back to the shim. The result is a shim ↔ uniwind/components require cycle that recurses through NativeModules at runtime.

(uniwind does have carve-outs for RN-internal origins, but they key on the path segment /react-native/; the shim lives under /react-native-worklets/, so it isn't recognized. The bug isn't uniwind-specific though — any resolver that remaps the bare react-native specifier triggers it.)

Environment

• react-native-worklets 0.10.0
• react-native 0.86.0, Expo SDK 57, Metro 0.84.4, Hermes
• uniwind 1.10.0 (any react-native-remapping resolver reproduces it)

Repro

1. Expo app with reanimated/worklets + Bundle Mode enabled (per the setup guide).
2. Add uniwind and withUniwindConfig(...) in metro.config.js.
3. Add any worklet, run on a simulator/device → startup recursion crash.

Proposed fix

Have the shim acquire the real module through a worklets-internal sentinel specifier instead of the bare react-native, and resolve that sentinel to the real RN path inside Bundle Mode's resolver. No other resolver matches the sentinel, and Bundle Mode returns a concrete filePath (never re-entering resolution), so the cycle can't form — regardless of resolver ordering. This hardens Bundle Mode against any react-native-remapping setup, not just uniwind.

packages/react-native-worklets/bundleMode/index.js:

@@
   'module',
   'index.js'
 );
+const realReactNativeModuleName = path.posix.join(
+  workletsPackageName,
+  'bundleMode',
+  'realReactNative'
+);
 
 function bundleModeResolveRequest(
   /** @type {any} */ context,
   /** @type {string} */ moduleName,
   /** @type {any} */ platform,
-  /** @type {any} */ userConfigResolveRequest
+  /** @type {any} */ userConfigResolveRequest,
+  /** @type {string} */ realReactNativePath
 ) {
   if (moduleName.startsWith(workletsDirPath)) {
     const fullModuleName = path.join(workletsPackageParentDir, moduleName);
     return { type: 'sourceFile', filePath: fullModuleName };
   }
+  // The react-native shim requires the real react-native through this internal
+  // sentinel specifier instead of the bare 'react-native' specifier, so that
+  // resolvers which remap 'react-native' (e.g. uniwind -> uniwind/components)
+  // cannot intercept it and form a shim <-> replacement require cycle.
+  if (moduleName === realReactNativeModuleName) {
+    return { type: 'sourceFile', filePath: realReactNativePath };
+  }
   if (
     moduleName === 'react-native' &&
     context.originModulePath !== reactNativeShimPath
@@ function getBundleModeMetroConfig(config) {
   config.serializer.createModuleIdFactory = bundleModeCreateModuleIdFactory;
 
+  const realReactNativePath = require.resolve('react-native', {
+    paths: [config.projectRoot || process.cwd()],
+  });
+
   const currentResolveRequest = config?.resolver?.resolveRequest;
   config.resolver.resolveRequest = (context, moduleName, platform) =>
     bundleModeResolveRequest(
       context,
       moduleName,
       platform,
-      currentResolveRequest
+      currentResolveRequest,
+      realReactNativePath
     );

packages/react-native-worklets/bundleMode/shims/reactNativeShim.js:

-module.exports = require('react-native');
+module.exports = require('react-native-worklets/bundleMode/realReactNative');

(The same change would apply to the bundleModeMetroConfig object used by non-Expo projects.)

Validation

Applied this patch to the installed react-native-worklets@0.10.0 in a real Expo 57 + uniwind app: the startup recursion is gone, the app boots, worklets run, and uniwind styling is preserved (app code's react-native → uniwind/components rewrite is untouched — only the shim's own react-native bypasses it).

Happy to send a PR if this approach looks right.

[github-actions]

Hey! 👋

It looks like you've omitted a few important sections from the issue template.

Please complete Description, Steps to reproduce, Snack or a link to a repository, Reanimated version, React Native version and Platforms sections.

[ottob]

Minimal repro (real uniwind): https://github.com/ottob/worklets-bundlemode-rn-remap-repro

Fresh Expo SDK 57 app (RN 0.86, reanimated 4.5.0, worklets 0.10.0, uniwind 1.10.0) with Bundle Mode enabled. metro.config.js layers getBundleModeMetroConfig (inner) then withUniwindConfig (outer) — the same ordering a real app uses. App.tsx has a worklet + uniwind classNames so uniwind's react-native → uniwind/components rewrite is engaged.

bun install
bun ios   # opens in Expo Go; a dev build (npx expo run:ios) crashes the same way

Crashes on launch with the Maximum call stack size exceeded (get NativeModules) recursion. Dropping withUniwindConfig (or disabling Bundle Mode) makes it boot — confirming the interaction.

Two things were needed just to get Bundle Mode to build, in case they're useful signal:

• The metro / metro-runtime 0.84.4 patches from the worklets repo (wired via patchedDependencies) — without the metro one you get Failed to get the SHA-1 for .../react-native-worklets/.worklets/*.js.
• @babel/preset-typescript pinned to 7.x (matching Babel 7 core) — with 8.x the extracted .worklets/*.js keep TypeScript syntax and fail to parse.

[zocario]

Thanks for opening the issue, @ottob. I’m encountering the same problem with NativeWind.

Regarding the memory issue with Hermes v1, it's a bit frustrating to have to enable bundle mode to fix it but not having a way to do it because of incompatibility with those libs.

[chanphiromsok]

fae the same issue using uniwind with bundleMode

[tshmieldev]

Thanks for reporting this issue.
Sadly, we believe that this is not fixable on our end.
Both libraries use shims and have custom resolution logic for react-native, which causes a cycle.
Metro does not provide a way to prevent cycles in the resolution process.
Here is a workaround that worked for us:

config = withUniwindConfig(config, {
  cssEntryFile: './global.css',
  dtsFile: './uniwind-types.d.ts'
})
config = getBundleModeMetroConfig(config)

const uniwindDir = path.dirname(require.resolve('uniwind/package.json')) + path.sep
const realReactNativePath = require.resolve('react-native')
const wrappedResolveRequest = config.resolver.resolveRequest
config.resolver.resolveRequest = (context, moduleName, platform) => {
  if (moduleName === 'react-native' && typeof context.originModulePath === 'string' && context.originModulePath.startsWith(uniwindDir)) {
    return { type: 'sourceFile', filePath: realReactNativePath }
  }
  return (wrappedResolveRequest || context.resolveRequest)(context, moduleName, platform)
}

module.exports = config

This works for most setups. If your setup is non-standard, take care that uniwindDir points to the correct location of the uniwind package,
and that realReactNativePath points to the correct location of react-native in your project.

[gobi-G]

Additional verified workaround from READO:

Environment:

• React Native 0.86.0
• Expo SDK 57
• react-native-worklets 0.10.3
• Uniwind 1.8.0
• Bundle Mode enabled
• resolver order: withUniwindConfig(getBundleModeMetroConfig(config), ...)

We currently patch the Worklets React Native shim to request React Native's concrete entry point instead of the bare specifier:

-module.exports = require('react-native');
+module.exports = require('react-native/index.js');

This avoids re-entering resolvers that specifically remap the bare react-native specifier. With this patch applied, a clean Expo production export completes for both iOS and Android (roughly 9.4k modules per platform).

This is a useful small local workaround, but it depends on React Native's package layout. The sentinel approach proposed in the issue is more general; the maintainer-provided Metro resolver workaround is also safer if that layout assumption is undesirable. Sharing this primarily as another confirmed setup/data point.