@modern-js/main-doc 0.0.0-nightly-20240912170717 → 0.0.0-nightly-20240914170654

package/docs/zh/configure/app/source/entries-dir.mdx

@@ -5,7 +5,7 @@ title: entriesDir
 # source.entriesDir
 
 - **类型：** `string`
-- **默认值：** `./src`
+- **默认值：** `'./src'`
 
 Modern.js 默认会扫描 `src` 目录来识别页面入口，你可以通过该选项自定义页面入口的识别目录。
 

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

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

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

@@ -4,6 +4,106 @@ title: globalVars
 
 # source.globalVars
 
-import Main from '@modern-js/builder-doc/docs/zh/config/source/globalVars.md';
+- **类型：** `Record<string, JSONValue> | Function`
+- **默认值：**
 
-<Main />
+```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

@@ -1,9 +1,26 @@
 ---
 title: include
+configName: source.include
 ---
 
 # source.include
 
-import Main from '@modern-js/builder-doc/docs/zh/config/source/include.md';
+- **类型：** [RuleSetCondition[]](https://rspack.dev/zh/config/module#condition)
+- **默认值：**
 
-<Main />
+```ts
+const defaultInclude = [
+  [
+    /node_modules\/react-router/,
+    /node_modules\/react-router-dom/,
+    /node_modules\/@remix-run\/router/,
+    '/node_modules/.modern-js',
+  ],
+];
+```
+
+`source.include` 用于指定额外需要编译的 JavaScript 文件。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

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

@@ -5,7 +5,7 @@ title: mainEntryName
 # source.mainEntryName
 
 - **类型：** `string`
-- **默认值：** `main`
+- **默认值：** `'main'`
 
 该选项用于配置 Modern.js 的主入口名称。
 

package/docs/zh/configure/app/source/module-scopes.mdx

@@ -4,6 +4,66 @@ title: moduleScopes
 
 # source.moduleScopes
 
-import Main from '@modern-js/builder-doc/docs/zh/config/source/moduleScopes.md';
+- **类型：** `Array<string | Regexp> | Function`
+- **默认值：** `undefined`
+- **打包工具：** `仅支持 webpack`
 
-<Main />
+限制源代码的引用路径。配置该选项后，所有源文件只能从约定的目录下引用代码，从其他目录引用代码会产生对应的报错提示。
+
+### 示例
+
+首先我们配置 `moduleScopes` 仅包含 `src` 目录：
+
+```js
+export default {
+  source: {
+    moduleScopes: ['./src'],
+  },
+};
+```
+
+然后在 `src/App.tsx` 中导入 `src` 目录外部的 `utils/a` 模块:
+
+```js
+import a from '../utils/a';
+```
+
+在编译时，会提示引用路径错误:
+
+![scopes-error](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/module-scopes-error.png)
+
+通过该选项配置 `utils` 目录，再进行编译，则不会出现错误提示。
+
+```js
+export default {
+  source: {
+    moduleScopes: ['./src', './utils'],
+  },
+};
+```
+
+### Array 类型
+
+当 `moduleScopes` 的值为 `Array` 类型时，可以直接设置若干个代码路径，比如添加以下配置：
+
+```js
+export default {
+  source: {
+    moduleScopes: ['./src', './shared', './utils'],
+  },
+};
+```
+
+### Function 类型
+
+`moduleScopes` 也支持通过函数的形式来进行修改，避免覆盖默认值：
+
+```js
+export default {
+  source: {
+    moduleScopes: scopes => {
+      scopes.push('./shared');
+    },
+  },
+};
+```

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

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

package/docs/zh/configure/app/source/resolve-extension-prefix.mdx

@@ -4,6 +4,54 @@ title: resolveExtensionPrefix
 
 # source.resolveExtensionPrefix
 
-import Main from '@modern-js/builder-doc/docs/zh/config/source/resolveExtensionPrefix.md';
+- **类型：** `string | Record<BuilderTarget, string>`
+- **默认值：** `undefined`
 
-<Main />
+用于为 [resolve.extensions](https://webpack.js.org/configuration/resolve/#resolveextensions) 添加统一的前缀。
+
+如果多个文件拥有相同的名称，但具有不同的文件后缀，Modern.js 会根据 extensions 数组的顺序进行识别，解析数组中第一个被识别的文件，并跳过其余文件。
+
+### 示例
+
+下面是配置 `.web` 前缀的例子。
+
+```js
+export default {
+  source: {
+    resolveExtensionPrefix: '.web',
+  },
+};
+```
+
+配置完成后，extensions 数组会发生以下变化：
+
+```js
+// 配置前
+const extensions = ['.js', '.ts', ...];
+
+// 配置后
+const extensions = ['.web.js', '.js', '.web.ts' , '.ts', ...];
+```
+
+在代码中 `import './foo'` 时，会优先识别 `foo.web.js` 文件，再识别 `foo.js` 文件。
+
+#### 根据产物类型设置
+
+当你同时构建多种类型的产物时，你可以为不同的产物类型设置不同的 extension 前缀。此时，你需要把 `resolveExtensionPrefix` 设置为一个对象，对象的 key 为对应的产物类型。
+
+比如为 `web` 和 `node` 设置不同的 extension 前缀：
+
+```js
+export default {
+  output: {
+    source: {
+      resolveExtensionPrefix: {
+        web: '.web',
+        node: '.node',
+      },
+    },
+  },
+};
+```
+
+在代码中 `import './foo'` 时，对于 node 产物，会优先识别 `foo.node.js` 文件，而对于 web 产物，则会优先识别 `foo.web.js` 文件。

package/docs/zh/configure/app/source/resolve-main-fields.mdx

@@ -4,6 +4,43 @@ title: resolveMainFields
 
 # source.resolveMainFields
 
-import Main from '@modern-js/builder-doc/docs/zh/config/source/resolveMainFields.md';
+- **类型：**
 
-<Main />
+```ts
+type Fields = (string | string[])[];
+
+type ResolveMainFields = Fields | Record<BuilderTarget, Fields>;
+```
+
+- **默认值：** `undefined`
+
+该配置项将决定你使用 `package.json` 哪个字段导入 `npm` 模块。对应 webpack 的 [resolve.mainFields](https://webpack.js.org/configuration/resolve/#resolvemainfields) 配置。
+
+### 示例
+
+```js
+export default {
+  source: {
+    resolveMainFields: ['main', 'browser', 'exports'],
+  },
+};
+```
+
+#### 根据产物类型设置
+
+当你同时构建多种类型的产物时，你可以为不同的产物类型设置不同的 mainFields。此时，你需要把 `resolveMainFields` 设置为一个对象，对象的 key 为对应的产物类型。
+
+比如为 `web` 和 `node` 设置不同的 mainFields：
+
+```js
+export default {
+  output: {
+    source: {
+      resolveMainFields: {
+        web: ['main', 'browser', 'exports'],
+        node: ['main', 'node', 'exports'],
+      },
+    },
+  },
+};
+```

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

@@ -1,9 +1,63 @@
 ---
 title: transformImport
+configName: source.transformImport
 ---
 
 # source.transformImport
 
-import Main from '@modern-js/builder-doc/docs/zh/config/source/transformImport.md';
+转换 import 的路径，可以用于模块化引用三方包的子路径，能力类似于 [babel-plugin-import](https://www.npmjs.com/package/babel-plugin-import)。
 
-<Main />
+- **类型:**
+
+```ts
+type TransformImport =
+  | Array<{
+      libraryName: string;
+      libraryDirectory?: string;
+      style?: string | boolean;
+      styleLibraryDirectory?: string;
+      camelToDashComponentName?: boolean;
+      transformToDefaultImport?: boolean;
+      customName?: string;
+      customStyleName?: string;
+    }>
+  | Function;
+```
+
+- **默认值:**
+
+当项目中安装了 [Ant Design 组件库](https://www.npmjs.com/package/antd) &lt;= 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` 相关的配置时，优先级会高于上述默认配置。
+:::
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

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

@@ -4,6 +4,45 @@ title: autoprefixer
 
 # tools.autoprefixer
 
-import Main from '@modern-js/builder-doc/docs/zh/config/tools/autoprefixer.md';
+- **类型：** `Object | Function`
+- **默认值：**
 
-<Main />
+```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';
+    },
+  },
+};
+```