Skip to content

Commit

Permalink
docs: change Storybook migration to storybook-rsbuild
Browse files Browse the repository at this point in the history
  • Loading branch information
fi3ework committed May 22, 2024
1 parent c7db90a commit d991555
Show file tree
Hide file tree
Showing 2 changed files with 54 additions and 57 deletions.
57 changes: 28 additions & 29 deletions website/docs/en/guide/migration/storybook.mdx
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.
54 changes: 26 additions & 28 deletions website/docs/zh/guide/migration/storybook.mdx
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)

0 comments on commit d991555

Please sign in to comment.