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,

package.json

@@ -31,7 +31,7 @@
     "format:check": "prettier --check --experimental-cli .",
     "format:fix": "prettier --write --experimental-cli .",
     "lint": "eslint --cache -c ./eslint.config.js",
-    "lint:fix": "lint --fix",
+    "lint:fix": "pnpm lint --fix",
     "publish:canary": "pnpm changeset publish --tag canary",
     "repo:fix": "sherif --fix -r unsync-similar-dependencies",
     "repo:lint": "sherif -r unsync-similar-dependencies",

packages/react-native/package.json

@@ -19,6 +19,7 @@
   "license": "MIT",
   "exports": {
     ".": "./dist/index.js",
+    "./withStorybook": "./dist/withStorybook.js",
     "./metro/withStorybook": "./dist/metro/withStorybook.js",
     "./repack/withStorybook": "./dist/repack/withStorybook.js",
     "./metro-env": "./metro-env.d.ts",
@@ -47,7 +48,8 @@
     "dev": "npx --yes tsx buildscripts/gendtsdev.ts && tsup --watch",
     "prepare": "rm -rf dist/ && tsup",
     "test": "jest",
-    "test:ci": "jest"
+    "test:ci": "jest",
+    "ws-smoke-server": "node ./scripts/ws-smoke-server.mjs"
   },
   "dependencies": {
     "@storybook/mcp": "^0.6.1",

packages/react-native/scripts/generate.js

@@ -14,6 +14,33 @@ const path = require('path');
 
 const cwd = process.cwd();
 
+const MAIN_ADDONS_DEPRECATION_URL =
+  'https://github.com/storybookjs/react-native/blob/main/MIGRATION.md#deprecating-addons-in-rnstorybook-main';
+
+/**
+ * @param {{ addons?: unknown[] }} main
+ * @param {string} configPath
+ *
+ * @todo Remove support for `main.addons` in a future major version.
+ */
+function warnDeprecatedMainAddonsField(main, configPath) {
+  const addons = main.addons ?? [];
+  if (addons.length === 0) {
+    return;
+  }
+
+  const names = addons
+    .map((addon) => getAddonName(addon))
+    .filter((name) => typeof name === 'string');
+  const list = [...new Set(names)].join(', ');
+  console.warn(
+    `[Storybook React Native] The \`addons\` field in your main config (${configPath}) is deprecated and will be removed in a future major version.\n` +
+      `Move every entry to \`deviceAddons\` instead. That includes on-device UI packages (\`@storybook/addon-ondevice-*\`), other addons you bundle with the app (for example storybook-addon-deep-controls), and local paths such as ./my-addon.\n` +
+      (list ? `Still listed under \`addons\`: ${list}.\n` : '') +
+      `Details: ${MAIN_ADDONS_DEPRECATION_URL}`
+  );
+}
+
 const loadMain = async ({ configPath, cwd }) => {
   try {
     const main = await loadMainConfig({ configDir: configPath, cwd });
@@ -24,12 +51,17 @@ const loadMain = async ({ configPath, cwd }) => {
 
   const mainPathTs = path.resolve(cwd, configPath, `main.ts`);
   const mainPathJs = path.resolve(cwd, configPath, `main.js`);
+  const mainPathCjs = path.resolve(cwd, configPath, `main.cjs`);
   if (fs.existsSync(mainPathTs)) {
     return interopRequireDefault(mainPathTs);
   } else if (fs.existsSync(mainPathJs)) {
     return interopRequireDefault(mainPathJs);
+  } else if (fs.existsSync(mainPathCjs)) {
+    return interopRequireDefault(mainPathCjs);
   } else {
-    throw new Error(`Main config file not found at ${mainPathTs} or ${mainPathJs}`);
+    throw new Error(
+      `Main config file not found at ${mainPathTs}, ${mainPathJs}, or ${mainPathCjs}`
+    );
   }
 };
 
@@ -50,14 +82,27 @@ function getLocalIPAddress() {
   return '0.0.0.0';
 }
 
-async function generate({
-  configPath,
-  useJs = false,
-  docTools = true,
-  host = undefined,
-  port = undefined,
-  secured = false,
-}) {
+/**
+ * @param {{
+ *   configPath: string;
+ *   useJs?: boolean;
+ *   docTools?: boolean;
+ *   host?: string;
+ *   port?: number;
+ *   secured?: boolean;
+ *   disableUI?: boolean;
+ * }} generateOptions
+ */
+async function generate(generateOptions) {
+  const {
+    configPath,
+    useJs = false,
+    docTools = true,
+    host = undefined,
+    port = undefined,
+    secured = false,
+    disableUI = false,
+  } = generateOptions;
   // here we want to get the ip address and pass it to rn storybook so that devices can connect over lan easily
   const channelHost = host === 'auto' ? getLocalIPAddress() : host;
   const storybookRequiresLocation = path.resolve(
@@ -68,6 +113,8 @@ async function generate({
 
   const main = await loadMain({ configPath, cwd });
 
+  warnDeprecatedMainAddonsField(main, configPath);
+
   const storiesSpecifiers = normalizeStories(main.stories, {
     configDir: configPath,
     workingDir: cwd,
@@ -95,7 +142,12 @@ async function generate({
 
   const registeredAddons = [];
 
-  for (const addon of main.addons) {
+  const allAddons = [
+    ...(main.addons ?? []), // TODO remove in v11
+    ...(main.deviceAddons ?? []),
+  ];
+
+  for (const addon of allAddons) {
     const registerPath = resolveAddonFile(
       getAddonName(addon),
       'register',
@@ -116,7 +168,7 @@ async function generate({
     enhancers.push(docToolsAnnotation);
   }
 
-  for (const addon of main.addons) {
+  for (const addon of allAddons) {
     const previewPath = resolveAddonFile(
       getAddonName(addon),
       'preview',
@@ -132,7 +184,11 @@ async function generate({
 
   let options = '';
   let optionsVar = '';
-  const reactNativeOptions = main.reactNative;
+  const reactNativeOptions = main.reactNative ?? {};
+
+  if (disableUI) {
+    reactNativeOptions.disableUI = true;
+  }
 
   if (reactNativeOptions && typeof reactNativeOptions === 'object') {
     optionsVar = `const options = ${JSON.stringify(reactNativeOptions, null, 2)}`;
@@ -192,6 +248,7 @@ declare global {
   const fileContent = `/* do not change this file, it is auto generated by storybook. */
 ${useJs ? '' : '/// <reference types="@storybook/react-native/metro-env" />\n'}import { start, updateView${useJs ? '' : ', View, type Features'} } from '@storybook/react-native';
 
+
 ${registeredAddons.join('\n')}
 
 const normalizedStories = [

packages/react-native/scripts/ws-smoke-server.mjs

@@ -0,0 +1,56 @@
+/**
+ * Minimal HTTP + WebSocket server for manual connectivity checks (LAN, firewall).
+ * Do not bind the same port as Metro's Storybook channel server while Metro is using it.
+ *
+ * Sends Storybook-style heartbeats every 10s (`{ type: 'ping', args: [] }`), matching
+ * packages/react-native/src/metro/channelServer.ts so storybook's WebsocketTransport
+ * does not close the socket (~20s) waiting for pings.
+ *
+ * Env: STORYBOOK_WS_HOST (bind address; omit for all interfaces), STORYBOOK_WS_PORT (default 7007)
+ */
+import { createServer } from 'node:http';
+import { WebSocketServer } from 'ws';
+
+const PING_INTERVAL_MS = 10_000;
+
+const port = Number(process.env.STORYBOOK_WS_PORT) || 7007;
+const host = process.env.STORYBOOK_WS_HOST || undefined;
+
+const httpServer = createServer((_req, res) => {
+  res.writeHead(404);
+  res.end();
+});
+
+const wss = new WebSocketServer({ server: httpServer });
+
+// Same global ping interval as createChannelServer — keeps Storybook client transport alive.
+const pingInterval = setInterval(() => {
+  wss.clients.forEach((client) => {
+    if (client.readyState === WebSocket.OPEN) {
+      client.send(JSON.stringify({ type: 'ping', args: [] }));
+    }
+  });
+}, PING_INTERVAL_MS);
+pingInterval.unref?.();
+
+wss.on('connection', (ws) => {
+  console.log('[ws-smoke-server] WebSocket connection established');
+
+  ws.on('message', (data) => {
+    const text = data.toString();
+    console.log('[ws-smoke-server] message:', text);
+    try {
+      const json = JSON.parse(text);
+      if (json?.type === 'pong') {
+        console.log('[ws-smoke-server] saw Storybook transport pong (heartbeat ack)');
+      }
+    } catch {
+      // ignore non-JSON
+    }
+  });
+});
+
+httpServer.listen(port, host, () => {
+  const where = host ?? '0.0.0.0 (all interfaces)';
+  console.log(`[ws-smoke-server] listening on ${where}:${port}`);
+});

packages/react-native/src/Start.tsx

@@ -143,7 +143,7 @@ export function start({
     previewView as any
   );
 
-  const view = new View(preview, channel);
+  const view = new View(preview, channel, options);
 
   if (global) {
     global.__STORYBOOK_ADDONS_CHANNEL__ = channel;

packages/react-native/src/View.tsx

@@ -11,7 +11,10 @@ import dedent from 'dedent';
 import { patchChannelForRN } from './patchChannelForRN';
 import deepmerge from 'deepmerge';
 import { useEffect, useMemo, useReducer, useState } from 'react';
+import { SafeAreaView, SafeAreaProvider } from 'react-native-safe-area-context';
+
 import {
+  StatusBar,
   ActivityIndicator,
   Linking,
   Platform,
@@ -118,11 +121,13 @@ export class View {
   _webUrl: string;
   _storage: Storage;
   _channel: Channel;
+  _options: any;
   _idToPrepared: Record<string, PreparedStory<ReactRenderer>> = {};
 
-  constructor(preview: PreviewWithSelection<ReactRenderer>, channel: Channel) {
+  constructor(preview: PreviewWithSelection<ReactRenderer>, channel: Channel, options: any) {
     this._preview = preview;
     this._channel = channel;
+    this._options = options;
   }
 
   _storyIdExists = (storyId: string) => {
@@ -201,13 +206,9 @@ export class View {
 
   _getServerChannel = (params: Partial<Params> = {}) => {
     const host = this._getHost(params);
-
     const port = `:${this.__getPort(params)}`;
-
     const query = params.query || '';
-
     const websocketType = this._isSecureConnection(params) ? 'wss' : 'ws';
-
     const url = `${websocketType}://${host}${port}/${query}`;
 
     const channel = new Channel({
@@ -236,14 +237,21 @@ export class View {
 
   getStorybookUI = (params: Partial<Params> = {}) => {
     const {
-      shouldPersistSelection = true,
-      onDeviceUI = true,
       enableWebsockets = false,
-      storage,
       CustomUIComponent,
       hasStoryWrapper: storyViewWrapper = true,
     } = params;
 
+    const storage = params.storage ?? {
+      getItem: async (key) => null,
+      setItem: async (key, value) => {},
+    };
+
+    const onDeviceUI = this._options.disableUI ? false : (params.onDeviceUI ?? true);
+    const shouldPersistSelection = this._options.disableUI
+      ? false
+      : (params.shouldPersistSelection ?? true);
+
     const getFullUI = (enabled: boolean): SBUI => {
       if (enabled) {
         try {
@@ -260,7 +268,10 @@ export class View {
 
     const FullUI: SBUI = getFullUI(onDeviceUI && !CustomUIComponent);
 
-    this._storage = storage;
+    this._storage = storage ?? {
+      getItem: async (key) => null,
+      setItem: async (key, value) => {},
+    };
 
     const initialStory = this._getInitialStory(params);
 
@@ -391,7 +402,7 @@ export class View {
         self._setStory = (newStory: StoryContext<ReactRenderer>) => {
           setContext(newStory);
 
-          if (shouldPersistSelection && !storage) {
+          if (shouldPersistSelection && !params.storage) {
             console.warn(dedent`Please set storage in getStorybookUI like this:
               const StorybookUIRoot = view.getStorybookUI({
                 storage: {
@@ -487,7 +498,22 @@ export class View {
         );
       } else {
         return (
-          <StoryView useWrapper={storyViewWrapper} storyBackgroundColor={storyBackgroundColor} />
+          <SafeAreaProvider>
+            <SafeAreaView style={{ flex: 1 }}>
+              <StatusBar hidden />
+              <RNView
+                style={{ flex: 1 }}
+                accessibilityLabel={story?.id}
+                testID={story?.id}
+                accessible
+              >
+                <StoryView
+                  useWrapper={storyViewWrapper}
+                  storyBackgroundColor={storyBackgroundColor}
+                />
+              </RNView>
+            </SafeAreaView>
+          </SafeAreaProvider>
         );
       }
     };