-
Notifications
You must be signed in to change notification settings - Fork 474
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: change Storybook migration to storybook-rsbuild
- Loading branch information
Showing
2 changed files
with
54 additions
and
57 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,53 +1,52 @@ | ||
# Migrate Storybook | ||
# Migrating Storybook | ||
|
||
If you are using the React framework of [Storybook 7.0](https://storybook.js.org/) and building with Webpack 5, you can replace the `@storybook/react-webpack5` with [@modern-js/storybook](https://www.npmjs.com/package/@modern-js/storybook), which supports Rspack as an out-of-the-box underlying build tool. Documentation can be referred to at [Modern.js - Using Storybook](https://modernjs.dev/en/guides/advanced-features/using-storybook.html). | ||
If you are using React / Vue with [Storybook 8.0](https://storybook.js.org/) and building with webpack 5, you can replace the `@storybook/react-webpack5` build with [storybook-rsbuild](https://github.com/rspack-contrib/storybook-rsbuild), which is implemented based on Rsbuild and uses Rspack as the underlying build tool. It supports out-of-the-box use, and the documentation can be found at [storybook-rsbuild](https://github.com/rspack-contrib/storybook-rsbuild). | ||
|
||
Next, we will take React as an example to introduce how to migrate a Storybook webpack 5 project. The migration steps for Vue projects are similar to React. | ||
|
||
## Update Dependencies | ||
|
||
First, we need to add the `@modern-js/storybook` dependency and remove the `webpack` dependency. | ||
First, add the [`storybook-react-rsbuild`](https://www.npmjs.com/package/storybook-react-rsbuild) dependency (for Vue projects, use [`storybook-vue3-rsbuild`](https://www.npmjs.com/package/storybook-vue3-rsbuild)) and replace the `@storybook/react-webpack5` dependency with `@rsbuild/core` and `@rsbuild/plugin-react` (for Vue projects, use `@rsbuild/plugin-vue`). | ||
|
||
```diff title=package.json | ||
{ | ||
"devDependencies": { | ||
- "@storybook/react-webpack5": "^7" | ||
+ "@modern-js/storybook": "^2" | ||
- "@storybook/react-webpack5": "^8" | ||
+ "storybook-react-rsbuild": "latest", | ||
+ "@rsbuild/core": "latest" | ||
+ "@rsbuild/plugin-react": "latest", | ||
} | ||
} | ||
``` | ||
|
||
## Configure Storybook | ||
## Configure Rsbuild | ||
|
||
Storybook Rsbuild will automatically load the Rsbuild configuration file from the working directory. Install [`@rsbuild/plugin-react`](https://rsbuild.dev/guide/framework/react) (for Vue projects, install and use [`@rsbuild/plugin-vue`](https://rsbuild.dev/guide/framework/vue3)). | ||
|
||
```js | ||
import { defineConfig } from '@rsbuild/core'; | ||
import { pluginReact } from '@rsbuild/plugin-react'; | ||
|
||
export default defineConfig({ | ||
plugins: [pluginReact()], | ||
}); | ||
``` | ||
|
||
Refer to the following configuration, modify the `main.js` configuration of Storybook, and specify Rspack as the build tool: | ||
## Update Storybook Configuration | ||
|
||
Refer to the following configuration to modify the `main.js` configuration of Storybook, and specify `'storybook-react-rsbuild'` as the Storybook framework (for Vue projects, use `'storybook-vue3-rsbuild'`). | ||
|
||
```diff title=.storybook/main.js | ||
export default { | ||
- framework: '@storybook/react-webpack5' | ||
+ framework: { | ||
+ name: '@modern-js/storybook', | ||
+ options: { | ||
+ bundler: 'rspack' | ||
+ }, | ||
+ framework: 'storybook-react-rsbuild', | ||
}, | ||
``` | ||
|
||
## Example | ||
## Examples | ||
|
||
Here is an example of building Storybook with Rspack based on @modern-js/storybook: [react-storybook](https://github.com/rspack-contrib/rspack-examples/tree/main/rspack/react-storybook). | ||
The [rspack-contrib/storybook-rsbuild](https://github.com/rspack-contrib/storybook-rsbuild/tree/main/sandboxes) repository provides examples of Storybook for React / Vue projects. | ||
|
||
## Limitations | ||
|
||
Support for Storybook 7.0 is still experimental, and there are currently some limitations: | ||
|
||
1. Support for frameworks other than React is not yet available. | ||
2. Support for Next.js is not available, as Next.js has its own build solution. | ||
3. If you find the build speed is very slow, check if the automatic documentation generation feature is enabled. For the highest performance, configure it to `react-docgen`. The difference between `react-docgen` and `react-docgen-typescript` is that the former is based on Babel, while the latter is based on TypeScript. The former has better performance, but weaker type inference capabilities. If using Rspack to build, only `react-docgen` is supported. | ||
|
||
```js title=main.js | ||
export default { | ||
typescript: { | ||
reactDocgen: 'react-docgen', | ||
}, | ||
}; | ||
``` | ||
|
||
We plan to provide a framework-agnostic builder based on [Rsbuild](https://github.com/web-infra-dev/rsbuild) to integrate with the framework, refer to [rsbuild#1974](https://github.com/web-infra-dev/rsbuild/issues/1974). | ||
Rspack is gradually improving full support for Storybook. Currently, there are some capabilities that are not supported, see [storybook-rsbuild - Rspack tasks](https://github.com/rspack-contrib/storybook-rsbuild#roadmap) for details. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,54 +1,52 @@ | ||
# 迁移 Storybook | ||
|
||
如果你正在使用 [Storybook 7.0](https://storybook.js.org/) 的 React 框架并且使用 Webpack 5 构建,那么可以使用 [@modern-js/storybook | ||
](https://www.npmjs.com/package/@modern-js/storybook) 替换 @storybook/react-webpack5 构建,@modern-js/storybook 支持 Rspack 作为开箱即用的底层构建工具,文档可参考 [Modern.js - Using Storybook](https://modernjs.dev/en/guides/advanced-features/using-storybook.html)。 | ||
如果你正在使用 [Storybook 8.0](https://storybook.js.org/) 的 React / Vue 框架并且使用 webpack 5 构建,那么可以使用 [storybook-rsbuild](https://github.com/rspack-contrib/storybook-rsbuild) 替换 `@storybook/react-webpack5` 构建,`storybook-rsbuild` 基于 Rsbuild 实现,以 Rspack 作为底层构建工具,支持开箱即用,文档可参考 [storybook-rsbuild](https://github.com/rspack-contrib/storybook-rsbuild)。 | ||
|
||
下面将以 React 为例,介绍如何迁移 Storybook webpack 5 项目,Vue 项目迁移步骤与 React 相似。 | ||
|
||
## 更新依赖 | ||
|
||
首先,我们需要添加 `@modern-js/storybook` 依赖并且可以去掉 `webpack` 的依赖。 | ||
首先,添加 [`storybook-react-rsbuild`](https://www.npmjs.com/package/storybook-react-rsbuild) 依赖(对于 Vue 项目则为 [`storybook-vue3-rsbuild`](https://www.npmjs.com/package/storybook-vue3-rsbuild)),并将 `@storybook/react-webpack5` 的依赖更换为 `@rsbuild/core` 及 `@rsbuild/plugin-react`(对于 Vue 项目则为 `@rsbuild/plugin-vue`) | ||
|
||
```diff title=package.json | ||
{ | ||
"devDependencies": { | ||
- "@storybook/react-webpack5": "^7" | ||
+ "@modern-js/storybook": "^2" | ||
- "@storybook/react-webpack5": "^8" | ||
+ "storybook-react-rsbuild": "latest", | ||
+ "@rsbuild/core": "latest" | ||
+ "@rsbuild/plugin-react": "latest", | ||
} | ||
} | ||
``` | ||
|
||
## 配置 Storybook | ||
## 配置 Rsbuild | ||
|
||
Storybook Rsbuild 会自动加载工作目录的 Rsbuild 配置文件,安装 [`@rsbuild/plugin-react`](https://rsbuild.dev/guide/framework/react)(对于 Vue 项目,需要安装及使用 [`@rsbuild/plugin-vue`](https://rsbuild.dev/guide/framework/vue3))。 | ||
|
||
```js | ||
import { defineConfig } from '@rsbuild/core'; | ||
import { pluginReact } from '@rsbuild/plugin-react'; | ||
|
||
export default defineConfig({ | ||
plugins: [pluginReact()], | ||
}); | ||
``` | ||
|
||
参考下列配置,修改 Storybook 的 `main.js` 配置,并指定 Rspack 作为构建工具: | ||
## 更新 Storybook 配置 | ||
|
||
参考下列配置,修改 Storybook 的 `main.js` 配置,并指定 `'storybook-react-rsbuild'` 作为 Storybook 框架(对于 Vue 项目则为 `'storybook-vue3-rsbuild'`)。 | ||
|
||
```diff title=.storybook/main.js | ||
export default { | ||
- framework: '@storybook/react-webpack5' | ||
+ framework: { | ||
+ name: '@modern-js/storybook', | ||
+ options: { | ||
+ bundler: 'rspack' | ||
+ }, | ||
+ framework: 'storybook-react-rsbuild', | ||
}, | ||
``` | ||
|
||
## 示例 | ||
|
||
这里有一个基于 @modern-js/storybook 使用 Rspack 构建 Storybook 的示例:[react-storybook](https://github.com/rspack-contrib/rspack-examples/tree/main/rspack/react-storybook)。 | ||
在 [rspack-contrib/storybook-rsbuild](https://github.com/rspack-contrib/storybook-rsbuild/tree/main/sandboxes) 仓库中提供了 React / Vue 项目的 Storybook 示例。 | ||
|
||
## 局限 | ||
|
||
对 Storybook 7.0 的支持仍然是实验性的,并且目前有一些局限: | ||
|
||
1. 暂不支持 React 以外的框架 | ||
2. 暂不支持 Next.js,Next.js 有自己的构建方案 | ||
3. 如果发现构建速度很慢,请检查是否开启了自动文档生成功能,如果想要最高的性能,请配置为 `react-docgen`。`react-docgen` 和 `react-docgen-typescript` 的区别是,前者基于 Babel 实现,后者基于 TypeScript 实现,前者性能会更好,但类型推断能力更弱。如果使用 Rspack 构建,则只支持 `react-docgen`。 | ||
|
||
```js title=main.js | ||
export default { | ||
typescript: { | ||
reactDocgen: 'react-docgen', | ||
}, | ||
}; | ||
``` | ||
|
||
我们有计划提供基于 [Rsbuild](https://github.com/web-infra-dev/rsbuild) 的框架无关的 builder 与 framework 集成,参考 [rsbuild#1974](https://github.com/web-infra-dev/rsbuild/issues/1974)。 | ||
Rspack 正在逐步完善对 Storybook 的完整支持,目前有部分能力不支持,具体见 [storybook-rsbuild - Rspack tasks](https://github.com/rspack-contrib/storybook-rsbuild#roadmap)。 |