@modern-js/main-doc 2.67.10 → 2.67.11

package/docs/en/guides/basic-features/debug/using-storybook.mdx

@@ -2,231 +2,47 @@
 sidebar_position: 15
 ---
 
-# Using Storybook
-
-[Storybook](https://storybook.js.org/) is a tool dedicated to component debugging, providing around component development.
-
-- Develop UIs that are more durable
-- Test UIs with less effort and no flakes
-- Document UI for your team to reuse
-- Share how the UI actually works
-- Automate UI workflows
-
-:::tip
-This tutorial is suitable for Storybook V7 users. If you are using an old version of Storybook V6 (using the @modern-js/plugin-storybook plugin), you can refer to the [Migration Guide](#migration-guide) to upgrade.
-:::
-
-## Quick Start
-
-Modern.js integrates Storybook debugging capabilities by default. You can directly enable the Storybook feature by using the following command:
-
-```bash
-$ npx modern new
-? Please select the operation you want: Enable features
-? Please select the feature name: Enable「Storybook」V7
-```
-
-This command will create a template for Storybook, including:
-
-- Creating a configuration folder .storybook and a default configuration file .storybook/main.ts.
-- Creating example story components.
-- Updating package.json to add dependencies @storybook/addon-essentials and @modern-js/storybook, as well as creating Storybook-related scripts.
-
-To start, run `npm run storybook`.
-
-## Enable Rspack build
-
-Rspack is known for its fast build speed. To use Rspack as a build tool in Modern.js, you only need to configure it as follows:
-
-```diff filename='.storybook/main.js'
-const config = {
-  framework: {
-    name: '@modern-js/storybook',
-    options: {
--      bundler: 'webpack'
-+      bundler: 'rspack'
-    },
-  },
-  typescript: {
--    reactDocgen: 'react-docgen-typescript'
-+    reactDocgen: 'react-docgen'
-  }
-};
-
-export default config;
-```
-
-Note that in the above configuration, the reactDocgen configuration has been changed because Rspack currently does not support @storybook/react-docgen-typescript-plugin.
-
-## Configurations
-
-There are some configurations in `.storybook/main.js`.
-
-### configPath
-
-- **Type**: `string`
-- **Default**: `modern.config.(j|t)s`
-
-Specify the path of Modern.js configuration.
-
-Example:
-
-```javascript filename='.storybook/main.js'
-const config = {
-  framework: {
-    name: '@modern-js/storybook',
-    options: {
-      configPath: 'modern.storybook.config.ts',
-    },
-  },
-};
-
-export default config;
-```
-
-### bundler
-
-- **Type**: `'webpack' | 'rspack'`
-- **Default**: `webpack`
-
-Specify the underlying build tool to use either Webpack or Rspack.
-
-Example:
-
-```javascript filename='.storybook/main.js'
-const config = {
-  framework: {
-    name: '@modern-js/storybook',
-    options: {
-      bundler: 'rspack',
-    },
-  },
-};
-
-export default config;
-```
-
-### builderConfig
+import { PackageManagerTabs } from '@theme'
 
-- **Type**: `BuilderConfig`
-- **Default**: `undefined`
-
-To modify the configuration of build, which has a higher priority than the configuration file, you can specify the build configuration directly here if you do not want to use the configuration file.
-
-Example:
-
-```javascript filename='.storybook/main.js'
-const config = {
-  framework: {
-    name: '@modern-js/storybook',
-    options: {
-      builderConfig: {
-        alias: {
-          react: require.resolve('react'),
-          'react-dom': require.resolve('react-dom'),
-        },
-      },
-    },
-  },
-};
-
-export default config;
-```
-
-## Command Line Interface
-
-@modern-js/storybook proxies some of the storybook cli commands.
-
-### storybook dev
-
-Start Storybook, more details at [storybook#dev](https://storybook.js.org/docs/react/api/cli-options#dev).
-
-### storybook build
-
-Build Storybook for production, more details at [storybook#build](https://storybook.js.org/docs/react/api/cli-options#build).
-
-## Storybook addon compatibility
-
-Due to the current version of Storybook in the document being version 7, please select the addon for Storybook V7.
-
-When an addon does not require additional Babel or Webpack configurations, it can be used directly, such as @storybook/addon-essentials.
-
-For some addons that require dependencies on Babel plugins and Webpack configurations, such as @storybook/addon-coverage, only @modern-js/builder-webpack-provider supports them.
-
-## Benefits
-
-Using @modern-js/storybook can bring you lightning-fast builds with Rspack, without the need for tedious configuration. It comes with many best practices for web development out-of-the-box, such as code splitting strategies, built-in support for CSS modules and postcss, TypeScript support, and commonly used Babel plugins.
-
-The powerful build capabilities of Modern.js can be directly used in Storybook projects.
-
-## Trouble Shooting
-
-1. Modern.js won't load your other configurations like `babel.config.json`, babel config needs to be set in Modern.js config, [tools.babel](/configure/app/tools/babel).
-   Webpack configuration can be written in either [tools.webpack](/configure/app/tools/webpack) or [tools.webpackChain](/configure/app/tools/webpack-chain).
-
-2. If you find that the build performance is not good, please check if the Storybook automatic documentation generation feature is enabled. For optimal performance, configure it to use `react-docgen`. The difference between `react-docgen` and `react-docgen-typescript` is that the former is implemented based on Babel, while the latter is implemented based on TypeScript. The former has better performance but weaker type inference capabilities. If you are using Rspack for the build, only `react-docgen` is supported.
-
-```javascript filename='.storybook/main.js'
-const config = {
-  typescript: {
-    reactDocgen: 'react-docgen',
-  },
-};
-
-export default config;
-```
-
-## Migration Guide
-
-### Migrate from @modern-js/plugin-storybook
-
-If you are a user migrating from V6 to V7, you can use V7 through [the above method](#quick-start) and make the following adjustments:
-
-##### Modify configuration file
-
-If you have made some custom configurations to Storybook in the older version, you need to move the configuration file `root/config/storybook/main.(j|t)s` to `root/.storybook/main.(j|t)s`.
-
-And then add the following lines in `root/.storybook/main.(j|t)s`, specify framework as `@modern-js/storybook`.
+# Using Storybook
 
-```diff
-const config = {
-+  framework: {
-+    name: '@modern-js/storybook'
-+  }
-};
+[Storybook](https://storybook.js.org/) is a tool specifically designed for component debugging. It provides:
 
-export default config;
-```
+- A rich variety of debugging capabilities
+- Integration with some testing tools
+- Reusable documentation content
+- Sharing capabilities
+- Workflow automation
 
-##### Update Dependencies
+## Principle
 
-Update dependencies like @storybook/addon-\* to major version 7.
+Rsbuild provides [Storybook Rsbuild](https://storybook.rsbuild.rs/index.html), which allows any Rsbuild project to use this tool for building Storybook.
 
-##### Remove @modern-js/plugin-storybook
+Modern.js implements `storybook-addon-modernjs` based on this tool. This plugin loads the Modern.js configuration file and converts it into a configuration usable by **Storybook Rsbuild**.
 
-在 modern.config.(j|t)s 中删除 @modern-js/plugin-storybook 插件的注册。
+:::info
+This document only provides the simplest usage. For more information, please refer to [Storybook Rsbuild Modern.js Integration](https://storybook.rsbuild.rs/guide/integrations/modernjs.html).
+:::
 
-##### Modify Storybook Syntax
+## Installation
 
-Follow the official Storybook documentation to make the necessary updates for some breaking changes, such as changes in story writing and MDX syntax. You can refer to the migration guide at [storybook migrate doc](https://storybook.js.org/docs/react/migration-guide).
+<PackageManagerTabs command="install @rsbuild/core storybook-builder-rsbuild storybook-addon-modernjs -D" />
 
-### Native Storybook users
+You need to install `@rsbuild/core` in your project, otherwise the plugin may not work properly.
 
-Modern.js only support Storybook 7, so you need to upgrade from Storybook version 6 to version 7, please follow the steps outlined in the official Storybook documentation at [storybook migrate doc](https://storybook.js.org/docs/react/migration-guide).
+## Configure `.storybook/main.ts`
 
-```diff filename='.storybook/main.js'
-const config = {
--  framework: '@storybook/react-webapck5',
-+  framework: {
-+    name: '@modern-js/storybook'
-+  },
-};
+```ts
+import type { StorybookConfig } from 'storybook-react-rsbuild'
 
-export default config;
+const config: StorybookConfig = {
+  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
+  addons: ['storybook-addon-modernjs'],
+  framework: ['storybook-react-rsbuild'],
+}
+export default config
 ```
 
-The default config file path is `modern.config.(j|t)s`, for the detail config, see [modern.js config](/configure/app/usage).
-
-If the original project includes configurations for Babel, they need to be written in the modern configuration. Most Babel configurations have already been included in Modern.js.
+## Example
 
-After installation, make the corresponding [configuration](/guides/basic-features/debug/using-storybook#configurations).
+You can check out the [example](https://github.com/rspack-contrib/storybook-rsbuild/tree/main/sandboxes/modernjs-react) to learn how to use Storybook in Modern.js.

package/docs/zh/guides/basic-features/debug/using-storybook.mdx

@@ -2,6 +2,8 @@
 sidebar_position: 15
 ---
 
+import { PackageManagerTabs } from '@theme'
+
 # 使用 Storybook
 
 [Storybook](https://storybook.js.org/) 是一个专门用于组件调试的工具，它围绕着组件开发提供了：
@@ -12,221 +14,35 @@ sidebar_position: 15
 - 可分享能力
 - 工作流程自动化
 
-:::tip
-本教程适用于新版 Storybook V7 用户，如果你在使用老版本 Storybook V6 (有使用 @modern-js/plugin-storybook 插件)，可参考 [迁移指南](#迁移指南) 进行升级。
-:::
-
-## 快速开始
-
-Modern.js 默认集成了 Storybook 的调试能力，当我们想要对组件进行调试的时候，可以通过以下方式启用 Storybook 调试功能：
-
-```bash
-$ npx modern new
-? 请选择你想要的操作 启用可选功能
-? 请选择功能名称 启用「Storybook」V7
-```
-
-该命令会创建好 Storybook 常用的模版，包括：
-
-- 创建配置文件夹 `.storybook`，以及默认配置文件 `.storybook/main.ts`
-- 创建 stories 组件示例
-- 更新 package.json，新增依赖 @storybook/addon-essential 和 @modern-js/storybook，以及创建 storybook 相关脚本
-
-运行 `npm run storybook` 即可启动 Storybook 预览。
-
-## 开启 Rspack 构建
-
-Rspack 构建速度非常快，在 Modern.js 中只需要如下配置即可使用 Rspack 作为构建工具。
-
-```diff filename='.storybook/main.js'
-const config = {
-  framework: {
-    name: '@modern-js/storybook',
-    options: {
--      bundler: 'webpack'
-+      bundler: 'rspack'
-    },
-  },
-  typescript: {
--    reactDocgen: 'react-docgen-typescript'
-+    reactDocgen: 'react-docgen'
-  }
-};
-
-export default config;
-```
-
-注意上面配置中，更改了 reactDocgen 配置，因为 Rspack 目前还不支持 @storybook/react-docgen-typescript-plugin。
-
-## 配置
-
-在 `.storybook/main.js` 中包含一些配置。
-
-### configPath
+## 原理
 
-- **类型**: `string`
-- **默认值**: `modern.config.(j|t)s`
+Rsbuild 提供了 [Storybook Rsbuild](https://storybook.rsbuild.rs/index.html)，任何 Rsbuild 的项目都可以使用该工具来实现 Storybook 的构建。
 
-用于指定配置文件路径。
+Modern.js 基于此工具实现了 `storybook-addon-modernjs`，该插件会加载 Modern.js 配置文件，并转换为 **Storybook Rsbuild** 可用的配置。
 
-例如
-
-```javascript filename='.storybook/main.js'
-const config = {
-  framework: {
-    name: '@modern-js/storybook',
-    options: {
-      configPath: 'modern.storybook.config.ts',
-    },
-  },
-};
-
-export default config;
-```
-
-### bundler
-
-- **类型**: `'webpack' | 'rspack'`
-- **默认值**: `webpack`
-
-指定底层构建工具使用 Webpack 还是 Rspack。
-
-例如
-
-```javascript filename='.storybook/main.js'
-const config = {
-  framework: {
-    name: '@modern-js/storybook',
-    options: {
-      bundler: 'rspack',
-    },
-  },
-};
-
-export default config;
-```
-
-### builderConfig
-
-- **类型**: `BuilderConfig`
-- **默认值**: `undefined`
-
-更改构建配置，该配置比配置文件拥有更高的优先级，若不想使用配置文件，也可直接在此处指定。
-
-例如
-
-```javascript filename='.storybook/main.js'
-const config = {
-  framework: {
-    name: '@modern-js/storybook',
-    options: {
-      builderConfig: {
-        alias: {
-          react: require.resolve('react'),
-          'react-dom': require.resolve('react-dom'),
-        },
-      },
-    },
-  },
-};
-
-export default config;
-```
-
-## 命令行
-
-@modern-js/storybook 代理了部分 storybook cli 的命令。
-
-### storybook dev
-
-启动 Storybook，详情请看 [storybook#dev](https://storybook.js.org/docs/react/api/cli-options#dev)
-
-### storybook build
-
-对 Storybook 进行生产环境构建，详情请看 [storybook#build](https://storybook.js.org/docs/react/api/cli-options#build)
-
-## Storybook addon 兼容性
-
-由于当前文档中的 Storybook 版本为 7，因此请选择 storybook V7 的 addon。
-
-当 addon 不需要额外的 Babel 或 Webpack 配置时，可以直接使用，如 @storybook/addon-essentials。
-
-部分 addon 需要依赖 babel 插件和 Webpack 配置时，如 @storybook/addon-coverage，只有使用 webpack 构建才会支持。
-
-## 收益
-
-使用 @modern-js/storybook 可以带给你 Rspack 超快的构建，并且完全无需繁琐配置，开箱即用。并且默认包含了许多 Web 构建中的最佳实践，例如 code splitting 策略，内置 css module 和 postcss，开箱即用的 TypeScript 支持，内置常用 Babel 插件等等。
-
-Modern.js 的构建能力和配置都可以直接在 Storybook 项目中使用。
-
-## Trouble Shooting
-
-1. 使用 Modern.js 启动 storybook 时不会读取 babel.config.json 等配置文件，因此 babel 配置需要在 [tools.babel](/configure/app/tools/babel) 中进行配置。
-   同样的 webpack 配置需要写在 [tools.webpack](/configure/app/tools/webpack) 或 [tools.webpackChain](/configure/app/tools/webpack-chain) 中。
-
-2. 如果发现构建速度很慢，请检查是否开启了自动文档生成功能，如果想要最高的性能，请配置为 `react-docgen`。`react-docgen` 和 `react-docgen-typescript` 的区别是，前者基于 Babel 实现，后者基于 TypeScript 实现，前者性能会更好，但类型推断能力更弱。如果使用 Rspack 构建，则只支持 `react-docgen`。
-
-```javascript filename='.storybook/main.js'
-const config = {
-  typescript: {
-    reactDocgen: 'react-docgen',
-  },
-};
-
-export default config;
-```
-
-## 迁移指南
-
-### 从 Modern.js Storybook V6 迁移
-
-如果你是从 V6 迁移至 V7 的用户，可以通过 [上述方式](#快速开始) 使用 V7，同时做以下调整:
-
-##### 修改配置文件
-
-若你在旧版本对 storybook 进行了一些自定义配置，需要将配置文件 `root/config/storybook/main.(j|t)s` 移动到 `root/.storybook/main.(j|t)s`。
-
-并在 `root/.storybook/main.(j|t)s` 中添加以下配置，指定 framework 为 @modern-js/storybook：
-
-```diff
-const config = {
-+  framework: {
-+    name: '@modern-js/storybook'
-+  },
-};
-
-export default config;
-```
-
-##### 依赖升级
-
-升级 @storybook/addon-\* 系列依赖，升级到 7 版本。
-
-##### 移除 @modern-js/plugin-storybook 插件
-
-在 modern.config.(j|t)s 中删除 @modern-js/plugin-storybook 插件的注册。
+:::info
+本文档仅提供最简单的使用方式，更多内容可参考 [Storybook Rsbuild Modern.js 集成](https://storybook.rsbuild.rs/guide/integrations/modernjs.html)。
+:::
 
-##### 修改 Storybook 写法
+## 安装
 
-按照 Storybook 官网文档，对一些 breaking change 做相应的更新，例如 stories 的写法，MDX 的写法等，参考[storybook 迁移文档](https://storybook.js.org/docs/react/migration-guide)。
+<PackageManagerTabs command="install @rsbuild/core storybook-builder-rsbuild storybook-addon-modernjs -D" />
 
-### 从原生 Storybook 项目迁移
+你需要在项目中安装 `@rsbuild/core`，否则该插件可能无法正常工作。
 
-若当前 Storybook 版本还是 6，需要先按照 Storybook 官网文档升级到版本 7，参考 [storybook 迁移文档](https://storybook.js.org/docs/react/migration-guide)。
+## 配置 `.storybook/main.ts`
 
-```diff filename='.storybook/main.js'
-const config = {
--  framework: '@storybook/react-webapck5',
-+  framework: {
-+    name: '@modern-js/storybook'
-+  },
-};
+```ts
+import type { StorybookConfig } from 'storybook-react-rsbuild'
 
-export default config;
+const config: StorybookConfig = {
+  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
+  addons: ['storybook-addon-modernjs'],
+  framework: ['storybook-react-rsbuild'],
+}
+export default config
 ```
 
-Modern.js 的配置文件默认为 `modern.config.(j|t)s`，配置请查看 [modern.js 配置](/configure/app/usage)。
-
-若原来项目中包含了 Babel 等配置，需要对应的写在 modern 配置中，大部分 Babel 配置已经包含进了 Modern.js。
+## 示例
 
-安装完成后进行相应的[配置](/guides/basic-features/debug/using-storybook#配置)。
+你可以查看 [示例](https://github.com/rspack-contrib/storybook-rsbuild/tree/main/sandboxes/modernjs-react) 了解 Modern.js 中使用 Storybook 的方式。

package/package.json

@@ -15,28 +15,28 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.67.10",
+  "version": "2.67.11",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "dependencies": {
     "mermaid": "^11.4.1",
-    "@modern-js/sandpack-react": "2.67.10"
+    "@modern-js/sandpack-react": "2.67.11"
   },
   "devDependencies": {
     "@rsbuild/plugin-sass": "1.3.2",
     "@shikijs/transformers": "^3.4.2",
-    "@rspress/shared": "2.0.0-beta.14",
-    "@rspress/plugin-llms": "2.0.0-beta.14",
+    "@rspress/shared": "2.0.0-beta.16",
+    "@rspress/plugin-llms": "2.0.0-beta.16",
     "@types/fs-extra": "9.0.13",
     "@types/node": "^16",
     "classnames": "^2.5.1",
     "clsx": "^1.2.1",
-    "fs-extra": "^10",
+    "fs-extra": "^10.1.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "rspress": "2.0.0-beta.14",
+    "rspress": "2.0.0-beta.16",
     "ts-node": "^10.9.1",
     "typescript": "^5"
   },