setup-react-native-storybook

React Native Storybook 设置

将 @storybook/react-native v10 添加到 React Native 项目中。

**重要提示：**检测项目使用的包管理器（查找 yarn.lock、pnpm-lock.yaml 或 bun.lockb），并在所有安装／运行命令中使用它，而不是 npm。以下示例使用 npm，但请替换为相应的命令（例如，使用 yarn add 替代 npm install，使用 yarn storybook 替代 npm run storybook）。对于 Expo 项目，请使用 npx expo install（或 bunx expo install 等）安装依赖项，以便 Expo 能解析兼容版本。

对于初始化命令，请使用带有以下标志的 <pm> create storybook。只有 npm 需要在标志前添加 --。切勿为此使用 npx／bunx 等命令。

根据项目类型选择以下 4 种设置流程：

1. Expo（无路由器）——请参阅 references/expo-setup.md
2. 使用 Expo Router 的 Expo 项目——请参阅 references/expo-router-setup.md
3. React Native CLI（非 Expo）——请参阅 references/react-native-cli-setup.md
4. Re.Pack（rspack／webpack）——请参阅 references/repack-setup.md

流程选择

• 项目包含 rspack.config 或 webpack.config，并使用 @callstack/repack → Re.Pack
• 项目包含 app/ 目录，其中有 _layout.tsx，并使用 expo-router → Expo Router
• 项目使用 Expo，但不使用基于文件的路由 → Expo
• 项目使用 @react-native-community/cli，且不使用 Expo → React Native CLI

通用步骤（适用于所有流程）

1. 运行 CLI 初始化命令

npm create storybook -- --type react_native --yes
# or: pnpm create storybook --type react_native --yes
# or: bun create storybook --type react_native --yes

此操作会安装依赖项，并创建包含 main.ts、preview.tsx 和 index.tsx 的 .rnstorybook/。

2. 在 .rnstorybook/index.tsx 中启用 WebSockets

更新生成的 .rnstorybook/index.tsx，以启用 WebSocket 支持。这是远程控制以及与 Storybook Web 配套应用同步所必需的：

// .rnstorybook/index.tsx
import AsyncStorage from '@react-native-async-storage/async-storage';
import { view } from './storybook.requires';

const StorybookUIRoot = view.getStorybookUI({
  storage: {
    getItem: AsyncStorage.getItem,
    setItem: AsyncStorage.setItem,
  },
  enableWebsockets: true,
});

export default StorybookUIRoot;

如果项目没有 @react-native-async-storage/async-storage，请安装它：

npm install @react-native-async-storage/async-storage

3. 在 main.ts 中更新 Story Glob

CLI 会在 .rnstorybook/main.ts 中生成默认的 stories glob。保留现有 glob，并添加一个指向项目中 UI 组件实际所在位置的条目。查找 components/、src/components/、src/、ui/ 等目录：

// .rnstorybook/main.ts
const main: StorybookConfig = {
  stories: [
    './stories/**/*.stories.?(ts|tsx|js|jsx)', // example stories from init
    '../src/components/**/*.stories.?(ts|tsx|js|jsx)', // add based on project structure
  ],
  // ...
};

4. 配置打包工具

对于 Metro 项目，请使用 withStorybook 包装 Metro 配置。对于 Re.Pack 项目，请将 StorybookPlugin 添加到 rspack／webpack 配置中。详情请参阅相应的参考文件。

5. 创建入口文件

不同流程的 Storybook 渲染方式有所不同——请参阅相应的参考文件。

6. 运行

npm run start
npm run ios     # or npm run android

withStorybook 选项（Metro）

module.exports = withStorybook(config, {
  enabled: true, // Remove Storybook from bundle when false
  configPath: './.rnstorybook', // Optional and redundant when using the default ./.rnstorybook folder
  useJs: false, // Generate .js instead of .ts
  docTools: true, // Auto arg extraction
  liteMode: false, // Mock default UI deps (use with react-native-ui-lite)
  websockets: { port: 7007, host: 'localhost' }, // Remote control
});

StorybookPlugin 选项（Re.Pack）

new StorybookPlugin({
  enabled: true, // Strip Storybook from bundle when false
  configPath: './.rnstorybook', // Optional and redundant when using the default ./.rnstorybook folder
  useJs: false, // Generate .js instead of .ts
  docTools: true, // Auto arg extraction
  liteMode: false, // Mock default UI deps (use with react-native-ui-lite)
  websockets: 'auto', // 'auto' detects LAN IP, or { port: 7007, host: 'localhost' }
});