Storybook for React Native Web

Storybook for React Native Web 是一个 framework 版本，可以轻松地为 React Native 开发和测试隔离的 UI 组件。它使用 Vite 为 Web 浏览器构建组件。

¥Storybook for React Native Web is a framework that makes it easy to develop and test UI components in isolation for React Native. It uses Vite to build your components for web browsers.

安装

¥Install

要在现有的 React Native 项目中安装 Storybook，请在项目根目录下运行以下命令：

¥To install Storybook in an existing React Native project, run this command in your project's root directory:

npm create storybook@latest

接下来，你可以开始使用 写故事、运行测试 和 组件文档。要更好地控制安装过程，请参阅 安装指南。

¥You can then get started writing stories, running tests and documenting your components. For more control over the installation process, refer to the installation guide.

要求

¥Requirements

• 

  React Native ≥ 0.72

• 

  React Native Web ≥ 0.19

• 

  Vite ≥ 5

运行 Storybook

¥Run Storybook

要为特定项目运行 Storybook，请运行以下命令：

¥To run Storybook for a particular project, run the following:

npm run storybook

要构建 Storybook，请运行：

¥To build Storybook, run:

npm run build-storybook

你将在配置的 outputDir（默认为 storybook-static）中找到输出。

¥You will find the output in the configured outputDir (default is storybook-static).

React Native 与 React Native Web

¥React Native vs React Native Web

如果你正在构建 React Native (RN) 组件，Storybook 提供两种选择：原生和 Web。

¥If you’re building React Native (RN) components, Storybook has two options: Native and Web.

这两个选项都提供了一个故事目录，当你在你喜欢的编辑器中编辑代码时，它会进行热刷新。但是，它们的实现方式截然不同：

¥Both options provide a catalog of your stories that hot refreshes as you edit the code in your favorite editor. However, their implementations are quite different:

• 原生 - 在你的 React Native 应用中运行。它具有高保真度，但功能集有限。

  ¥Native - Runs inside your React Native application. It’s high-fidelity but has a limited feature set.

• Web - 在浏览器中显示你的 React Native 组件。它基于 Storybook for Web，功能丰富且成熟。

  ¥Web - Displays your React Native components in the browser. It’s based on Storybook for Web, which is feature-rich and mature.

比较

¥Comparison

那么，哪种选择适合你？

¥So, which option is right for you?

原生。如果你需要以下情况，则应选择此选项：

¥Native. You should choose this option if you want:

• 原生功能 - 你的组件依赖于设备特定的功能，例如原生模块。它可以在你的实际应用、模拟器或设备上运行，并提供完全保真度。网页版使用 react-native-web，它适用于大多数组件，但支持 limitations。

  ¥Native features - Your components rely on device-specific features like native modules. It runs in your actual application, in-simulator, or on-device and provides full fidelity. The web version uses react-native-web, which works for most components but has limitations.

• 移动发布 - 你希望在设备上共享 Storybook，作为测试版本的一部分，或将其嵌入到你的应用中。

  ¥Mobile publication - You want to share your Storybook on-device as part of a test build or embedded inside your application.

Web.如果你需要以下情况，则应选择此选项：

¥Web. You should choose this option if you want:

• 共享 - 发布到网络并与你的团队或公开分享。

  ¥Sharing - Publish to the web and share with your team or publicly.

• 文档 - 在 MDX 中自动生成的组件文档或丰富的 Markdown 文档。

  ¥Documentation - Auto-generated component docs or rich markdown docs in MDX.

• 测试 - 组件的组件、视觉和 a11y 测试。

  ¥Testing - Component, visual, and a11y tests for your components.

• 插件 - 500 多个插件，用于改进开发、文档、测试以及与其他工具的集成。

  ¥Addons - 500+ addons that improve development, documentation, testing, and integration with other tools.

两者皆有。也可以同时使用这两个选项。这会增加 Storybook 的安装占用空间，但如果除了所有 Web 功能外，你还想要原生保真度，这是一个不错的选择。了解更多信息，请见下文。

¥Both. It’s also possible to use both options together. This increases Storybook’s install footprint but is a good option if you want native fidelity in addition to all of the web features. Learn more below.

同时使用 React Native 和 React Native Web

¥Using both React Native and React Native Web

使用 React Native 和 React Native Web 最简单的方法是在安装 Storybook 时选择 "两者皆有" 选项。这将为两种环境安装并创建配置，让你可以在同一项目中为这两种环境运行 Storybook。

¥The easiest way to use React Native and React Native Web is to select the "Both" option when installing Storybook. This will install and create configurations for both environments, allowing you to run Storybook for both in the same project.

选择 "两者皆有" 后，安装程序将执行以下操作：

¥When you select "Both", the installation will:

1. 安装并配置 React Native Storybook（设备端）

   ¥Install and configure React Native Storybook (on-device)

2. 安装并配置 React Native Web Storybook（Web 端）

   ¥Install and configure React Native Web Storybook (web-based)

3. 在项目中设置两种配置

   ¥Set up both configurations in your project

安装完成后，你将看到两个环境的说明：

