feat:unified withStorybook wrapper for entrypoint-swapping

[Copilot]

Tracked by storybookjs/storybook#34276 ("Easy React Native Setup")
Companion PR: storybookjs/storybook#34333 (CLI init overhaul, codemods, automigrations)
Closes #873 (deviceAddons)
Documentation PR: storybookjs/react-native#877

What this does

This PR adds a bundler-agnostic withStorybook wrapper at @storybook/react-native/withStorybook that introduces entry-point swapping as the new recommended way to run Storybook for React Native — matching the mental model of Storybook for Web, where Storybook runs as its own entry point rather than being deeply integrated into the user's app.

It also introduces the deviceAddons config property, separating on-device addons from the addons array to prevent CriticalPresetLoadError during server-side operations like extract.

Entry-point swapping

The new withStorybook wrapper:

• Auto-detects whether the project uses Metro or Re.Pack and delegates accordingly.
• Swaps the app entry point for .rnstorybook/index when STORYBOOK_ENABLED=true is set — no changes to App.tsx required.
• Is a strict no-op when STORYBOOK_ENABLED is not set — zero Storybook code in the production bundle.
• Reads configuration from environment variables (STORYBOOK_ENABLED, STORYBOOK_WS_HOST, STORYBOOK_WS_PORT, STORYBOOK_WS_SECURED, STORYBOOK_SERVER, STORYBOOK_DISABLE_UI), so the same metro config works for all environments.
• Auto-injects WebSocket host/port into the generated storybook.requires file, eliminating the need to manually match config between withStorybook and getStorybookUI.

The existing ./metro/withStorybook and ./repack/withStorybook exports are completely untouched and remain fully supported for projects using the in-app integration approach.

deviceAddons

On-device addons (like @storybook/addon-ondevice-controls) contain React Native code that can't be evaluated in Node.js. When listed in addons, Storybook Core tries to load them as presets during operations like extract, which fails. The new deviceAddons property ensures they're only loaded at runtime on the device.

const main: StorybookConfig = {
  stories: ['../components/**/*.stories.?(ts|tsx|js|jsx)'],
  deviceAddons: [
    '@storybook/addon-ondevice-controls',
    '@storybook/addon-ondevice-actions',
  ],
};

