feat:unified withStorybook wrapper for entrypoint-swapping

.changeset/add-device-addons.md

@@ -0,0 +1,5 @@
+---
+'@storybook/react-native': minor
+---
+
+Add `deviceAddons` property to `StorybookConfig` for separating on-device addons from core addons. On-device addons listed in `deviceAddons` are only consumed at runtime by the code generator, not evaluated as presets by Storybook Core. This prevents `extract` failures caused by loading React Native code in a Node.js context. Backwards compatible: addons in the `addons` field continue to work.

.changeset/unified-withstorybook-wrapper.md

@@ -0,0 +1,5 @@
+---
+'@storybook/react-native': minor
+---
+
+Add unified bundler-agnostic withStorybook wrapper at @storybook/react-native/withStorybook

examples/expo-example/.rnstorybook/main.ts

@@ -10,13 +10,13 @@ const main: StorybookConfig = {
       files: '**/*.stories.?(ts|tsx|js|jsx)',
     },
   ],
-  addons: [
+  deviceAddons: [
+    'storybook-addon-deep-controls',
+    './local-addon-example',
     { name: '@storybook/addon-ondevice-controls' },
     '@storybook/addon-ondevice-actions',
     // '@storybook/addon-ondevice-backgrounds',
     '@storybook/addon-ondevice-notes',
-    'storybook-addon-deep-controls',
-    './local-addon-example',
   ],
   reactNative: {
     playFn: false,

examples/expo-example/.rnstorybook/storybook.requires.ts

@@ -2,11 +2,12 @@
 /// <reference types="@storybook/react-native/metro-env" />
 import { start, updateView, View, type Features } from '@storybook/react-native';
 
+
+import "storybook-addon-deep-controls/register";
+import "./local-addon-example/register";
 import "@storybook/addon-ondevice-controls/register";
 import "@storybook/addon-ondevice-actions/register";
 import "@storybook/addon-ondevice-notes/register";
-import "storybook-addon-deep-controls/register";
-import "./local-addon-example/register";
 
 const normalizedStories = [
   {
@@ -64,7 +65,7 @@ const annotations = [
 
 globalThis.STORIES = normalizedStories;
 globalThis.STORYBOOK_WEBSOCKET = {
-  host: '192.168.1.171',
+  host: '192.168.86.21',
   port: 7007,
   secured: false,
 };

examples/expo-new-wrapper-example/.expo/README.md

@@ -0,0 +1,13 @@
+> Why do I have a folder named ".expo" in my project?
+
+The ".expo" folder is created when an Expo project is started using "expo start" command.
+
+> What do the files contain?
+
+- "devices.json": contains information about devices that have recently opened this project. This is used to populate the "Development sessions" list in your development builds.
+- "settings.json": contains the server configuration that is used to serve the application manifest.
+
+> Should I commit the ".expo" folder?
+
+No, you should not share the ".expo" folder. It does not contain any information that is relevant for other developers working on the project, it is specific to your machine.
+Upon project creation, the ".expo" folder is already added to your ".gitignore" file.

examples/expo-new-wrapper-example/.expo/devices.json

@@ -0,0 +1,3 @@
+{
+  "devices": []
+}

examples/expo-new-wrapper-example/.rnstorybook/index.tsx

@@ -0,0 +1,18 @@
+// This file is the app's bundle entry when Storybook is enabled.
+// `withStorybook` swaps the resolver from the project's `index.js` to this
+// file, so it must register a root component itself. See ../metro.config.js
+// and ../README.md for the full picture.
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { registerRootComponent } from 'expo';
+
+import { view } from './storybook.requires';
+
+const StorybookUIRoot = view.getStorybookUI({
+  shouldPersistSelection: true,
+  storage: {
+    getItem: AsyncStorage.getItem,
+    setItem: AsyncStorage.setItem,
+  },
+});
+
+registerRootComponent(StorybookUIRoot);

examples/expo-new-wrapper-example/.rnstorybook/main.ts

@@ -0,0 +1,12 @@
+import type { StorybookConfig } from '@storybook/react-native';
+
+const main: StorybookConfig = {
+  stories: ['../components/**/*.stories.?(ts|tsx|js|jsx)'],
+  deviceAddons: [
+    { name: '@storybook/addon-ondevice-controls' },
+    '@storybook/addon-ondevice-actions',
+  ],
+  framework: '@storybook/react-native',
+};
+
+export default main;

examples/expo-new-wrapper-example/.rnstorybook/preview.tsx

@@ -0,0 +1,16 @@
+import type { Preview } from '@storybook/react-native';
+
+const preview: Preview = {
+  parameters: {
+    actions: { argTypesRegex: '^on[A-Z].*' },
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/,
+      },
+    },
+    layout: 'padded',
+  },
+};
+
+export default preview;

examples/expo-new-wrapper-example/.rnstorybook/storybook.requires.ts

@@ -0,0 +1,48 @@
+/* do not change this file, it is auto generated by storybook. */
+/// <reference types="@storybook/react-native/metro-env" />
+import { start, updateView, View, type Features } from '@storybook/react-native';
+
+import '@storybook/addon-ondevice-controls/register';
+import '@storybook/addon-ondevice-actions/register';
+
+const normalizedStories = [
+  {
+    titlePrefix: '',
+    directory: './components',
+    files: '**/*.stories.?(ts|tsx|js|jsx)',
+    importPathMatcher:
+      /^\.(?:(?:^|\/|(?:(?:(?!(?:^|\/)\.).)*?)\/)(?!\.)(?=.)[^/]*?\.stories\.(?:ts|tsx|js|jsx)?)$/,
+    req: require.context(
+      '../components',
+      true,
+      /^\.(?:(?:^|\/|(?:(?:(?!(?:^|\/)\.).)*?)\/)(?!\.)(?=.)[^/]*?\.stories\.(?:ts|tsx|js|jsx)?)$/
+    ),
+  },
+];
+
+declare global {
+  var view: View;
+  var STORIES: typeof normalizedStories;
+  var STORYBOOK_WEBSOCKET: { host?: string; port?: number; secured?: boolean } | undefined;
+  var FEATURES: Features;
+}
+
+const annotations = [require('./preview'), require('@storybook/react-native/preview')];
+
+globalThis.STORIES = normalizedStories;
+
+module?.hot?.accept?.();
+
+const options = {};
+
+if (!globalThis.view) {
+  globalThis.view = start({
+    annotations,
+    storyEntries: normalizedStories,
+    options,
+  });
+} else {
+  updateView(globalThis.view, annotations, normalizedStories, options);
+}
+
+export const view: View = globalThis.view;

examples/expo-new-wrapper-example/App.tsx

@@ -0,0 +1,17 @@
+import { SafeAreaView, Text, View } from 'react-native';
+
+export default function App() {
+  return (
+    <SafeAreaView style={{ flex: 1 }}>
+      <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center', padding: 24 }}>
+        <Text style={{ fontSize: 18, fontWeight: '600', marginBottom: 8 }}>
+          Real app placeholder
+        </Text>
+        <Text style={{ textAlign: 'center', color: '#555' }}>
+          Storybook is disabled. Run `pnpm storybook` (sets EXPO_PUBLIC_STORYBOOK_ENABLED=true) to
+          launch the on-device Storybook UI instead.
+        </Text>
+      </View>
+    </SafeAreaView>
+  );
+}

examples/expo-new-wrapper-example/README.md

@@ -0,0 +1,66 @@
+# expo-new-wrapper-example
+
+Minimal Expo app that exercises the new universal `withStorybook` wrapper at
+[`@storybook/react-native/withStorybook`](../../packages/react-native/src/withStorybook.ts).
+
+It is intentionally separate from [`expo-example`](../expo-example) so the new
+wrapper's behavior can be exercised in isolation, without rozenite, secured
+websockets, EAS, or other extras getting in the way.
+
+## How it works
+
+The new wrapper performs an entry-point swap at the Metro resolver level. When
+Storybook is enabled, Metro asks for the project entry (`index.js`) and the
+resolver redirects it to `.rnstorybook/index.tsx`.
+
+```mermaid
+flowchart LR
+  subgraph enabled [pnpm storybook]
+    Enabled_indexJs[index.js] -->|"swap (resolver)"| SBIndex[.rnstorybook/index.tsx]
+    SBIndex --> RegSB["registerRootComponent(StorybookUIRoot)"]
+  end
+  subgraph disabled [pnpm start]
+    Disabled_indexJs[index.js] --> AppTsx[App.tsx]
+    AppTsx --> RegApp["registerRootComponent(App)"]
+  end
+```
+
+This means `.rnstorybook/index.tsx` becomes the bundle entry, so it is
+responsible for calling `registerRootComponent` itself. There is no magic
+shim — what you see is what gets executed.
+
+When Storybook is disabled, the wrapper returns the Metro config unchanged.
+`index.js` -> `App.tsx` runs as the real (placeholder) app, and Storybook is
+not in the bundle because nothing imports it.
+
+## Scripts
+
+- `pnpm storybook` — sets `EXPO_PUBLIC_STORYBOOK_ENABLED=true` and starts Expo.
+  Metro swaps the entry to `.rnstorybook/index.tsx` and the on-device Storybook
+  UI is shown.
+- `pnpm ios` / `pnpm android` — same as `pnpm storybook`, targeted at a
+  simulator.
+- `pnpm start` — plain `expo start`, no env var. The placeholder `App.tsx`
+  renders.
+- `pnpm check` — TypeScript check.
+
+## Migration notes
+
+Compared to the old `@storybook/react-native/metro/withStorybook`, two patterns
+have changed in this example:
+
+1. `.rnstorybook/index.tsx` is now a bootstrap entry. It must call
+   `registerRootComponent` (Expo) or `AppRegistry.registerComponent` (bare RN).
+   It does not need to default-export a component anymore.
+2. `App.tsx` does not import `.rnstorybook`. Reaching Storybook is the
+   wrapper's job, not the app's. As a side benefit, `pnpm start` honestly
+   excludes Storybook from the bundle.
+
+## What is not covered here
+
+- Re.Pack — the universal wrapper's `enhanceRepackConfig` branch is not
+  exercised. A separate Re.Pack example is the natural follow-up.
+- `expo-router` — `resolveEntryPoint`'s `expo-router/entry` detection is also
+  unexercised here. Add an `expo-router` variant if you want to cover it.
+- The wider feature set demoed in `expo-example` (secured websockets, MCP,
+  rozenite, screenshot testing, web). Use `expo-example` for those.

examples/expo-new-wrapper-example/app.json

@@ -0,0 +1,19 @@
+{
+  "name": "ExpoNewWrapperExample",
+  "slug": "expo-new-wrapper-example",
+  "version": "1.0.0",
+  "orientation": "portrait",
+  "scheme": "storybook-newwrapper",
+  "userInterfaceStyle": "automatic",
+  "newArchEnabled": true,
+  "ios": {
+    "bundleIdentifier": "com.storybook.newwrapperexample"
+  },
+  "android": {
+    "package": "com.storybook.newwrapperexample",
+    "edgeToEdgeEnabled": true
+  },
+  "experiments": {
+    "tsconfigPaths": true
+  }
+}

examples/expo-new-wrapper-example/babel.config.js

@@ -0,0 +1,7 @@
+module.exports = function (api) {
+  api.cache(true);
+  return {
+    presets: [['babel-preset-expo']],
+    plugins: ['react-native-worklets/plugin'],
+  };
+};

examples/expo-new-wrapper-example/components/Button/Button.stories.tsx

@@ -0,0 +1,27 @@
+import type { Meta, StoryObj } from '@storybook/react-native';
+import { fn } from 'storybook/test';
+
+import { Button } from './Button';
+
+const meta = {
+  component: Button,
+  args: {
+    onPress: fn(),
+  },
+} satisfies Meta<typeof Button>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    title: 'Press me',
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    title: 'Press me',
+    disabled: true,
+  },
+};

examples/expo-new-wrapper-example/components/Button/Button.tsx

@@ -0,0 +1,25 @@
+import { Pressable, Text, type GestureResponderEvent } from 'react-native';
+
+export interface ButtonProps {
+  title: string;
+  onPress?: (event: GestureResponderEvent) => void;
+  disabled?: boolean;
+}
+
+export function Button({ title, onPress, disabled }: ButtonProps) {
+  return (
+    <Pressable
+      onPress={onPress}
+      disabled={disabled}
+      style={({ pressed }) => ({
+        paddingVertical: 12,
+        paddingHorizontal: 20,
+        borderRadius: 8,
+        backgroundColor: disabled ? '#aaa' : pressed ? '#1d4ed8' : '#2563eb',
+        alignItems: 'center',
+      })}
+    >
+      <Text style={{ color: 'white', fontWeight: '600' }}>{title}</Text>
+    </Pressable>
+  );
+}

examples/expo-new-wrapper-example/components/HelloText/HelloText.stories.tsx

@@ -0,0 +1,22 @@
+import type { Meta, StoryObj } from '@storybook/react-native';
+
+import { HelloText } from './HelloText';
+
+const meta = {
+  component: HelloText,
+} satisfies Meta<typeof HelloText>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Hello: Story = {
+  args: {
+    message: 'Hello, Storybook',
+  },
+};
+
+export const Goodbye: Story = {
+  args: {
+    message: 'Goodbye, Storybook',
+  },
+};

examples/expo-new-wrapper-example/components/HelloText/HelloText.tsx

@@ -0,0 +1,9 @@
+import { Text } from 'react-native';
+
+export interface HelloTextProps {
+  message: string;
+}
+
+export function HelloText({ message }: HelloTextProps) {
+  return <Text style={{ fontSize: 18 }}>{message}</Text>;
+}

examples/expo-new-wrapper-example/index.js

@@ -0,0 +1,5 @@
+import { registerRootComponent } from 'expo';
+
+import App from './App';
+
+registerRootComponent(App);