/enable-worklets-bundle-mode

name: enable-worklets-bundle-mode
description:
  Enable react-native-worklets Bundle Mode (imports inside worklets, third party libraries on worklet runtimes) in an Expo, RN
  CLI or brownfield React Native app, including the mandatory metro/metro-runtime patches. Use when the user asks to enable
  Bundle Mode, wants to import npm libraries inside worklets or offload JS code to worklet runtimes, or hits "Failed to get the
  SHA-1" errors in a worklets Bundle Mode project / missing Fast Refresh for worklet code. Covers enabling only — not disabling;
  upgrades react-native-worklets to a compatible version when needed, but never installs it from scratch and never touches
  Reanimated.
compatibility: Requires network access to raw.githubusercontent.com and api.github.com to fetch metro patches
metadata:
  author: Tomasz Żelawski
  version: 1.0.0

Enable Worklets Bundle Mode

Bundle Mode lets worklets access the entire JS bundle (imports inside worklets, etc.). Stable since `react-native-worklets` 0.10.0. Official setup docs: https://docs.swmansion.com/react-native-worklets/docs/bundleMode/setup

Bundle Mode has **three** parts: the babel plugin option, the metro config helper, and the metro + metro-runtime patches. The patches are mandatory - the docs label them "recommended", but without them DX is very poor.

Reference implementation: https://github.com/software-mansion-labs/Bundle-Mode-showcase-app

0. Detect current state and environment

Bundle Mode is already ON when all three hold:

• `babel.config.js`: `react-native-worklets/plugin` has `bundleMode: true`.
• `metro.config.js`: imports from `react-native-worklets/bundleMode` (`bundleModeMetroConfig` or `getBundleModeMetroConfig`).
• Patches applied — layout-aware check (hoisted, pnpm isolated, and workspace layouts; run at the workspace root):

`find node_modules -path '*metro/src/node-haste/DependencyGraph.js' -exec grep -l react-native-worklets {} +` and `find node_modules -path '*metro-runtime/src/modules/HMRClient.js' -exec grep -l __workletsModuleProxy {} +` each match at least one file. The copy that matters is the one `react-native` resolves — nested under `node_modules/react-native/` if present there.

If all three hold, report that Bundle Mode is already enabled and stop. If only some hold, that's a partial (broken) setup — report which parts are missing, then complete them with the steps below.

Environment facts you need:

• Confirm `react-native-worklets` is a dependency. If it's missing entirely, stop and tell the user — this skill upgrades

worklets when needed but does not introduce it to an app.

• Bundle Mode needs worklets >= 0.10.0. If the installed version is older, upgrade it to the newest applicable version:

1. Read the installed `react-native` and (if present) `react-native-reanimated` versions. 2. Fetch both compatibility tables and pick the HIGHEST worklets minor that is (a) compatible with the app's RN version per https://docs.swmansion.com/react-native-worklets/docs/guides/compatibility and (b) accepted by the installed reanimated minor per https://docs.swmansion.com/react-native-reanimated/docs/guides/compatibility/ — reanimated pins narrow worklets ranges (e.g. 4.5.x accepts 0.10.x–0.11.x while 4.3.x only accepts 0.8.x), so both tables must agree on the pick. 3. If the best version satisfying both is still < 0.10.0 (old reanimated), stop and explain: Bundle Mode requires a reanimated upgrade first, and that is the user's decision — never upgrade reanimated yourself. 4. Install the picked version with the detected package manager (`npx expo install react-native-worklets@{ver}` on Expo, plain add elsewhere), then re-check the resolved version before continuing.

• Detect the package manager from the lockfile: `yarn.lock` (Yarn 2+ berry when `packageManager: yarn@2+` is set or `.yarnrc.yml`

with `yarnPath`/`nodeLinker` exists, otherwise Yarn 1 classic), `package-lock.json` (npm), `bun.lockb` / `bun.lock` (bun), `pnpm-lock.yaml` (pnpm). In a workspace repo look for the lockfile upward from the app dir — patch registration happens at the workspace root.

• Get the **installed metro version** — patches are version-specific:

  node -e "console.log(require('metro/package.json').version)"
  node -e "console.log(require('metro-runtime/package.json').version)"

Under pnpm's isolated layout these `require`s fail with MODULE_NOT_FOUND — use `pnpm why metro` / `pnpm why metro-runtime`, or read the `version` field of the `package.json` next to the files located by the find commands above.

• Is it Expo or RN community CLI? (Different metro helper — see step 2.) An Expo app may have no `babel.config.js` /

`metro.config.js` at all — that's normal, not a broken state; steps 1–2 generate them.

• Does another library remap the bare `react-native` specifier in `metro.config.js`? Check for uniwind

(`grep -ns "uniwind" metro.config.js package.json`); NativeWind is reported to do the same. If present, the plain step 2 setup crashes the app at startup — use [references/uniwind-remap-workaround.md](references/uniwind-remap-workaround.md) in step 2 instead.

1. Babel plugin

In `babel.config.js`, add the worklets plugin with `bundleMode: true`. `strictGlobal: true` is optional but recommended by the docs.

If the worklets plugin is already present, just add the options to it — do not add a second copy. The plugin should stay last in the `plugins` array, and the options go on the plugin entry, never on a preset.

Always use the typed-const form shown below, including when merging into an existing config: declare `workletsPluginOptions` with the `/** @type {import('react-native-worklets/plugin').PluginOptions} */` JSDoc annotation and reference it from the plugin entry — do not inline an untyped options object. Keep the JSDoc line even in codebases with a no-comments convention: it is a type annotation (editor completion + typo checking for the opti