@modern-js/main-doc 2.60.0 → 2.60.1

package/docs/zh/configure/app/tools/webpack.mdx

@@ -4,6 +4,299 @@ title: webpack
 
 # tools.webpack
 
-import Main from '@modern-js/builder-doc/docs/zh/config/tools/webpack.md';
+- **类型：** `Object | Function | undefined`
+- **默认值：** `undefined`
+- **打包工具：** `仅支持 webpack`
 
-<Main />
+`tools.webpack` 选项用于配置原生的 [webpack](https://webpack.js.org/)。
+
+> `tools.bundlerChain` 同样可以修改 webpack 配置，并且功能更加强大，建议优先使用 `tools.bundlerChain`。
+
+### Object 类型
+
+`tools.webpack` 可以配置为一个对象，这个对象将会和内置的 webpack 配置通过 [webpack-merge](https://github.com/survivejs/webpack-merge) 进行深层合并。
+
+比如添加 `resolve.alias` 配置：
+
+```js
+export default {
+  tools: {
+    webpack: {
+      resolve: {
+        alias: {
+          '@util': 'src/util',
+        },
+      },
+    },
+  },
+};
+```
+
+### Function 类型
+
+`tools.webpack` 也可以配置为一个函数，这个函数的第一个入参为内置的 webpack 配置对象，你可以对这个对象进行修改，然后返回一份新的配置。比如：
+
+```js
+export default {
+  tools: {
+    webpack: config => {
+      config.resolve.alias['@util'] = 'src/util';
+      return config;
+    },
+  },
+};
+```
+
+:::tip
+`tools.webpack` 函数返回的对象会直接作为最终使用的 webpack 配置，不会再与内置的 webpack 配置进行合并。
+:::
+
+### 工具集合
+
+这个函数的第二个参数是一个对象，包含了一些工具函数和属性，详情如下：
+
+#### env
+
+- **类型：** `'development' | 'production' | 'test'`
+
+通过 env 参数可以判断当前环境为 development、production 还是 test。比如：
+
+```js
+export default {
+  tools: {
+    webpack: (config, { env }) => {
+      if (env === 'development') {
+        config.devtool = 'cheap-module-eval-source-map';
+      }
+      return config;
+    },
+  },
+};
+```
+
+#### isProd
+
+- **类型：** `boolean`
+
+通过 isProd 参数可以判断当前环境是否为 production。比如：
+
+```js
+export default {
+  tools: {
+    webpack: (config, { isProd }) => {
+      if (isProd) {
+        config.devtool = 'source-map';
+      }
+      return config;
+    },
+  },
+};
+```
+
+#### target
+
+- **类型：** `'web' | 'node' | 'modern-web' | 'web-worker'`
+
+通过 target 参数可以判断当前构建的目标运行时环境。比如：
+
+```js
+export default {
+  tools: {
+    webpack: (config, { target }) => {
+      if (target === 'node') {
+        // ...
+      }
+      return config;
+    },
+  },
+};
+```
+
+#### isServer
+
+- **类型：** `boolean`
+
+判断当前构建的目标运行时环境是否为 `node`，等价于 `target === 'node'`。
+
+```js
+export default {
+  tools: {
+    webpack: (config, { isServer }) => {
+      if (isServer) {
+        // ...
+      }
+      return config;
+    },
+  },
+};
+```
+
+#### isWebWorker
+
+- **类型：** `boolean`
+
+判断当前构建的目标运行时环境是否为 `web-worker`，等价于 `target === 'web-worker'`。
+
+```js
+export default {
+  tools: {
+    webpack: (config, { isWebWorker }) => {
+      if (isWebWorker) {
+        // ...
+      }
+      return config;
+    },
+  },
+};
+```
+
+#### webpack
+
+- **类型：** `typeof import('webpack')`
+
+通过这个参数你可以拿到 webpack 实例。比如：
+
+```js
+export default {
+  tools: {
+    webpack: (config, { webpack }) => {
+      config.plugins.push(new webpack.ProgressPlugin());
+      return config;
+    },
+  },
+};
+```
+
+#### HtmlWebpackPlugin
+
+- **类型：** `typeof import('html-webpack-plugin')`
+
+通过这个参数你可以拿到 HtmlWebpackPlugin 实例。
+
+```js
+export default {
+  tools: {
+    webpack: (chain, { HtmlWebpackPlugin }) => {
+      console.log(HtmlWebpackPlugin);
+    },
+  },
+};
+```
+
+#### addRules
+
+- **类型：** `(rules: RuleSetRule | RuleSetRule[]) => void`
+
+添加额外的 [webpack rules](https://webpack.js.org/configuration/module/#modulerules)。
+
+示例：
+
+```ts
+export default {
+  tools: {
+    webpack: (config, { addRules }) => {
+      // 添加单条规则
+      addRules({
+        test: /\.foo/,
+        loader: require.resolve('foo-loader'),
+      });
+
+      // 以数组形式添加多条规则
+      addRules([
+        {
+          test: /\.foo/,
+          loader: require.resolve('foo-loader'),
+        },
+        {
+          test: /\.bar/,
+          loader: require.resolve('bar-loader'),
+        },
+      ]);
+    },
+  },
+};
+```
+
+#### prependPlugins
+
+- **类型：** `(plugins: WebpackPluginInstance | WebpackPluginInstance[]) => void`
+
+在内部 webpack 插件数组头部添加额外的插件，数组头部的插件会优先执行。
+
+```ts
+export default {
+  tools: {
+    webpack: (config, { prependPlugins, webpack }) => {
+      // 添加单个插件
+      prependPlugins(
+        new webpack.BannerPlugin({
+          banner: 'hello world!',
+        }),
+      );
+
+      // 以数组形式添加多个插件
+      prependPlugins([new PluginA(), new PluginB()]);
+    },
+  },
+};
+```
+
+#### appendPlugins
+
+- **类型：** `(plugins: WebpackPluginInstance | WebpackPluginInstance[]) => void`
+
+在内部 webpack 插件数组尾部添加额外的插件，数组尾部的插件会在最后执行。
+
+```ts
+export default {
+  tools: {
+    webpack: (config, { appendPlugins, webpack }) => {
+      // 添加单个插件
+      appendPlugins([
+        new webpack.BannerPlugin({
+          banner: 'hello world!',
+        }),
+      ]);
+
+      // 以数组形式添加多个插件
+      appendPlugins([new PluginA(), new PluginB()]);
+    },
+  },
+};
+```
+
+#### removePlugin
+
+- **类型：** `(name: string) => void`
+
+删除内部的 webpack 插件，参数为该插件的 `constructor.name`。
+
+例如，删除内部的 [fork-ts-checker-webpack-plugin](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin)：
+
+```ts
+export default {
+  tools: {
+    webpack: (config, { removePlugin }) => {
+      removePlugin('ForkTsCheckerWebpackPlugin');
+    },
+  },
+};
+```
+
+#### mergeConfig
+
+- **类型：** `(...configs: WebpackConfig[]) => WebpackConfig`
+
+用于合并多份 webpack 配置，等价于 [webpack-merge](https://github.com/survivejs/webpack-merge)。
+
+```ts
+export default {
+  tools: {
+    webpack: (config, { mergeConfig }) => {
+      return mergeConfig(config, {
+        devtool: 'eval',
+      });
+    },
+  },
+};
+```

package/docs/zh/guides/advanced-features/_meta.json

@@ -14,7 +14,6 @@
   },
   "build-performance",
   "compatibility",
-  "eslint",
   "low-level",
   "source-build",
   "web-server"

package/docs/zh/guides/advanced-features/rspack-start.mdx

@@ -4,7 +4,7 @@ sidebar_position: 1
 
 # 使用 Rspack
 
-import Rspack from '@modern-js/builder-doc/docs/zh/shared/rspackTip.mdx';
+import Rspack from '@site-docs/components/rspackTip.mdx';
 
 <Rspack />
 
@@ -42,7 +42,7 @@ export default defineConfig({
 如果你当前版本低于 MAJOR_VERSION.59.0，可通过执行 `npx modern upgrade` 进行升级。
 :::
 
-import RspackPrecautions from '@modern-js/builder-doc/docs/zh/shared/rspackPrecautions.md';
+import RspackPrecautions from '@site-docs/components/rspackPrecautions.mdx';
 
 <RspackPrecautions />
 

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

@@ -167,7 +167,7 @@ declare module '*.styl' {
 
 上述方法虽然可以解决 CSS Modules 在 TypeScript 中的类型问题，但是无法准确地提示出某个 CSS 文件导出了哪些类名。
 
-Builder 支持为 CSS Modules 生成准确的类型声明，你只需要开启 [output.enableCssModuleTSDeclaration](/configure/app/output/enable-css-module-tsdeclaration) 配置项，再执行构建命令，Builder 就会为项目中所有的 CSS Modules 文件生成相应的类型声明文件。
+Modern.js 支持为 CSS Modules 生成准确的类型声明，你只需要开启 [output.enableCssModuleTSDeclaration](/configure/app/output/enable-css-module-tsdeclaration) 配置项，再执行构建命令，Modern.js 就会为项目中所有的 CSS Modules 文件生成相应的类型声明文件。
 
 ```ts
 export default {

package/docs/zh/guides/basic-features/output-files.mdx

@@ -42,7 +42,7 @@ dist
 
 ## 修改产物目录
 
-Builder 提供了多个配置项来修改产物目录和产物名称，你可以：
+Modern.js 提供了多个配置项来修改产物目录和产物名称，你可以：
 
 - 通过 [output.filename](/configure/app/output/filename) 来修改产物的文件名。
 - 通过 [output.distPath](/configure/app/output/dist-path) 来修改产物的输出路径。
@@ -158,7 +158,7 @@ dist
 
 ## 产物不写入磁盘
 
-默认情况下，Builder 会将构建产物写入磁盘，以方便开发者查看产物的内容，或是配置静态资源的代理规则。
+默认情况下，Modern.js 会将构建产物写入磁盘，以方便开发者查看产物的内容，或是配置静态资源的代理规则。
 
 在开发环境，你可以选择将构建产物保存在 Dev Server 的内存中，从而减少文件操作产生的开销。
 

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

@@ -4,7 +4,7 @@ sidebar_position: 2
 
 # 构建工具
 
-Modern.js 内部基于 [Rsbuild](https://rsbuild.dev/) 封装了自身的构建工具（Modern.js Builder），并支持在 Webpack 和 Rspack 两种打包工具间无缝切换。
+Modern.js 构建是基于 [Rsbuild](https://rsbuild.dev/) 实现的，并支持在 Webpack 和 Rspack 两种打包工具间无缝切换。
 
 :::tip 什么是 Rsbuild
 Rsbuild 是基于 Rspack 的构建工具，是一个增强版的 Rspack CLI，更易用、开箱即用。

package/docs/zh/guides/get-started/glossary.mdx

@@ -12,13 +12,13 @@ BFF 服务作为前端应用程序和服务端 API 之间的中介，可以为
 
 ## Bundler
 
-import Bundler from '@modern-js/builder-doc/docs/zh/shared/bundler.md';
+import Bundler from '@site-docs/components/bundler.mdx';
 
 <Bundler />
 
 ## Builder
 
-import Builder from '@modern-js/builder-doc/docs/zh/shared/builder.md';
+import Builder from '@site-docs/components/builder.mdx';
 
 <Builder />
 
@@ -36,25 +36,25 @@ CSR 是 "Client-Side Rendering"（客户端渲染）的缩写。它表示页面
 
 ## Micro-frontend
 
-import MicroFrontend from '@modern-js/builder-doc/docs/zh/shared/micro-frontend.md';
+import MicroFrontend from '@site-docs/components/micro-frontend.mdx';
 
 <MicroFrontend />
 
 ## Module Federation
 
-import ModuleFederation from '@modern-js/builder-doc/docs/zh/shared/module-federation.md';
+import ModuleFederation from '@site-docs/components/module-federation.mdx';
 
 <ModuleFederation />
 
 ## Rsbuild
 
-import Rsbuild from '@modern-js/builder-doc/docs/zh/shared/rsbuild.md';
+import Rsbuild from '@site-docs/components/rsbuild.mdx';
 
 <Rsbuild />
 
 ## Rspack
 
-import Rspack from '@modern-js/builder-doc/docs/zh/shared/rspack.md';
+import Rspack from '@site-docs/components/rspack.mdx';
 
 <Rspack />
 
@@ -76,6 +76,6 @@ SSG 是 "Static Site Generation"（静态网站生成）的缩写。它表示网
 
 ## SWC
 
-import SWC from '@modern-js/builder-doc/docs/zh/shared/swc.md';
+import SWC from '@site-docs/components/swc.mdx';
 
 <SWC />

package/docs/zh/guides/get-started/quick-start.mdx

@@ -72,7 +72,7 @@ export default defineConfig({
 
 - 提供 `modern dev`, `modern build` 等常用的 CLI 命令。
 - 集成 Modern.js Core，提供配置解析、插件加载等能力。
-- 集成 Modern.js Builder，提供构建能力。
+- 集成 Rsbuild，提供构建能力。
 - 集成 Modern.js Server，提供开发和生产服务器相关能力。
 
 `@modern-js/app-tools` 是基于 Modern.js 的插件体系实现的，本质上是一个插件，因此你需要在配置文件的 `plugins` 字段中注册 `appTools`：

package/docs/zh/guides/topic-detail/_meta.json

@@ -10,11 +10,5 @@
     "name": "model",
     "label": "reduck",
     "collapsed": true
-  },
-  {
-    "type": "dir",
-    "name": "generator",
-    "label": "generator",
-    "collapsed": true
   }
 ]

package/docs/zh/guides/topic-detail/micro-frontend/c01-introduction.mdx

@@ -4,7 +4,7 @@ sidebar_position: 1
 
 # 微前端介绍
 
-import MicroFrontend from '@modern-js/builder-doc/docs/zh/shared/micro-frontend.md';
+import MicroFrontend from '@site-docs/components/micro-frontend.mdx';
 
 <MicroFrontend />
 

package/docs/zh/guides/topic-detail/model/quick-start.mdx

@@ -2,6 +2,11 @@
 sidebar_position: 1
 title: 快速上手
 ---
+
+:::caution
+新项目不再推荐使用 Reduck，可以使用社区中的状态管理工具，例如 [Jotai](https://jotai.org/)、[zustand](https://zustand.docs.pmnd.rs/getting-started/introduction)、[valtio](https://valtio.dev/docs/introduction/getting-started) 等。
+:::
+
 # 快速上手
 
 import ReduckMigration from "@site-docs/components/reduck-migration"

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

@@ -40,8 +40,8 @@ Modern.js 提供 [inspect 命令](/apis/app/commands.html) 用于查看项目最
 
 Inspect config succeed, open following files to view the content:
 
-  - Builder Config: /root/my-project/dist/builder.config.js
-  - Rspack Config (web): /root/my-project/dist/rspack.config.web.js
+  - Rsbuild Config: /root/my-project/dist/rsbuild.config.mjs
+  - Rspack Config (web): /root/my-project/dist/rspack.config.web.mjs
 ```
 
 ---

package/docs/zh/plugin/cli-plugins/plugin-swc.mdx

@@ -11,7 +11,7 @@ sidebar_position: 2
 
 :::
 
-import SWC from '@modern-js/builder-doc/docs/zh/shared/swc.md';
+import SWC from '@site-docs/components/swc.mdx';
 
 <SWC />
 
@@ -51,9 +51,9 @@ import SWC from '@modern-js/builder-doc/docs/zh/shared/swc.md';
 
 ### 在 Modern.js 框架中使用
 
-Modern.js 框架对 Builder 的 SWC 插件进行了封装，你可以通过以下方式来使用：
+Modern.js 框架对 SWC 插件进行了封装，你可以通过以下方式来使用：
 
-import EnableSWC from '@modern-js/builder-doc/docs/zh/shared/enableSwc.md';
+import EnableSWC from '@site-docs/components/enableSwc.mdx';
 
 <EnableSWC />
 
@@ -285,7 +285,7 @@ boolean | {
 #### extensions.pluginImport
 
 :::tip
-Builder 提供了 [source.transformImport](/configure/app/source/transform-import) 配置项，因此你不需要手动配置 `extensions.pluginImport`。
+Modern.js 提供了 [source.transformImport](/configure/app/source/transform-import) 配置项，因此你不需要手动配置 `extensions.pluginImport`。
 :::
 
 移植自 [babel-plugin-import](https://github.com/umijs/babel-plugin-import)，配置选项保持一致。

package/docs/zh/plugin/rsbuild-plugins/plugin-esbuild.mdx

@@ -11,7 +11,7 @@ sidebar_position: 3
 
 :::
 
-import Esbuild from '@modern-js/builder-doc/docs/zh/shared/esbuild.md';
+import Esbuild from '@site-docs/components/esbuild.mdx';
 
 <Esbuild />
 
@@ -19,7 +19,7 @@ import Esbuild from '@modern-js/builder-doc/docs/zh/shared/esbuild.md';
 
 ### 在 Modern.js 框架中使用
 
-Modern.js 框架默认集成了 Builder 的 esbuild 插件，因此，你不需要手动安装和注册插件，只需要使用 [tools.esbuild](/configure/app/tools/esbuild.html) 配置项即可：
+Modern.js 框架默认集成了 esbuild 插件，因此，你不需要手动安装和注册插件，只需要使用 [tools.esbuild](/configure/app/tools/esbuild.html) 配置项即可：
 
 ```js
 export default defineConfig({
@@ -102,7 +102,7 @@ builderPluginEsbuild({
 
 #### 关闭代码转译
 
-将 `loader` 设置为 `false` 来关闭 esbuild 代码转译，此时 Builder 会继续使用 Babel 来进行代码转译。
+将 `loader` 设置为 `false` 来关闭 esbuild 代码转译，此时 Modern.js 会继续使用 Babel 来进行代码转译。
 
 ```ts
 builderPluginEsbuild({
@@ -146,7 +146,7 @@ builderPluginEsbuild({
 
 #### 关闭代码压缩
 
-将 `minimize` 设置为 `false` 来关闭 esbuild 代码压缩，此时 Builder 会继续使用 Terser 进行代码压缩。
+将 `minimize` 设置为 `false` 来关闭 esbuild 代码压缩，此时 Modern.js 会继续使用 Terser 进行代码压缩。
 
 ```ts
 builderPluginEsbuild({
@@ -156,7 +156,7 @@ builderPluginEsbuild({
 
 ## esbuild 局限性
 
-虽然 esbuild 能给现有的 webpack 项目带来明显的构建性能提升，但这个工具在接入 Builder 时还存在一定的局限性，需要大家在接入的时候格外注意。
+虽然 esbuild 能给现有的 webpack 项目带来明显的构建性能提升，但这个工具在接入 Modern.js 时还存在一定的局限性，需要大家在接入的时候格外注意。
 
 ### 兼容性
 
@@ -190,7 +190,7 @@ builderPluginEsbuild({
 
 ### 不支持 Babel 插件
 
-使用 esbuild 进行代码转译时，诸如 `babel-plugin-import` 等原有 Babel 插件的语法编译功能在开启 esbuild 后无法使用。并且由于 Builder 底层使用的是 esbuild 的 `Transform API`，因此不支持使用额外 esbuild 插件来进行自定义编译过程。
+使用 esbuild 进行代码转译时，诸如 `babel-plugin-import` 等原有 Babel 插件的语法编译功能在开启 esbuild 后无法使用。并且由于 Modern.js 底层使用的是 esbuild 的 `Transform API`，因此不支持使用额外 esbuild 插件来进行自定义编译过程。
 
 如果你有 `babel-plugin-import` 等 Babel 插件相关诉求，可以使用 SWC 插件。
 

package/package.json

@@ -15,20 +15,17 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.60.0",
+  "version": "2.60.1",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public",
     "provenance": true
   },
   "dependencies": {
-    "@modern-js/sandpack-react": "2.60.0"
-  },
-  "peerDependencies": {
-    "@modern-js/builder-doc": "^2.60.0"
+    "@modern-js/sandpack-react": "2.60.1"
   },
   "devDependencies": {
-    "@rspress/shared": "1.28.2",
+    "@rspress/shared": "1.31.0",
     "@types/fs-extra": "9.0.13",
     "@types/node": "^16",
     "classnames": "^2",
@@ -36,16 +33,14 @@
     "fs-extra": "^10",
     "react": "^18",
     "react-dom": "^18",
-    "rspress": "1.28.2",
+    "rspress": "1.31.0",
     "ts-node": "^10.9.1",
-    "typescript": "^5",
-    "@modern-js/builder-doc": "2.60.0"
+    "typescript": "^5"
   },
   "scripts": {
     "dev": "rspress dev",
     "dev:no_lazy": "LAZY=false rspress dev",
-    "build": "npx ts-node ./scripts/sync.ts",
-    "build:doc": "rspress build",
+    "build": "rspress build",
     "preview": "rspress preview"
   }
 }

package/src/components/RsbuildLink/index.tsx

@@ -0,0 +1,19 @@
+import React from 'react';
+import { useLang } from 'rspress/runtime';
+
+const RsbuildLInk = ({ configName }: { configName: string }) => {
+  const lang = useLang();
+  const href = `https://rsbuild.dev/${lang === 'zh' ? 'zh/' : ''}config/${configName
+    .split('.')
+    .join('/')
+    .replace(/([a-z])([A-Z])/g, '$1-$2')
+    .toLowerCase()}`;
+
+  return (
+    <a href={href} target="__blank">
+      Rsbuild - {configName}
+    </a>
+  );
+};
+
+export default RsbuildLInk;