¥After installation, you'll see instructions for both environments:

• React Native Storybook 需要额外的手动配置步骤（替换应用入口、封装 Metro 配置）。

  ¥React Native Storybook will require additional manual configuration steps (replacing app entry, wrapping metro config)

• 可以使用 storybook 命令立即启动 React Native Web Storybook。

  ¥React Native Web Storybook can be started immediately using the storybook command

但是，如果安装了一个版本，你可以单独安装它们。你可以通过运行安装命令并在安装向导中选择 "React Native Web"，在现有的 React Native Storybook 旁边添加 React Native Web Storybook，反之亦然。

¥However, you can install them separately if one version is installed. You can add a React Native Web Storybook alongside an existing React Native Storybook by running the install command and selecting "React Native Web" in the setup wizard, and vice versa.

常见问题

¥FAQ

如何从 React Native Web 插件迁移？

¥How do I migrate from the React Native Web addon?

React Native Web 插件 是基于 Webpack 的 React Native Web Vite 框架（即 @storybook/react-native-web-vite）的前身。如果你使用的是插件，则应迁移到框架，因为它速度更快、更稳定、维护更完善，并且文档记录更完善。请按照以下步骤操作。

¥The React Native Web addon was a Webpack-based precursor to the React Native Web Vite framework (i.e., @storybook/react-native-web-vite). If you're using the addon, you should migrate to the framework, which is faster, more stable, maintained, and better documented. To do so, follow the steps below.

运行以下命令将 Storybook 升级到最新版本：

¥Run the following command to upgrade Storybook to the latest version:

npx storybook@latest upgrade

安装框架及其对等依赖：

¥Install the framework and its peer dependencies:

npm install --save-dev @storybook/react-native-web-vite vite

更新你的 .storybook/main.js|ts 文件以更改框架属性并移除 @storybook/addon-react-native-web 插件：

¥Update your .storybook/main.js|ts to change the framework property and remove the @storybook/addon-react-native-web addon:

export default {
  addons: [
    '@storybook/addon-react-native-web', // 👈 Remove the addon
  ],
  // Replace @storybook/react-webpack5 with the Vite framework
  framework: '@storybook/react-native-web-vite',
};

最后，从你的项目中删除插件和类似的软件包（即 @storybook/react-webpack5 和 @storybook/addon-react-native-web）。

¥Finally, remove the addon and similar packages (i.e., @storybook/react-webpack5 and @storybook/addon-react-native-web) from your project.

API

选项

¥Options

如果需要，你可以传递一个选项对象以进行其他配置：

¥You can pass an options object for additional configuration if needed:

import type { StorybookConfig } from '@storybook/react-native-web-vite';
 
const config: StorybookConfig = {
  framework: {
    name: '@storybook/react-native-web-vite',
    options: {
      modulesToTranspile: ['my-library'], // add libraries that are not transpiled for web by default
 
      // You should apply babel plugins and presets here for your project that you want to apply to your code
      // for example put the reanimated preset here if you are using reanimated
      // or the nativewind jsxImportSource for example
      pluginReactOptions: {
        jsxRuntime: 'automatic' | 'classic', // default: 'automatic'
        jsxImportSource: string, // default: 'react'
        babel:{
          plugins: Array<string | [string, any]>,
          presets: Array<string | [string, any]>,
          // ... other compatible babel options
        }
        include: Array<string|RegExp>, 
        exclude: Array<string|RegExp>,
        // ... other compatible @vitejs/plugin-react options
      }
    },
  },
};
 
export default config;

重新激活

¥Example configuration for reanimated

const main: StorybookConfig = {
  // ... rest of config
 
  framework: {
    name: "@storybook/react-native-web-vite",
    options: {
      pluginReactOptions: {
        babel: {
          plugins: [
            "@babel/plugin-proposal-export-namespace-from",
            "react-native-reanimated/plugin",
          ],
        },
      },
    },
  },
 
  // ... rest of config
}

nativewind 的示例配置

¥Example configuration for nativewind

 
const main: StorybookConfig = {
  // ... rest of config
 
  framework: {
    name: "@storybook/react-native-web-vite",
    options: {
      pluginReactOptions: {
        jsxImportSource: "nativewind",
      },
    },
  },
}

用于转译其他 node_modules 的示例配置

¥Example configuration to transpile additional node_modules

假设你需要转译一个名为 my-library 的库，该库默认不会转译为 Web 版本。你可以将其添加到 modulesToTranspile 选项中。

¥Let's say you need to transpile a library called my-library that is not transpiled for web by default. You can add it to the modulesToTranspile option.

const main: StorybookConfig = {
  // ... rest of config
 
  framework: {
    name: "@storybook/react-native-web-vite",
    options: {
      modulesToTranspile: ['my-library'],
    },
  },
}

builder

类型：Record<string, any>

¥Type: Record<string, any>

配置 框架的构建器 的选项。对于此框架，可以在 Vite 构建器文档 中找到可用选项。

¥Configure options for the framework's builder. For this framework, available options can be found in the Vite builder docs.