@modern-js/main-doc 2.46.0 → 2.47.0

package/docs/zh/guides/advanced-features/using-storybook.mdx

@@ -2,12 +2,7 @@
 sidebar_position: 15
 ---
 
-# 使用 StorybookV6
-
-:::warning
-该教程是用于老版本 StorybookV6 用户，并且会在以后弃用，想要从旧版本插件升级或新用户想要尝试请查看[新文档](https://modernjs.dev/builder/guide/advanced/storybook.html)
-:::
-
+# 使用 Storybook
 
 [Storybook](https://storybook.js.org/) 是一个专门用于组件调试的工具，它围绕着组件开发提供了：
 
@@ -17,33 +12,221 @@ sidebar_position: 15
 - 可分享能力
 - 工作流程自动化
 
-## 开启 Storybook 调试
+:::tip
+本教程适用于新版 Storybook V7 用户，如果你在使用老版本 Storybook V6 (有使用 @modern-js/plugin-storybook 插件)，可参考 [迁移指南](#迁移指南) 进行升级。
+:::
 
-Modern.js 默认集成了 Storybook 的调试能力。
+## 快速开始
 
-当我们想要对组件进行调试的时候，可以通过 `pnpm run new` 启用 Storybook 调试功能。
+Modern.js 默认集成了 Storybook 的调试能力，当我们想要对组件进行调试的时候，可以通过以下方式启用 Storybook 调试功能：
 
 ```bash
 $ npx modern new
 ? 请选择你想要的操作 启用可选功能
-? 请选择功能名称 启用「Visual Testing (Storybook)」模式
+? 请选择功能名称 启用「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`
+
+用于指定配置文件路径。
+
+例如
+
+```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.config.ts` 文件中注册 Modern.js 的 Storybook 插件，即可启用 Storybook 调试能力。
+## 命令行
+
+@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。
 
-```ts title="modern.config.ts"
-import { appTools, defineConfig } from '@modern-js/app-tools';
-import { storybookPlugin } from '@modern-js/plugin-storybook';
+部分 addon 需要依赖 babel 插件和 Webpack 配置时，如 @storybook/addon-coverage，只有使用 webpack 构建才会支持。
 
-export default defineConfig({
-  plugins: [appTools(), storybookPlugin()],
-});
+## 收益
+
+使用 @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 插件的注册。
+
+##### 修改 Storybook 写法
+
+按照 Storybook 官网文档，对一些 breaking change 做相应的更新，例如 stories 的写法，MDX 的写法等，参考[storybook 迁移文档](https://storybook.js.org/docs/react/migration-guide)。
+
+### 从原生 Storybook 项目迁移
+
+若当前 Storybook 版本还是 6，需要先按照 Storybook 官网文档升级到版本 7，参考 [storybook 迁移文档](https://storybook.js.org/docs/react/migration-guide)。
+
+```diff filename='.storybook/main.js'
+const config = {
+-  framework: '@storybook/react-webapck5',
++  framework: {
++    name: '@modern-js/storybook'
++  },
+};
+
+export default config;
+```
 
-Modern.js 默认识别项目源码目录 src/ 下 [\*.stories.(js|jsx|ts|tsx|mdx)](/apis/app/hooks/src/stories.html) 格式的文件作为 Storybook 的调试文件。
+Modern.js 的配置文件默认为 `modern.config.(j|t)s`，配置请查看 [modern.js 配置](/configure/app/usage)。
 
-## 配置 Storybook
+若原来项目中包含了 Babel 等配置，需要对应的写在 modern 配置中，大部分 Babel 配置已经包含进了 Modern.js。
 
-在 Modern.js 中，可以在项目的 [`config/storybook`](/apis/app/hooks/config/storybook.html) 目录下增加 Storybook 配置文件。
+安装完成后进行相应的[配置](/guides/advanced-features/using-storybook#配置)。

package/docs/zh/guides/basic-features/css.mdx

@@ -12,13 +12,13 @@ Modern.js 内置了社区流行的 CSS 预处理器，包括 Less 和 Sass。
 
 默认情况下，你不需要对 Less 和 Sass 进行任何配置。如果你有自定义 loader 配置的需求，可以通过配置 [tools.less](/configure/app/tools/less)、[tools.sass](/configure/app/tools/sass) 来进行设置。
 
-你也可以在 Modern.js 中使用 Stylus，只需要安装 Modern.js Builder 提供的 Stylus 插件即可，使用方式请参考 [Stylus 插件](https://modernjs.dev/builder/plugins/plugin-stylus.html)。
+你也可以在 Modern.js 中使用 Stylus，只需要安装 Rsbuild 提供的 Stylus 插件即可，使用方式请参考 [Stylus 插件](https://rsbuild.dev/zh/plugins/list/plugin-stylus)。
 
 ## 使用 PostCSS
 
 Modern.js 内置了 [PostCSS](https://postcss.org/) 来转换 CSS 代码。
 
-请阅读 [Modern.js Builder - 使用 PostCSS](https://modernjs.dev/builder/guide/basic/css-usage.html#%E4%BD%BF%E7%94%A8-postcss) 了解更多用法。
+请阅读 [Rsbuild - 使用 PostCSS](https://rsbuild.dev/zh/guide/basic/css-usage#%E4%BD%BF%E7%94%A8-postcss) 了解更多用法。
 
 ## 使用 CSS Modules
 

package/docs/zh/guides/concept/builder.mdx

@@ -4,44 +4,42 @@ sidebar_position: 2
 
 # 构建工具
 
-**Modern.js 的构建能力由 [Modern.js Builder](https://modernjs.dev/builder) 提供。**
+Modern.js 内部基于 [Rsbuild](https://rsbuild.dev/) 封装了自身的构建工具（Modern.js Builder），并支持在 Webpack 和 Rspack 两种打包工具间无缝切换。
 
-Modern.js Builder 是 Modern.js 体系的核心组件之一，它是一个基于 Rspack 的 Web 构建工具，可以脱离 Modern.js 被独立使用。Modern.js Builder 同时支持 webpack 和 Rspack 等多种打包工具，默认情况下使用最成熟的 webpack 进行打包。
+:::tip 什么是 Rsbuild
+Rsbuild 是基于 Rspack 的构建工具，是一个增强版的 Rspack CLI，更易用、开箱即用。
+:::
 
 ## 构建架构
 
 从构建的角度看，Modern.js 分为三层架构，从上到下依次是：
 
-- 上层研发框架：Modern.js。
-- 通用构建工具：Modern.js Builder。
-- 底层打包工具：webpack 和 Rspack。
+- 研发框架：Modern.js（开源）和 EdenX（内部）。
+- 构建工具：Rsbuild。
+- 打包工具：Webpack 和 Rspack。
 
-<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/builder-layers-0824.png" style={{ width: '100%', maxWidth: '540px' }} />
+<img
+  src="https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/build-layers-02193.png"
+  style={{ width: '100%', maxWidth: '540px' }}
+/>
 
 ## 构建文档
 
-由于 Modern.js Builder 是一个可独立使用的模块，我们为它提供了单独的文档，文档地址为：[modernjs.dev/builder](https://modernjs.dev/builder)。
+Rsbuild 的文档地址为：https://rsbuild.dev/
 
-在该文档中，你可以了解到 Modern.js Builder 的详细介绍，同时也可以找到各个构建能力的完整使用指南。当你遇到构建方面的需求或问题时，建议你优先阅读 Modern.js Builder 文档来解决。
+在该文档中，你可以了解到 Rsbuild 的详细介绍，同时也可以找到各个构建能力的完整使用指南。
 
-## 构建配置
+如果你想要了解某些构建配置的使用，建议你优先阅读 Modern.js 文档，因为 Modern.js 中的构建配置和默认值与 Rsbuild 并不完全相同。
 
-Modern.js 的配置继承自 Modern.js Builder，因此你可以在 Modern.js 中使用 Modern.js Builder 提供的所有构建配置。
+## 构建插件
 
-以 Modern.js Builder 的 `html.title` 配置项为例，你可以直接在 `modern.config.ts` 文件中使用该配置项，它会被自动传递给 Modern.js Builder。
+在 Modern.js 中，你可以注册 Webpack 插件、Rspack 插件或 Rsbuild 插件：
 
-```ts title="modern.config.js"
-export default defineConfig({
-  html: {
-    title: 'example',
-  },
-});
-```
-
-关于构建配置的详细说明，请参考 [「Modern.js Builder - Builder 配置」](https://modernjs.dev/builder/guide/basic/builder-config.html)。
+- Webpack / Rspack 插件：通过 [tools.bundlerChain](/configure/app/tools/bundler-chain) 配置。
+- Rsbuild 插件：通过 [builderPlugins](/configure/app/builder-plugins) 配置。
 
 ## 构建能力
 
-Modern.js Builder 提供了丰富的构建能力，包括 JavaScript 编译、CSS 编译、静态资源处理、代码热更新、代码压缩、TS 类型检查等几十种能力。
+Rsbuild 提供了丰富的构建能力，包括 JavaScript 编译、CSS 编译、静态资源处理、代码热更新、代码压缩、TS 类型检查等几十种能力。
 
-我们推荐你阅读 [「Modern.js Builder - 功能导航」](https://modernjs.dev/builder/guide/features.html) 来了解 Modern.js Builder 提供的所有构建能力。
+我们推荐你阅读 [「Rsbuild - 功能导航」](https://rsbuild.dev/zh/guide/start/features) 来了解 Rsbuild 提供的所有构建能力。

package/docs/zh/guides/get-started/tech-stack.mdx

@@ -89,7 +89,7 @@ Modern.js 支持[「启用 Tailwind CSS」](/guides/basic-features/css.html#使
 Modern.js 支持 [Sass](https://sass-lang.com/)、[Less](https://lesscss.org/) 和 [Stylus](https://stylus-lang.com/) 三种 CSS 预处理器：
 
 - 默认支持 Sass 和 Less，开箱即用。
-- 可选支持 Stylus，请参考[「Stylus 插件」](https://modernjs.dev/builder/plugins/plugin-stylus.html) 来使用。
+- 可选支持 Stylus，请参考[「Stylus 插件」](https://rsbuild.dev/zh/plugins/list/plugin-stylus) 来使用。
 
 ---
 

package/docs/zh/guides/topic-detail/framework-plugin/introduction.mdx

@@ -10,7 +10,7 @@ Modern.js 提供了一套拥有完整生命周期的插件系统。插件可用
 
 ## 使用方式
 
-插件需要在配置文件中显示注册才能够生效，当需要为 Modern.js 添加插件时，可以将它配置到 [plugin](/configure/app/plugins.html) 字段中：
+插件需要在配置文件中显式注册才能够生效，当需要为 Modern.js 添加插件时，可以将它配置到 [plugins](/configure/app/plugins.html) 字段中：
 
 ```ts title="edenx.config.ts"
 // an example for bff

package/docs/zh/guides/topic-detail/micro-frontend/c02-development.mdx

@@ -12,14 +12,13 @@ title: 体验微前端
 
 ## 创建应用
 
-目前支持两种路由模式
+目前项目的路由模式分为以下三种
 
-- 自控式路由
-- 约定式路由
+- 约定式路由 (设置 `router: true` 并使用文件路由)
+- 自控式路由 (设置 `router: true` 并自己创建 `BrowserRouter` 等)
+- 其他 (设置 `router: false` 项目内自己安装和使用 `react-router-dom`)
 
-首先明确主应用的路由模式 [创建约定式路由主应用](#创建约定式路由主应用) 或 [创建自控式路由主应用](#创建自控式路由主应用)
-
-在本次体验中我们会为主应用创建两个子应用 Table 和 Dashboard (Table 为约定式路由，Dashboard 为自控式路由)
+在本教程中我们会为主应用创建两个子应用 Table 和 Dashboard (Table 为约定式路由，Dashboard 为自控式路由)
 
 ### 创建约定式路由主应用
 
@@ -145,6 +144,36 @@ import CustomRouterMicroFrontend from '@site-docs/components/custom-router-micro
 
 <CustomRouterMicroFrontend />
 
+### 创建其他主应用
+
+项目内自己安装和使用 `react-router-dom` , 与自控式路由唯一的区别是, 设置 `router: false` 后 plugin-garfish 无法获得 `useLocation` `useHref` 等 hook 来辅助计算 basename 和主子应用路由同步
+
+import { Tab, Tabs } from 'rspress/theme';
+
+<Tabs>
+<Tab label="react-router-dom@6">
+```tsx
+import { useLocation, useHref } from 'react-router-dom';
+const App = () => {
+  const basename = useHref('/table');
+  const { Table } = useModuleApps();
+  return <Table useLocation={useLocation} basename={basename} />;
+};
+```
+</Tab>
+<Tab label="react-router-dom@5">
+```tsx
+import { useLocation, useHistory } from 'react-router-dom';
+const App = () => {
+  const history = useHistory();
+  const basename = history.createHref({ pathname: '/table' });
+  const { Table } = useModuleApps();
+  return <Table useLocation={useLocation} basename={basename} />;
+};
+```
+</Tab>
+</Tabs>
+
 ### 创建约定式路由子应用
 
 通过命令行工具初始化项目：

package/package.json

@@ -15,17 +15,17 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.46.0",
+  "version": "2.47.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public",
     "provenance": true
   },
   "dependencies": {
-    "@modern-js/sandpack-react": "2.46.0"
+    "@modern-js/sandpack-react": "2.47.0"
   },
   "peerDependencies": {
-    "@modern-js/builder-doc": "^2.46.0"
+    "@modern-js/builder-doc": "^2.47.0"
   },
   "devDependencies": {
     "classnames": "^2",
@@ -35,12 +35,12 @@
     "ts-node": "^10.9.1",
     "typescript": "^5",
     "fs-extra": "^10",
-    "rspress": "1.9.3",
-    "@rspress/shared": "1.9.3",
+    "rspress": "1.11.2",
+    "@rspress/shared": "1.11.2",
     "@types/node": "^16",
     "@types/fs-extra": "9.0.13",
-    "@modern-js/doc-plugin-auto-sidebar": "2.46.0",
-    "@modern-js/builder-doc": "2.46.0"
+    "@modern-js/builder-doc": "2.47.0",
+    "@modern-js/doc-plugin-auto-sidebar": "2.47.0"
   },
   "scripts": {
     "dev": "rspress dev",

package/docs/en/configure/app/source/compile-js-data-uri.mdx

@@ -1,9 +0,0 @@
----
-sidebar_label: compileJsDataURI
----
-
-# source.compileJsDataURI
-
-import Main from '@modern-js/builder-doc/docs/en/config/source/compileJsDataURI.md';
-
-<Main />

package/docs/zh/configure/app/source/compile-js-data-uri.mdx

@@ -1,9 +0,0 @@
----
-sidebar_label: compileJsDataURI
----
-
-# source.compileJsDataURI
-
-import Main from '@modern-js/builder-doc/docs/zh/config/source/compileJsDataURI.md';
-
-<Main />