setup-react-native-storybook

用途

该技能用于向 React Native 项目添加 @storybook/react-native v10，帮助开发者在移动端项目中搭建 Storybook 环境，用于组件的独立开发、预览与调试。

支持的四种搭建流程

技能会根据项目类型选择对应的流程：

Expo（无路由）：参见 references/expo-setup.md
Expo 配合 Expo Router：参见 references/expo-router-setup.md
React Native CLI（无 Expo）：参见 references/react-native-cli-setup.md
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

包管理器注意事项

需检测项目使用的包管理器（查找 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 等。

通用步骤（所有流程）

1. 运行 CLI 初始化

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

该命令会安装依赖并创建 .rnstorybook/ 目录，其中包含 main.ts、preview.tsx 和 index.tsx。

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

更新生成的 .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 中的故事匹配路径

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

// .rnstorybook/main.ts
const main: StorybookConfig = {
  stories: [
    './stories/**/*.stories.?(ts|tsx|js|jsx)', // 初始化生成的示例故事
    '../src/components/**/*.stories.?(ts|tsx|js|jsx)', // 根据项目结构添加
  ],
  // ...
};

4. 配置打包器

对于 Metro 项目，使用 withStorybook 包装 metro 配置。对于 Re.Pack 项目，将 StorybookPlugin 添加到 rspack/webpack 配置中。详见相关参考文件。

5. 创建入口文件

Storybook 的渲染方式因流程而异，详见相关参考文件。

6. 运行

npm run start
npm run ios     # 或 npm run android

withStorybook 选项（Metro）

module.exports = withStorybook(config, {
  enabled: true, // 为 false 时从打包中移除 Storybook
  configPath: './.rnstorybook', // 可选，使用默认 ./.rnstorybook 目录时冗余
  useJs: false, // 生成 .js 而非 .ts
  docTools: true, // 自动提取 arg
  liteMode: false, // 模拟默认 UI 依赖（配合 react-native-ui-lite 使用）
  websockets: { port: 7007, host: 'localhost' }, // 远程控制
});

StorybookPlugin 选项（Re.Pack）

new StorybookPlugin({
  enabled: true, // 为 false 时从打包中剥离 Storybook
  configPath: './.rnstorybook', // 可选，使用默认 ./.rnstorybook 目录时冗余
  useJs: false, // 生成 .js 而非 .ts
  docTools: true, // 自动提取 arg
  liteMode: false, // 模拟默认 UI 依赖（配合 react-native-ui-lite 使用）
  websockets: 'auto', // 'auto' 检测局域网 IP，或 { port: 7007, host: 'localhost' }
});

适用场景

适用于需要为 React Native 组件建立独立开发与预览环境的项目，覆盖 Expo、Expo Router、React Native CLI 与 Re.Pack 等常见工程形态。

限制

资料未提供关于收费、价格、平台兼容性范围或具体效果的信息，暂未提供。