setup-react-native-storybook

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

React Native Storybook Setup

React Native Storybook 配置指南

Add

@storybook/react-native

v10 to a React Native project.

Important: Detect the project's package manager (look for

yarn.lock

pnpm-lock.yaml

, or

bun.lockb

) and use it for all install/run commands instead of

npm

. The examples below use

npm

but substitute accordingly (e.g.

yarn add

instead of

npm install

yarn storybook

instead of

npm run storybook

). For Expo projects, use

npx expo install

(or

bunx expo install

, etc.) to install dependencies so Expo can resolve compatible versions.

For the init command, use

<pm> create storybook

with the flags shown below. Only npm needs

--

before the flags. Never use

npx

bunx

etc for this.

Four setup flows based on project type:

Expo (no router) - see references/expo-setup.md
Expo with Expo Router - see references/expo-router-setup.md
React Native CLI (no Expo) - see references/react-native-cli-setup.md
Re.Pack (rspack/webpack) - see references/repack-setup.md

在React Native项目中添加

@storybook/react-native

v10版本。

重要提示： 检测项目的包管理器（查找

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

等工具执行此命令。

根据项目类型分为四种配置流程：

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

Flow Selection

流程选择规则

Project has

rspack.config

webpack.config

and uses

@callstack/repack

-> Re.Pack

Project has
```
app/
```
directory with
```
_layout.tsx
```
and uses
```
expo-router
```
-> Expo Router
Project uses Expo but not file-based routing -> Expo
Project uses
```
@react-native-community/cli
```
with no Expo -> React Native CLI

项目包含

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流程

Common Steps (all flows)

通用步骤（所有流程）

1. Run CLI Init

1. 运行CLI初始化命令

bash

npm create storybook -- --type react_native --yes

bash

npm create storybook -- --type react_native --yes

or: pnpm create storybook --type react_native --yes

或: pnpm create storybook --type react_native --yes

or: bun create storybook --type react_native --yes

或: bun create storybook --type react_native --yes


This installs dependencies and creates `.rnstorybook/` with `main.ts`, `preview.tsx`, and `index.tsx`.


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

2. Enable WebSockets in .rnstorybook/index.tsx

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

Update the generated

.rnstorybook/index.tsx

to enable WebSocket support. This is required for remote control and syncing with the Storybook web companion:

tsx

// .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;

If the project doesn't have

@react-native-async-storage/async-storage

, install it:

bash

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

更新生成的

.rnstorybook/index.tsx

文件以启用WebSocket支持，这是实现远程控制及与Storybook网页端同步的必要配置：

tsx

// .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

，请执行以下命令安装：

bash

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

3. Update Story Globs in main.ts

3. 在main.ts中更新Story文件匹配规则

The CLI generates a default

stories

glob in

.rnstorybook/main.ts

. Keep the existing glob and add an additional entry pointing to where UI components actually live in the project. Look for directories like

components/

src/components/

src/

ui/

, etc.:

// .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
  ],
  // ...
};

CLI会在

.rnstorybook/main.ts

中生成默认的stories匹配规则。保留现有规则并添加一条指向项目UI组件实际存放目录的规则。常见组件目录包括

components/

、

src/components/

、

src/

、

ui/

等：

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

4. Configure Bundler

4. 配置打包工具

For Metro projects, wrap the metro config with

withStorybook

. For Re.Pack projects, add the

StorybookPlugin

to your rspack/webpack config. See the relevant reference file for details.

对于Metro项目，使用

withStorybook

包装Metro配置。对于Re.Pack项目，在rspack/webpack配置中添加

StorybookPlugin

。详情请查看对应流程的参考文档。

5. Create Entrypoint

5. 创建入口文件

How Storybook is rendered differs per flow - see the relevant reference file.

不同流程中Storybook的渲染方式有所差异，请查看对应流程的参考文档。

6. Run

6. 运行项目

bash

npm run start
npm run ios     # or npm run android

bash

npm run start
npm run ios     # 或 npm run android

withStorybook Options (Metro)

withStorybook配置项（Metro）

module.exports = withStorybook(config, {
  enabled: true, // Remove Storybook from bundle when false
  configPath: './.rnstorybook', // Storybook config directory
  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
});

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

StorybookPlugin Options (Re.Pack)

StorybookPlugin配置项（Re.Pack）

new StorybookPlugin({
  enabled: true, // Strip Storybook from bundle when false
  configPath: './.rnstorybook', // Storybook config directory
  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' }
});

new StorybookPlugin({
  enabled: true, // 设置为false时会从打包文件中移除Storybook
  configPath: './.rnstorybook', // Storybook配置目录路径
  useJs: false, // 生成.js文件而非.ts文件
  docTools: true, // 自动提取参数
  liteMode: false, // 模拟默认UI依赖（配合react-native-ui-lite使用）
  websockets: 'auto', // 'auto'会自动检测局域网IP，也可手动配置为{ port: 7007, host: 'localhost' }
});