@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

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

@@ -0,0 +1,14 @@
+---
+title: exclude
+---
+
+# source.exclude
+
+- **类型：** [RuleSetCondition[]](https://rspack.rs/zh/config/module#condition)
+- **默认值：** `[]`
+
+指定不需要编译的 JavaScript/TypeScript 文件。用法与 Rspack 中的 [Rule.exclude](https://rspack.rs/zh/config/module#ruleexclude) 一致，支持传入字符串或正则表达式来匹配模块的路径。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="source.exclude" />

package/docs/zh/configure/app/source/global-vars.mdx

@@ -0,0 +1,109 @@
+---
+title: globalVars
+---
+
+# source.globalVars
+
+- **类型：** `Record<string, JSONValue> | Function`
+- **默认值：**
+
+```ts
+// Modern.js 默认会添加环境变量 `process.env.NODE_ENV`，因此你不需要手动添加它。
+const defaultGlobalVars = {
+  'process.env.NODE_ENV': process.env.NODE_ENV,
+};
+```
+
+用于在构建时将类似 `process.env.FOO` 的全局变量表达式替换为指定的值，比如：
+
+```js
+console.log(process.env.NODE_ENV);
+
+// ⬇️ Turn into being...
+console.log('development');
+```
+
+### 示例
+
+在下方示例中，会在代码中注入 `ENABLE_VCONSOLE` 和 `APP_CONTEXT` 两个环境变量：
+
+```js
+export default {
+  source: {
+    globalVars: {
+      ENABLE_VCONSOLE: true,
+      APP_CONTEXT: { answer: 42 },
+    },
+  },
+};
+```
+
+你可以在代码中直接使用它们：
+
+```js
+if (ENABLE_VCONSOLE) {
+  // do something
+}
+
+console.log(APP_CONTEXT);
+```
+
+### 函数用法
+
+- **类型：**
+
+```ts
+type GlobalVarsFn = (
+  obj: Record<string, JSONValue>,
+  utils: { env: NodeEnv; target: BuilderTarget },
+) => Record<string, JSONValue> | void;
+```
+
+你可以将 `source.globalVars` 设置为一个函数，从而动态设置一些环境变量的值。
+
+比如，根据当前的构建产物类型进行动态设置：
+
+```js
+export default {
+  source: {
+    globalVars(obj, { target }) {
+      obj['MY_TARGET'] = target === 'node' ? 'server' : 'client';
+    },
+  },
+};
+```
+
+### 与 define 的区别
+
+`source.globalVars` 是 `source.define` 的一个语法糖，它们之间唯一的区别是，`source.globalVars` 会自动将传入的值进行 JSON 序列化处理，这使得设置全局变量的值更加方便。注意 `globalVars` 的每个值都需要是可以被 JSON 序列化的值。
+
+```js
+export default {
+  source: {
+    globalVars: {
+      'process.env.BUILD_VERSION': '0.0.1',
+      'import.meta.foo': { bar: 42 },
+      'import.meta.baz': false,
+    },
+    define: {
+      'process.env.BUILD_VERSION': JSON.stringify('0.0.1'),
+      'import.meta': {
+        foo: JSON.stringify({ bar: 42 }),
+        baz: JSON.stringify(false),
+      },
+    },
+  },
+};
+```
+
+### 注意事项
+
+`source.globalVars` 是通过字符串替换的形式来注入环境变量的，因此它无法对「解构赋值」等动态写法生效。
+
+在使用解构赋值时，Modern.js 将无法判断变量 `NODE_ENV` 是否与要替换的表达式 `process.env.NODE_ENV` 存在关联，因此以下使用方式是无效的：
+
+```js
+const { NODE_ENV } = process.env;
+console.log(NODE_ENV);
+// ❌ Won't get a string.
+```

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

@@ -0,0 +1,40 @@
+---
+title: include
+---
+
+# source.include
+
+- **类型：** [RuleSetCondition[]](https://rspack.rs/zh/config/module#condition)
+- **默认值：**
+
+```ts
+const defaultInclude = [
+  [{ not: /[\\/]node_modules[\\/]/ }, /\.(?:ts|tsx|jsx|mts|cts)$/],
+];
+```
+
+`source.include` 用于指定额外需要编译的 JavaScript 文件。默认情况下，会编译以下文件：
+
+- 任意目录下的 TypeScript 和 JSX 文件，匹配的文件后缀为 `.ts`、`.tsx`、`.jsx`、`.mts`、`.cts`。
+- 非 `node_modules` 目录下的 JavaScript 文件，匹配的文件后缀为 `.js`、`.mjs`、`.cjs`。
+
+:::tip
+在 Rsbuild 1.4 版本前，`source.include` 的默认值为：
+
+```ts
+const defaultInclude = [
+  [
+    {
+      and: [APP_ROOT, { not: /[\\/]node_modules[\\/]/ }],
+    },
+    /\.(?:ts|tsx|jsx|mts|cts)$/,
+  ],
+];
+```
+
+与新版本的差异是，非当前项目目录的 `.js`、`.mjs`、`.cjs` 文件不会被编译。
+:::
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="source.include" />

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

@@ -0,0 +1,28 @@
+---
+title: mainEntryName
+---
+
+# source.mainEntryName
+
+- **类型：** `string`
+- **默认值：** `'index'`
+
+该选项用于配置 Modern.js 的主入口名称。
+
+默认情况下，Modern.js 的默认主入口名称为 `index`，当使用单入口或者入口名称和 `package.json` 中 name 字段一致时，会将对应入口作为主入口，通过该配置可以修改主入口的名称。
+
+比如将主入口名称改为 main：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    mainEntryName: 'main',
+  },
+});
+```
+
+构建之后，对应 html 产物路径将会变为 `dist/html/index/index.html`。
+
+:::info
+当修改主入口名称后，其他 `**ByEntries` 的配置也需要对应调整使用修改后的入口名称。
+:::

package/docs/zh/configure/app/source/pre-entry.mdx

@@ -0,0 +1,14 @@
+---
+title: preEntry
+---
+
+# source.preEntry
+
+- **类型：** `string | string[]`
+- **默认值：** `[]`
+
+在每个页面的入口文件前添加一段代码，这段代码会早于页面的代码执行，因此可以用于执行一些全局的代码逻辑，比如注入 polyfill、设置全局样式等。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="source.preEntry" />

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

@@ -0,0 +1,31 @@
+---
+title: transformImport
+---
+
+# source.transformImport
+
+转换 import 的路径，可以用于模块化引用三方包的子路径，能力类似于 [babel-plugin-import](https://www.npmjs.com/package/babel-plugin-import)。
+
+- **类型:**
+
+```ts
+type TransformImport =
+  | false
+  | Array<{
+      libraryName: string;
+      libraryDirectory?: string;
+      style?: string | boolean;
+      styleLibraryDirectory?: string;
+      camelToDashComponentName?: boolean;
+      transformToDefaultImport?: boolean;
+      customName?: string;
+      customStyleName?: string;
+    }>
+  | Function;
+```
+
+- **默认值：** `undefined`
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="source.transformImport" />

package/docs/zh/configure/app/split-chunks.mdx

@@ -0,0 +1,17 @@
+# splitChunks
+
+- **类型：**
+
+```ts
+type SplitChunksConfig =
+  | (Rspack.OptimizationSplitChunksOptions & {
+      preset?: SplitChunksPreset;
+    })
+  | false;
+```
+
+`splitChunks` 用于配置 Rsbuild 的 chunk 拆分策略。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="splitChunks" />

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

@@ -0,0 +1,48 @@
+---
+title: autoprefixer
+---
+
+# tools.autoprefixer
+
+- **类型：** `Object | Function`
+- **默认值：**
+
+```js
+{
+  flexbox: 'no-2009',
+  // browserslist 取决于项目中的 browserslist 配置
+  // 以及 `output.overrideBrowserslist`(优先级更高) 配置
+  overrideBrowserslist: browserslist,
+}
+```
+
+通过 `tools.autoprefixer` 可以修改 [autoprefixer](https://github.com/postcss/autoprefixer) 的配置。
+
+### Object 类型
+
+当 `tools.autoprefixer` 的值为 `Object` 类型时，会与默认配置通过 Object.assign 合并。比如：
+
+```js
+export default {
+  tools: {
+    autoprefixer: {
+      flexbox: 'no-2009',
+    },
+  },
+};
+```
+
+### Function 类型
+
+当 `tools.autoprefixer` 为 Function 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果。比如：
+
+```js
+export default {
+  tools: {
+    autoprefixer(config) {
+      // 修改 flexbox 的配置
+      config.flexbox = 'no-2009';
+    },
+  },
+};
+```

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

@@ -0,0 +1,33 @@
+---
+title: bundlerChain
+---
+
+# tools.bundlerChain
+
+- **类型：**
+
+```ts
+type BundlerChainFn = (
+  chain: RspackChain,
+  utils: ModifyBundlerChainUtils,
+) => Promise<void> | void;
+```
+
+- **默认值：** `undefined`
+
+你可以通过 `tools.bundlerChain` 来修改默认的 Rspack 配置，它的值为 `Function` 类型，接收两个参数：
+
+- 第一个参数为 `bundler-chain` 对象实例，你可以通过这个实例来修改 Rspack 的配置。
+- 第二个参数为一个工具集合，包括`env`、`isProd`、`CHAIN_ID` 等。
+
+:::tip 什么是 BundlerChain
+
+Bundler chain 是基于 Rspack 配置 API 实现的链式配置工具，你可以用它来修改 Rspack 的配置。
+
+通过 bundler chain 修改的配置，将在 Rspack 构建时生效。
+
+:::
+
+> `tools.bundlerChain` 的执行时机早于 tools.rspack，因此会被 tools.rspack 中的修改所覆盖。
+
+更多信息可参考 [Rsbuild#tools.bundlerChain](https://v2.rsbuild.rs/zh/config/tools/bundler-chain)。

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

@@ -0,0 +1,34 @@
+---
+title: cssExtract
+---
+
+# tools.cssExtract
+
+- **类型：**
+
+```ts
+type CSSExtractOptions = {
+  pluginOptions?: Rspack.CssExtractRspackPluginOptions;
+  loaderOptions?: Rspack.CssExtractRspackLoaderOptions;
+};
+```
+
+- **默认值：**
+
+```js
+const defaultOptions = {
+  pluginOptions: {
+    ignoreOrder: true,
+    // 默认值由 Rsbuild 的 output.distPath 和 output.filename 选项决定
+    filename: 'static/css/[name].css',
+    chunkFilename: 'static/css/async/[name].css',
+  },
+  loaderOptions: {},
+};
+```
+
+通过 `tools.cssExtract` 可以更改 [CssExtractRspackPlugin](https://rspack.rs/zh/plugins/rspack/css-extract-rspack-plugin) 的配置。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="tools.cssExtract" />

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

@@ -0,0 +1,21 @@
+---
+title: cssLoader
+---
+
+# tools.cssLoader
+
+- **类型：** `Object | Function`
+- **默认值：**
+
+```js
+const defaultOptions = {
+  modules: rsbuildConfig.output.cssModules,
+  sourceMap: rsbuildConfig.output.sourceMap.css,
+};
+```
+
+修改 [css-loader](https://github.com/webpack-contrib/css-loader) 的配置项。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="tools.cssLoader" />

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

@@ -0,0 +1,117 @@
+---
+title: devServer
+---
+
+# tools.devServer
+
+- **类型：** `Object`
+- **默认值：** `{}`
+
+通过 `tools.devServer` 可以修改开发环境服务器的配置。
+
+### 选项
+
+#### compress
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 [dev.server.compress](/configure/app/dev/server) 代替。
+:::
+
+- **类型：** `boolean`
+- **默认值：** `true`
+
+是否对静态资源启用 gzip 压缩。
+
+如果你需要禁用 gzip 压缩，可以将 `compress` 设置为 `false`：
+
+```ts
+export default {
+  tools: {
+    devServer: {
+      compress: false,
+    },
+  },
+};
+```
+
+#### headers
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 [dev.server.headers](/configure/app/dev/server) 代替。
+:::
+
+- **类型：** `Record<string, string>`
+- **默认值：** `undefined`
+
+设置自定义响应头。
+
+```js
+export default {
+  tools: {
+    devServer: {
+      headers: {
+        'X-Custom-Foo': 'bar',
+      },
+    },
+  },
+};
+```
+
+#### historyApiFallback
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 [dev.server.historyApiFallback](/configure/app/dev/server) 代替。
+:::
+
+- **类型：** `boolean | ConnectHistoryApiFallbackOptions`
+- **默认值：** `false`
+
+在需要对一些 404 响应或其他请求提供替代页面的场景，可通过 `devServer.historyApiFallback` 进行设置：
+
+```js
+export default {
+  tools: {
+    devServer: {
+      historyApiFallback: true,
+    },
+  },
+};
+```
+
+更多选项和详细信息可参考 [connect-history-api-fallback](https://github.com/bripkens/connect-history-api-fallback) 文档。
+
+#### proxy
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 [dev.server.proxy](/configure/app/dev/server) 代替。
+:::
+
+- **类型：** `ProxyOptions[] | Record<string, string | ProxyOptions>`
+- **默认值：** `undefined`
+
+为开发服务器配置代理规则，把请求转发到指定服务。
+
+```js
+export default {
+  tools: {
+    devServer: {
+      proxy: {
+        // http://localhost:8080/api -> https://example.com/api
+        // http://localhost:8080/api/foo -> https://example.com/api/foo
+        '/api': 'https://example.com',
+      },
+    },
+  },
+};
+```
+
+#### watch
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 [dev.server.watch](/configure/app/dev/server) 代替。
+:::
+
+- **类型：** `boolean`
+- **默认值：** `true`
+
+是否监听 `mock/`、`server/`、`api/` 等目录的文件变化。

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

@@ -0,0 +1,45 @@
+---
+title: htmlPlugin
+---
+
+# tools.htmlPlugin
+
+- **类型：** `boolean | Object | Function`
+- **默认值：**
+
+```js
+const defaultOptions = {
+  meta, // 对应 `html.meta` 配置
+  title, // 对应 `html.title` 配置
+  inject, // 对应 `html.inject` 配置
+  favicon, // 对应 `html.favicon` 配置
+  template, // 对应 `html.template` 配置
+  filename, // 基于 `output.distPath` 和 `entryName` 生成
+  templateParameters, // 对应 `html.templateParameters` 配置
+  chunks: [entryName],
+  minify: {
+    // 基于 `output.minify` 生成
+    removeComments: false,
+    useShortDoctype: true,
+    keepClosingSlash: true,
+    collapseWhitespace: true,
+    removeRedundantAttributes: true,
+    removeScriptTypeAttributes: true,
+    removeStyleLinkTypeAttributes: true,
+    removeEmptyAttributes: true,
+    minifyJS, // 基于 `output.charset`、`output.legalComments` 和 `performance.removeConsole` 生成
+    minifyCSS: true,
+    minifyURLs: true,
+  },
+};
+```
+
+:::warning
+SSR 应用请勿启用 `minify.removeComments` 配置项，否则会导致 SSR 渲染失败。
+:::
+
+通过 `tools.htmlPlugin` 可以修改 [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin) 的配置项。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="tools.htmlPlugin" />

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

@@ -0,0 +1,86 @@
+---
+title: less
+---
+
+# tools.less
+
+- **类型：** `Object | Function`
+- **默认值：**
+
+```js
+const defaultOptions = {
+  lessOptions: {
+    javascriptEnabled: true,
+  },
+  // 默认在开发环境下启用 CSS 的 Source Map
+  sourceMap: isDev,
+};
+```
+
+你可以通过 `tools.less` 修改 [less-loader](https://github.com/webpack-contrib/less-loader) 的配置。
+
+### Object 类型
+
+当 `tools.less` 的值为 `Object` 类型时，会与默认配置通过 Object.assign 进行浅层合并，值得注意的是，`lessOptions` 会通过 deepMerge 进行深层合并。
+
+```js
+export default {
+  tools: {
+    less: {
+      lessOptions: {
+        javascriptEnabled: false,
+      },
+    },
+  },
+};
+```
+
+### Function 类型
+
+当 `tools.less` 为 Function 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果，第二个参数提供了一些可以直接调用的工具函数：
+
+```js
+export default {
+  tools: {
+    less(config) {
+      // 修改 lessOptions 配置
+      config.lessOptions = {
+        javascriptEnabled: false,
+      };
+    },
+  },
+};
+```
+
+### 修改 Less 版本
+
+在某些场景下，如果你需要使用特定的 Less 版本，而不是使用 Modern.js 内置的 Less v4，可以在项目中安装需要使用的 Less 版本，并通过 `less-loader` 的 `implementation` 选项设置。
+
+```js
+export default {
+  tools: {
+    less: {
+      implementation: require('less'),
+    },
+  },
+};
+```
+
+### 工具函数
+
+#### addExcludes
+
+- **类型：** `(excludes: RegExp | RegExp[]) => void`
+
+用来指定 `less-loader` 不编译哪些文件，你可以传入一个或多个正则表达式来匹配 less 文件的路径。例如：
+
+```js
+export default {
+  tools: {
+    less(config, { addExcludes }) {
+      addExcludes(/node_modules/);
+    },
+  },
+};
+```
+

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

@@ -0,0 +1,39 @@
+---
+title: lightningcssLoader
+---
+
+# tools.lightningcssLoader
+
+- **类型：** `Rspack.LightningcssLoaderOptions | Function | boolean`
+- **默认值：** `false`
+
+通过 `tools.lightningcssLoader` 可以设置 [builtin:lightningcss-loader](https://rspack.rs/guide/features/builtin-lightningcss-loader) 的选项。
+
+## 开启 loader
+
+将 `tools.lightningcssLoader` 设置为 `true`，可以开启 Rsbuild 内置的 `lightningcss-loader`：
+
+```js
+export default {
+  tools: {
+    lightningcssLoader: true,
+  },
+};
+```
+
+此时，默认生效的配置如下：
+
+```js
+const defaultOptions = {
+  // use current browserslist config
+  targets: browserslist,
+  // minify is enabled when output.injectStyles is true and in production mode
+  minify: config.mode === 'production' && config.output.injectStyles,
+};
+```
+
+需要注意的是，开启 `lightningcss-loader` 时，将会默认关闭 `postcss-loader`。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="tools.lightningcssLoader" />