Backwards compatible — addons still works and a console warning guides users to migrate. The companion PR (storybookjs/storybook#34333) includes an automigration (rn-ondevice-addons-to-device-addons) that handles this automatically via npx storybook automigrate.

How it works together

This PR (react-native repo) provides the runtime bundler wrapper. The companion PR (storybook repo) provides the CLI tooling:

Concern	This PR	storybookjs/storybook#34333
Bundler-agnostic withStorybook	✅ Implementation	—
Entry-point swapping	✅ Metro resolver + Re.Pack plugin	—
Env var support	✅ Runtime reading	—
deviceAddons type + runtime	✅ StorybookConfig type, generate.js	—
storybook init for RN	—	✅ Codemod, entrypoint generation, scripts
deviceAddons automigration	—	✅ rn-ondevice-addons-to-device-addons
Metro config codemod	—	✅ AST-based withStorybook() wrapping

Manual verification

Existing withStorybook (backwards compatibility)

Upgraded two existing projects to the canary release of this branch to verify the legacy ./metro/withStorybook path is unaffected:

• React Native CLI project — upgraded to canary, confirmed existing setup works unchanged.
• Expo project — upgraded to canary, confirmed existing setup works unchanged.

Both projects continued to function correctly with their existing metro config and in-app Storybook integration, confirming zero regressions.

npx storybook init CLI

Tested npx storybook@0.0.0-pr-34333-sha-865b50bc init in a fresh Expo project:

• ✅ .rnstorybook/index.ts generated correctly.
• ✅ metro.config.js wrapped with withStorybook() using the bundler-agnostic import.
• ✅ storybook:ios and storybook:android scripts added to package.json.
• ⚠️ The CLI currently pulls main.ts (and other templates) from the latest published version of @storybook/react-native, not from the canary. This means the generated main.ts won't have deviceAddons until this PR is released. This will resolve itself once we publish the minor release.

npx storybook automigrate

Verified that npx storybook@0.0.0-pr-34333-sha-865b50bc automigrate correctly moves on-device addons from addons → deviceAddons in an existing project's .rnstorybook/main.ts.

Release plan

Targeting release as a new minor version this week (v10.4), alongside:

• The companion Storybook core PR (storybookjs/storybook#34333)
• Documentation updates PR (storybookjs/react-native#877)

Test coverage

• 39 tests in @storybook/react-native (unit tests for withStorybook, enhanceMetroConfig, enhanceRepackConfig, entry-point resolution, env var handling).
• 14 tests in the tests package (story generation snapshots).
• All passing ✅

[changeset-bot]

🦋 Changeset detected

Latest commit: 7960793

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 9 packages

Name	Type
@storybook/react-native	Minor
@storybook/react-native-ui	Minor
@storybook/react-native-ui-lite	Minor
@storybook/react-native-ui-common	Minor
@storybook/react-native-theming	Minor
@storybook/addon-ondevice-actions	Minor
@storybook/addon-ondevice-backgrounds	Minor
@storybook/addon-ondevice-controls	Minor
@storybook/addon-ondevice-notes	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[ndelangen]

@copilot, can you try again? It looks like you had some internal error.

[Copilot]

@copilot, can you try again? It looks like you had some internal error.

Implemented M4 in commits a889fb4 and 537de98. The changes add:

1. resolveEntryPoint() - detects app entry point for Expo (package.json#main), Expo Router (expo-router/entry), and RN CLI (index.js fallback)
2. Entry-point swapping - when STORYBOOK_ENABLED=true, the Metro resolver redirects the app entry to .rnstorybook/index. Strict no-op when not set.
3. Websocket env overrides - STORYBOOK_WS_HOST, STORYBOOK_WS_PORT, STORYBOOK_WS_SECURED environment variables
4. 15 new tests covering all new functionality, all 33 tests passing

[ndelangen]

@copilot Did you catch that we'd need backwards support?

I think it'd be best if we created 2 separate withStorybook config wrappers, so that 1 does entrypoint-swapping, and the other acts as the backwards support way.

[ndelangen]

@copilot I'm aiming for the new config wrapper to be a single agnostic one, exposed as @storybook/react-native/withStorybook.

This exports a single named export (withStorybook) which should support both metro and repack.
This way SB init command doesn't need to know about this complaexity, and can always generate the same thing.

The types of this function should be like so:
function<T>: T

Though internally we should try to be somewhat type-safe, but externally it's not exposed.

[Copilot]

@copilot I'm aiming for the new config wrapper to be a single agnostic one, exposed as @storybook/react-native/withStorybook.

This exports a single named export (withStorybook) which should sup...

Added a unified withStorybook<T>(config: T, options?): T at @storybook/react-native/withStorybook in commit 7e754f5. It auto-detects Metro vs Repack from the config object (checks for transformer property) and delegates accordingly:

• Metro → withStorybookSwap (entry-point swapping + ws env overrides)
• Repack/Rspack/Webpack → adds StorybookPlugin to config.plugins with ws env overrides

Usage is identical regardless of bundler:

const { withStorybook } = require('@storybook/react-native/withStorybook');
module.exports = withStorybook(config);

The existing ./metro/withStorybook and ./repack/withStorybook exports remain for direct access.

[ndelangen]

@copilot the previously existing ./metro/withStorybook and ./repack/withStorybook ARE the backwards support, and should remain completely untouched.

The @storybook/react-native/withStorybook should be the new entrypoint swapping config wrapper, can you check if that's what you did?

[dannyhw]

• I believe there is still some unresolved issue regarding resolving the expo router entry point in node_modules when node_modules is not in project root (monorepo), i believe we should solve this before moving forward.
• When enabled is explicitly false, the new @storybook/react-native/withStorybook wrapper currently returns the original Metro config, so projects that still import .rnstorybook from their app entry keep rendering Storybook instead of being stubbed like the existing Metro wrapper does. I think it would still be useful to stub out storybook when its disabled in order to ensure its removed from the bundle.
• theres not a easy way to try it in the example app still
• lite mode should still be respected so that users can opt out of the full dependency list when using the lite-ui
• repack config should done using a plugin not with a wrapper imho

Please add something along these lines would make the Expo example easy to exercise locally:

const useNewStorybookWrapper = process.env.EXPO_PUBLIC_STORYBOOK_NEW_WRAPPER === 'true';
const { withStorybook } = useNewStorybookWrapper
  ? require('@storybook/react-native/withStorybook')
  : require('@storybook/react-native/metro/withStorybook');

{
  "storybook:new-wrapper": "EXPO_PUBLIC_STORYBOOK_ENABLED=true EXPO_PUBLIC_STORYBOOK_NEW_WRAPPER=true expo start",
  "storybook:new-wrapper:disabled": "EXPO_PUBLIC_STORYBOOK_NEW_WRAPPER=true expo start"
}

For the implementation, the disabled Metro path could be closer to the existing metro/withStorybook behavior: if enabled was explicitly set false, wrap the Metro resolver so storybook/@storybook requests become empty modules and .rnstorybook/index.(ts|tsx|js|jsx) resolves to the stub. If there is no explicit enable signal at all, keep the current strict no-op behavior for the new wrapper.

For example, withStorybook could pass the existing enabled state into the Metro enhancer and let the enhancer apply the disabled resolver behavior when enabled === false:

const hasExplicitEnabled = process.env.STORYBOOK_ENABLED != null || options.enabled != null;
const enabled = envVariableToBoolean(process.env.STORYBOOK_ENABLED, options.enabled ?? false);

if (!enabled && !hasExplicitEnabled) {
  return config;
}

if (isMetroConfig(config)) {
  return enhanceMetroConfig(config, { enabled, configPath });
}

Then the enhancer can branch on enabled === false while preserving its current swap behavior:

export function enhanceMetroConfig(config: MetroConfig, options: EnhanceMetroOptions = {}) {
  const { swap, enabled = true, configPath } = options;
  const shouldStubStorybook = enabled === false;
  const normalizedConfigPath = configPath ? path.resolve(configPath) : undefined;
  const stubPath = path.resolve(
    __dirname,
    __dirname.includes(path.sep + 'src') ? './stub.tsx' : './stub.js'
  );

  return {
    ...config,
    resolver: {
      ...config.resolver,
      resolveRequest: (context, moduleName, platform) => {
        const resolveFunction = config.resolver?.resolveRequest ?? context.resolveRequest;

        if (shouldStubStorybook && (moduleName.startsWith('storybook') || moduleName.startsWith('@storybook'))) {
          return { type: 'empty' };
        }

        if (platform !== 'web' && (moduleName === 'tty' || moduleName === 'os')) {
          return { type: 'empty' };
        }

        const resolved = resolveFunction(context, moduleName, platform);

        if (shouldStubStorybook && resolved.filePath && normalizedConfigPath) {
          const resolvedFilePath = path.resolve(resolved.filePath);
          const isConfigIndex = ['index.ts', 'index.tsx', 'index.js', 'index.jsx'].some(
            (file) => resolvedFilePath === path.join(normalizedConfigPath, file)
          );

          if (isConfigIndex) {
            return { filePath: stubPath, type: 'sourceFile' };
          }

          if (resolvedFilePath.startsWith(normalizedConfigPath + path.sep)) {
            return { type: 'empty' };
          }
        }

        return resolved;
      },
    },
  };
}

[dannyhw]

after thinking it through I'm not sure a unified wrapper is the right direction since repack is quite different, repack builds on webpack/rspack and uses plugins for extended behaviour, we only wrap metro config because of its lacking support for plugins or other ways to extend metro behaviour.

it would likely be better to just extract reusable code and provide a repack plugin like we currently do but updated for the expected new flow (or exclude it entirely from this initial version)

[ndelangen]

@dannyhw considering how the new setup needs a differently formatted index.tsx file (a proper entrypoint) I figured it would be better to create a separate example.

[dannyhw]

sounds like a good choice, thanks for that. I will take a look soon.

[dannyhw]

Its really nice to have the entrypoint just magically swap, can't wait to see it with the new init changes too