@modern-js/main-doc 2.69.7 → 3.0.0-alpha.1

package/docs/zh/configure/app/source/include.mdx

@@ -9,10 +9,7 @@ title: include
 
 ```ts
 const defaultInclude = [
-  [
-    { not: /[\\/]node_modules[\\/]/ },
-    /\.(?:ts|tsx|jsx|mts|cts)$/,
-  ],
+  [{ not: /[\\/]node_modules[\\/]/ }, /\.(?:ts|tsx|jsx|mts|cts)$/],
 ];
 ```
 
@@ -28,10 +25,7 @@ const defaultInclude = [
 const defaultInclude = [
   [
     {
-      and: [
-        APP_ROOT,
-        { not: /[\\/]node_modules[\\/]/ }
-      ]
+      and: [APP_ROOT, { not: /[\\/]node_modules[\\/]/ }],
     },
     /\.(?:ts|tsx|jsx|mts|cts)$/,
   ],
@@ -41,14 +35,6 @@ const defaultInclude = [
 与新版本的差异是，非当前项目目录的 `.js`、`.mjs`、`.cjs` 文件不会被编译。
 :::
 
-## Rspack
-
 import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
 
 <RsbuildConfig configName="source.include" />
-
-## Webpack
-
-为了保证历史项目可以正常运行，Webpack 编译时，`source.include` 与 Rsbuild 1.4 版本前的默认值一致。
-
-

package/docs/zh/configure/app/source/main-entry-name.mdx

@@ -5,18 +5,18 @@ title: mainEntryName
 # source.mainEntryName
 
 - **类型：** `string`
-- **默认值：** `'main'`
+- **默认值：** `'index'`
 
 该选项用于配置 Modern.js 的主入口名称。
 
-默认情况下，Modern.js 的默认主入口名称为 `main`，当使用单入口或者入口名称和 `package.json` 中 name 字段一致时，会将对应入口作为主入口，通过该配置可以修改主入口的名称。
+默认情况下，Modern.js 的默认主入口名称为 `index`，当使用单入口或者入口名称和 `package.json` 中 name 字段一致时，会将对应入口作为主入口，通过该配置可以修改主入口的名称。
 
-比如将主入口名称改为 index：
+比如将主入口名称改为 main：
 
 ```ts title="modern.config.ts"
 export default defineConfig({
   source: {
-    mainEntryName: 'index',
+    mainEntryName: 'main',
   },
 });
 ```

package/docs/zh/configure/app/source/transform-import.mdx

@@ -24,66 +24,8 @@ type TransformImport =
   | Function;
 ```
 
-- **默认值:**
-
-当项目中安装了 [Ant Design 组件库](https://www.npmjs.com/package/antd) <= 4.x 版本时，Modern.js 会自动添加以下默认配置：
-
-```js
-const defaultAntdConfig = {
-  libraryName: 'antd',
-  libraryDirectory: isServer ? 'lib' : 'es',
-  style: true,
-};
-```
-
-当项目中安装了 [Arco Design 组件库](https://www.npmjs.com/package/@arco-design/web-react) 时，Modern.js 会自动添加以下默认配置：
-
-```js
-const defaultArcoConfig = [
-  {
-    libraryName: '@arco-design/web-react',
-    libraryDirectory: isServer ? 'lib' : 'es',
-    camelToDashComponentName: false,
-    style: true,
-  },
-  {
-    libraryName: '@arco-design/web-react/icon',
-    libraryDirectory: isServer ? 'react-icon-cjs' : 'react-icon',
-    camelToDashComponentName: false,
-  },
-];
-```
-
-:::tip
-当你添加了 `antd` 或 `@arco-design/web-react` 相关的配置时，优先级会高于上述默认配置。
-:::
+- **默认值：** `undefined`
 
 import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
 
 <RsbuildConfig configName="source.transformImport" />
-
-### 禁用默认配置
-
-你可以手动设置 `transformImport: false` 来关掉 transformImport 的默认行为。
-
-```js
-export default {
-  source: {
-    transformImport: false,
-  },
-};
-```
-
-你也可以使用 `transformImport` 的 [function 用法](https://rsbuild.rs/zh/config/source/transform-import#function-%E7%B1%BB%E5%9E%8B) 对默认配置进行自定义修改。
-
-```js
-export default {
-  source: {
-    transformImport: imports => {
-      return imports.filter(data => data.libraryName !== 'antd');
-    },
-  },
-};
-```
-
-比如，当你使用了 `externals` 来避免打包 antd 时，由于 `transformImport` 默认会转换 antd 的引用路径，导致匹配的路径发生了变化，因此 externals 无法正确生效，此时你可以设置关闭 `transformImport` 来避免该问题。

package/docs/zh/configure/app/tools/bundler-chain.mdx

@@ -8,26 +8,26 @@ title: bundlerChain
 
 ```ts
 type BundlerChainFn = (
-  chain: RspackChain | webpackChain,
+  chain: RspackChain,
   utils: ModifyBundlerChainUtils,
 ) => Promise<void> | void;
 ```
 
 - **默认值：** `undefined`
 
-你可以通过 `tools.bundlerChain` 来修改默认的 webpack 和 Rspack 配置，它的值为 `Function` 类型，接收两个参数：
+你可以通过 `tools.bundlerChain` 来修改默认的 Rspack 配置，它的值为 `Function` 类型，接收两个参数：
 
-- 第一个参数为 `bundler-chain` 对象实例，你可以通过这个实例来修改 webpack 和 Rspack 的配置。
+- 第一个参数为 `bundler-chain` 对象实例，你可以通过这个实例来修改 Rspack 的配置。
 - 第二个参数为一个工具集合，包括`env`、`isProd`、`CHAIN_ID` 等。
 
 :::tip 什么是 BundlerChain
 
-Bundler chain 是 webpack chain 的子集，其中包含一部分 webpack chain API，你可以用它来同时修改 webpack 和 Rspack 的配置。
+Bundler chain 是基于 Rspack 配置 API 实现的链式配置工具，你可以用它来修改 Rspack 的配置。
 
-通过 bundler chain 修改的配置，在 webpack 和 Rspack 构建时均可生效。需要注意的是，bundler chain 只支持修改 webpack 和 Rspack 间无差异部分的配置。如，修改 devtool 配置项(webpack 和 Rspack 的 devtool 属性值类型相同)，或添加一个[Rspack 兼容](https://rspack.rs/zh/guide/compatibility/plugin)的 webpack 插件。
+通过 bundler chain 修改的配置，将在 Rspack 构建时生效。
 
 :::
 
-> `tools.bundlerChain` 的执行时机早于 tools.webpackChain / tools.webpack / tools.rspack，因此会被其他几个配置中的修改所覆盖。
+> `tools.bundlerChain` 的执行时机早于 tools.rspack，因此会被 tools.rspack 中的修改所覆盖。
 
 更多信息可参考 [Rsbuild#tools.bundlerChain](https://rsbuild.rs/zh/config/tools/bundler-chain)。

package/docs/zh/configure/app/tools/css-extract.mdx

@@ -27,7 +27,7 @@ const defaultOptions = {
 };
 ```
 
-通过 `tools.cssExtract` 可以更改 [CssExtractRspackPlugin](https://rspack.rs/zh/plugins/rspack/css-extract-rspack-plugin) 或 [mini-css-extract-plugin](https://github.com/webpack-contrib/mini-css-extract-plugin) 的配置。
+通过 `tools.cssExtract` 可以更改 [CssExtractRspackPlugin](https://rspack.rs/zh/plugins/rspack/css-extract-rspack-plugin) 的配置。
 
 import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
 

package/docs/zh/configure/app/tools/dev-server.mdx

@@ -15,118 +15,12 @@ Modern.js 中并没有直接使用 [webpack-dev-server](https://webpack.js.org/a
 
 ### 选项
 
-#### after
-
-:::warning
-**Deprecated**：该配置已废弃，请使用 [dev.setupMiddlewares](https://modernjs.dev/configure/app/dev/setup-middlewares) 代替。
-:::
-
-- **类型：** `Array`
-- **默认值：** `[]`
-
-添加自定义中间件，在所有开发环境中间件后执行。
-
-```js
-export default {
-  tools: {
-    devServer: {
-      after: [
-        async (req, res, next) => {
-          console.log('after dev middleware');
-          next();
-        },
-      ],
-    },
-  },
-};
-```
-
-`webpack-dev-server` 使用 Express 作为服务端框架。Modern.js 中没有使用任何框架，上述中间件中 `req` 和 `res` 都是 Node 原生对象，因此 `webpack-dev-server` 的 Express 中间件不一定能直接在 Modern.js 中使用。
-
-如果要迁移 `webpack-dev-server` 中使用的 Express 中间件，可以使用以下方式，将 Express app 作为中间件传入：
-
-```js
-import expressMiddleware from 'my-express-middleware';
-import express from 'express';
-
-// 初始化 Express app
-const app = express();
-app.use(expressMiddleware);
-
-export default {
-  tools: {
-    devServer: {
-      after: [app],
-    },
-  },
-};
-```
-
-#### before
-
-:::warning
-**Deprecated**：该配置已废弃，请使用 [dev.setupMiddlewares](https://modernjs.dev/configure/app/dev/setup-middlewares) 代替。
-:::
-
-- **类型：** `Array`
-- **默认值：** `[]`
-
-添加自定义中间件，在所有开发环境中间件前执行。
-
-```js
-export default {
-  tools: {
-    devServer: {
-      before: [
-        async (req, res, next) => {
-          console.log('before dev middleware');
-          next();
-        },
-      ],
-    },
-  },
-};
-```
-
-#### client
+#### compress
 
 :::warning
-**Deprecated**：该配置已废弃，请使用 [dev.client](https://modernjs.dev/configure/app/dev/client) 代替。
+**Deprecated**：该配置已废弃，请使用 [dev.server.compress](/configure/app/dev/server) 代替。
 :::
 
-- **类型：**
-
-```ts
-{
-    /** 指定协议名称 */
-    protocol?: string;
-    /** 事件流路径 */
-    path?: string;
-    /** 指定监听请求的端口号 */
-    port?: string;
-    /** 指定要使用的 host */
-    host?: string;
-}
-```
-
-- **默认值：**
-
-```js
-const defaultConfig = {
-  path: '/webpack-hmr',
-  // By default it is set to the port number of the dev server
-  port: '',
-  // By default it is set to "location.hostname"
-  host: '',
-  // By default it is set to "location.protocol === 'https:' ? 'wss' : 'ws'""
-  protocol: '',
-};
-```
-
-对应 HMR 客户端的配置，通常用于设置 HMR 对应的 WebSocket URL。
-
-#### compress
-
 - **类型：** `boolean`
 - **默认值：** `true`
 
@@ -144,32 +38,12 @@ export default {
 };
 ```
 
-#### devMiddleware
+#### headers
 
 :::warning
-**Deprecated**：该配置已废弃，请使用 [dev.writeToDisk](https://modernjs.dev/configure/app/dev/write-to-disk) 代替。
+**Deprecated**：该配置已废弃，请使用 [dev.server.headers](/configure/app/dev/server) 代替。
 :::
 
-- **类型：**
-
-```js
-{
-  writeToDisk: boolean | ((filename: string) => boolean);
-}
-```
-
-- **默认值：**
-
-```js
-{
-  writeToDisk: (file: string) => !file.includes('.hot-update.'),
-}
-```
-
-devMiddleware 配置项。当前配置是 [webpack-dev-middleware](https://github.com/webpack/webpack-dev-middleware) 配置项的子集.
-
-#### headers
-
 - **类型：** `Record<string, string>`
 - **默认值：** `undefined`
 
@@ -189,6 +63,10 @@ export default {
 
 #### historyApiFallback
 
+:::warning
+**Deprecated**：该配置已废弃，请使用 [dev.server.historyApiFallback](/configure/app/dev/server) 代替。
+:::
+
 - **类型：** `boolean | ConnectHistoryApiFallbackOptions`
 - **默认值：** `false`
 
@@ -206,128 +84,12 @@ export default {
 
 更多选项和详细信息可参考 [connect-history-api-fallback](https://github.com/bripkens/connect-history-api-fallback) 文档。
 
-#### hot
-
-:::warning
-**Deprecated**：该配置已废弃，请使用 [dev.hmr](https://modernjs.dev/configure/app/dev/hmr) 代替。
-:::
-
-- **类型：** `boolean`
-- **默认值：** `true`
-
-是否开启 [Hot Module Replacement](https://webpack.js.org/concepts/hot-module-replacement/) 热更新能力。
-
-#### https
-
-:::warning
-**Deprecated**：该配置已废弃，请使用 [dev.https](https://modernjs.dev/configure/app/dev/https) 代替。
-:::
-
-- **类型：** `boolean | { key: string; cert: string }`
-- **默认值：** `false`
-
-默认情况下，DevServer 会启用 HTTP 服务器。通过设置 `devServer.https` 为 `true` 将开启对 HTTPS 的支持，同时会禁用 HTTP 服务器。
-
-你也可以手动传入 HTTPS 服务器所需要的证书和对应的私钥：
-
-```js
-export default {
-  tools: {
-    devServer: {
-      https: {
-        key: fs.readFileSync('certificates/private.pem'),
-        cert: fs.readFileSync('certificates/public.pem'),
-      },
-    },
-  },
-};
-```
-
-#### liveReload
-
-:::warning
-**Deprecated**：该配置已废弃，请使用 [dev.liveReload](https://modernjs.dev/configure/app/dev/live-reload) 代替。
-:::
-
-- **类型：** `boolean`
-- **默认值：** `true`
-
-默认情况下，当监听到文件变化时，DevServer 将会刷新页面（为使 liveReload 能够生效，`devServer.hot` 配置项应当禁用）。通过设置 `devServer.liveReload` 为 `false` 可以关闭该行为。
-
-#### setupMiddlewares
+#### proxy
 
 :::warning
-**Deprecated**：该配置已废弃，请使用 [dev.setupMiddlewares](https://modernjs.dev/configure/app/dev/setup-middlewares) 代替。
+**Deprecated**：该配置已废弃，请使用 [dev.server.proxy](/configure/app/dev/server) 代替。
 :::
 
-- **类型：**
-
-```js
-Array<
-  (
-    middlewares: {
-      unshift: (...handlers: RequestHandler[]) => void;
-      push: (...handlers: RequestHandler[]) => void;
-    },
-    server: {
-      sockWrite: (
-        type: string,
-        data?: string | boolean | Record<string, any>,
-      ) => void;
-    },
-  ) => void
->;
-```
-
-- **默认值：** `undefined`
-
-提供执行自定义函数和应用自定义中间件的能力。
-
-几种不同中间件之间的执行顺序是: `devServer.before` => `unshift` => 内置中间件 => `push` => `devServer.after`。
-
-```js
-export default {
-  tools: {
-    devServer: {
-      setupMiddlewares: [
-        (middlewares, server) => {
-          middlewares.unshift((req, res, next) => {
-            next();
-          });
-
-          middlewares.push((req, res, next) => {
-            next();
-          });
-        },
-      ],
-    },
-  },
-};
-```
-
-一些特殊场景需求可能需要使用服务器 API：
-
-- sockWrite。允许向 hmr 客户端传递一些消息，hmr 客户端将根据接收到的消息类型进行不同的处理。如果你发送一个 "content-changed " 的消息，页面将会重新加载。
-
-```js
-export default {
-  tools: {
-    devServer: {
-      setupMiddlewares: [
-        (middlewares, server) => {
-          // 添加自定义 watcher 并在文件更新时触发页面刷新
-          watcher.on('change', changed => {
-            server.sockWrite('content-changed');
-          });
-        },
-      ],
-    },
-  },
-};
-```
-
-#### proxy
-
 - **类型：** `Record<string, string> | Record<string, ProxyDetail>`
 - **默认值：** `undefined`
 
@@ -436,6 +198,10 @@ export default {
 
 #### watch
 
+:::warning
+**Deprecated**：该配置已废弃，请使用 [dev.server.watch](/configure/app/dev/server) 代替。
+:::
+
 - **类型：** `boolean`
 - **默认值：** `true`
 

package/docs/zh/configure/app/tools/html-plugin.mdx

@@ -17,7 +17,8 @@ const defaultOptions = {
   filename, // 基于 `output.distPath` 和 `entryName` 生成
   templateParameters, // 对应 `html.templateParameters` 配置
   chunks: [entryName],
-  minify: { // 基于 `output.minify` 和 `output.disableMinimize` 生成
+  minify: {
+    // 基于 `output.minify` 生成
     removeComments: false,
     useShortDoctype: true,
     keepClosingSlash: true,
@@ -37,7 +38,7 @@ const defaultOptions = {
 SSR 应用请勿启用 `minify.removeComments` 配置项，否则会导致 SSR 渲染失败。
 :::
 
-通过 `tools.htmlPlugin` 可以修改 [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin) 或 [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) 的配置项。
+通过 `tools.htmlPlugin` 可以修改 [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin) 的配置项。
 
 import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
 

package/docs/zh/configure/app/tools/lightningcss-loader.mdx

@@ -6,7 +6,6 @@ title: lightningcssLoader
 
 - **类型：** `Rspack.LightningcssLoaderOptions | Function | boolean`
 - **默认值：** `false`
-- **打包工具：** `仅支持 rspack`
 
 通过 `tools.lightningcssLoader` 可以设置 [builtin:lightningcss-loader](https://rspack.rs/guide/features/builtin-lightningcss-loader) 的选项。
 

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

@@ -24,7 +24,7 @@ import SWC from '@site-docs/components/swc.mdx';
 ```ts
 import { defineConfig } from '@modern-js/app-tools';
 
-export default defineConfig<'rspack'>({
+export default defineConfig({
   tools: {
     swc: {
       jsc: {
@@ -67,45 +67,3 @@ export default {
 如果你遇到了以上问题，通常可行的解决方法是将 Modern.js 和 SWC 插件都升级到最新版本。
 
 详情可参考 [Rsbuild - SWC 插件版本](https://rsbuild.rs/zh/guide/basic/configure-swc#swc-%E6%8F%92%E4%BB%B6%E7%89%88%E6%9C%AC)。
-
-## 在 Webpack 模式下使用
-
-import EnableSWC from '@site-docs/components/enableSwc.mdx';
-
-<EnableSWC />
-
-### 配置项
-
-你可以通过 `tools.swc` 配置项来设置 SWC 编译行为。
-
-```js title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-
-export default defineConfig({
-  tools: {
-    swc: {
-      jsMinify: {
-        compress: {},
-        mangle: true,
-      },
-    },
-  },
-});
-```
-
-当然也可以使用函数进行更灵活的配置，或者修改某些默认配置。
-
-```js title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-
-export default defineConfig({
-  tools: {
-    swc(config, { setConfig }) {
-      // 用于 mobx 中 decorator 编译
-      setConfig(config, 'jsc.transform.useDefineForClassFields', true);
-    },
-  },
-});
-```
-
-完整配置项请参考 [SWC 插件配置](/plugin/official/cli-plugins/plugin-swc.html#配置)。

package/docs/zh/configure/app/usage.mdx

@@ -43,15 +43,6 @@ export default defineConfig({
 });
 ```
 
-当你使用 Rspack 作为打包工具时，由于 webpack 和 Rspack 的配置类型存在一些差异，需要为 `defineConfig` 指定 `<'rspack'>` 泛型：
-
-```diff title=modern.config.ts
-- export default defineConfig({
-+ export default defineConfig<'rspack'>({
-  // ...
-});
-```
-
 #### modern.config.js
 
 如果你在开发一个非 TypeScript 项目，可以使用 `.js` 格式的配置文件：
@@ -95,9 +86,9 @@ export default defineConfig(({ env, command }) => ({
 该函数接受以下入参：
 
 - `env`：对应 `process.env.NODE_ENV` 的值。
-  - 当运行 `modern dev` 或 `modern start` 时，`env` 的值为 `development`。
+  - 当运行 `modern dev` 时，`env` 的值为 `development`。
   - 当运行 `modern build` 或 `modern serve` 时，`env` 的值为 `production`。
-- `command`：对应当前运行的命令，如 `dev`、`start`、`build`、`serve`。
+- `command`：对应当前运行的命令，如 `dev`、`build`、`serve`。
 
 #### 导出异步函数
 
@@ -159,7 +150,6 @@ $ modern build -c modern.prod.config.js
 #### 注意事项
 
 - 不建议同时使用 `package.json` 和 `modern.config.js` 进行配置。如果同时使用了两者并出现配置冲突，Modern.js 会在命令行进行提示错误。
-- `@modern-js/runtime` 导出了同名的 [defineConfig](/apis/app/runtime/app/define-config) API，请注意区分。
 
 ### 本地调试配置
 
@@ -197,11 +187,11 @@ export default defineConfig({
 
 在使用 `modern.config.local.ts` 时，请注意以下事项：
 
-- `modern.config.local.ts` 文件仅会在执行 `modern dev` 或 `modern start` 命令时被加载，当执行 `modern build` 时不会被加载。
+- `modern.config.local.ts` 文件仅会在执行 `modern dev` 命令时被加载，当执行 `modern build` 时不会被加载。
 - `modern.config.local.ts` 文件的优先级不仅高于 `modern.config.ts`，也高于 `package.json` 中的 `modernConfig` 字段。
 - 由于 `modern.config.local.ts` 仅在本地调试时使用，因此不建议将其提交到代码仓库中，请确保项目的 `.gitignore` 文件中包含 `modern.config.local.ts` 等文件。
 
-```bash title=".gitingore"
+```bash title=".gitignore"
 modern.config.local.*
 ```
 
@@ -257,18 +247,6 @@ Modern.js 导出了 `AppUserConfig` 类型，对应 Modern.js 配置对象的类
 import type { AppUserConfig } from '@modern-js/app-tools';
 
 const config: AppUserConfig = {
-  tools: {
-    webpack: {},
-  },
-};
-```
-
-当你使用 Rspack 作为打包工具时，由于 webpack 和 Rspack 的配置类型存在一些差异，需要为 `AppUserConfig` 指定 `<'rspack'>` 泛型：
-
-```ts title="modern.config.ts"
-import type { AppUserConfig } from '@modern-js/app-tools';
-
-const config: AppUserConfig<'rspack'> = {
   tools: {
     rspack: {},
   },
@@ -284,11 +262,11 @@ const config: AppUserConfig<'rspack'> = {
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';
-import { statePlugin } from '@modern-js/plugin-state';
+import { xxPlugin } from '@modern-js/plugin-xx';
 
 export default defineConfig({
   plugins: [
-    statePlugin({
+    xxPlugin({
       /** 在此处添加参数 */
     }),
   ],

package/docs/zh/guides/_meta.json

@@ -29,5 +29,9 @@
     "name": "troubleshooting",
     "label": "troubleshooting"
   },
-  "deprecated"
+  {
+    "type": "dir",
+    "name": "upgrade",
+    "label": "从 Modern.js 2.0 升级"
+  }
 ]

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

@@ -1,5 +1,4 @@
 [
-  "rspack-start",
   {
     "type": "dir",
     "name": "bff",
@@ -23,5 +22,11 @@
     "label": "server-monitor",
     "collapsed": true
   },
+  {
+    "type": "dir",
+    "name": "international",
+    "label": "国际化",
+    "collapsed": true
+  },
   "web-server"
 ]

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

@@ -1 +1,9 @@
-["function", "frameworks", "extend-server", "sdk", "upload", "cross-project"]
+[
+  "function",
+  "frameworks",
+  "operators",
+  "extend-server",
+  "sdk",
+  "upload",
+  "cross-project"
+]