docs: improve resolve.mainFields (#8703)

* docs: improve `resolve.mainFields` * docs: fix order * docs: fix order * docs: fix
web-infra-dev · Dec 13, 2024 · 4f8966e · 4f8966e
1 parent b1807de
commit 4f8966e
Show file tree

Hide file tree

Showing 2 changed files with 131 additions and 75 deletions.
diff --git a/website/docs/en/config/resolve.mdx b/website/docs/en/config/resolve.mdx
@@ -73,6 +73,27 @@ module.exports = {
 };
 ```
 
+## resolve.exportsFields
+
+- **Type:** `string[]`
+- **Default:** `["exports"]`
+
+Customize the `exports` field in package.json. e.g.
+
+```json title="lib/package.json"
+{
+  "name": "lib",
+  "testExports": {
+    ".": "./test.js"
+  },
+  "exports": {
+    ".": "./index.js"
+  }
+}
+```
+
+When this configuration is `["testExports", "exports"]`, the result of `import value from 'lib'` is `lib/test.js`.
+
 ## resolve.extensions
 
 - **Type:** `string[]`
@@ -181,16 +202,15 @@ Customize the `imports` field in package.json which are used to provide the inte
 
 e.g.
 
-```
-// package.json
+```json title="package.json"
 {
   "name": "lib",
   "imports": {
     "#foo": "./src/foo.js",
     "#common/*": "./src/common/*.js"
-  }
+  },
   "testImports": {
-    "#foo": "./src/test/foo.js",
+    "#foo": "./src/test/foo.js"
   }
 }
 ```
@@ -200,21 +220,41 @@ When this configuration is ["testImports", "imports"], the result of `import val
 ## resolve.mainFields
 
 - **Type:** `string[]`
-- **Default:**
-  - `target` is `["browser", "module", "main"]` when it is web
-  - `["module", "main"]` for others
+- **Default:** Based on the [target](/config/target) option
+
+When importing from an npm package, for example `import React from 'react'`, `resolve.mainFields` is used to determine which fields in `package.json` are resolved.
 
-Try to parse the fields in package.json, e.g.
+If `target` is `'web'`, `'webworker'`, or not specified, the default value is `["browser", "module", "main"]`.
+
+```js title="rspack.config.js"
+module.exports = {
+  resolve: {
+    mainFields: ['browser', 'module', 'main'],
+  },
+};
+```
 
-```json
-// package.json
+For any other `target` (including `'node'`), the default value is `["module", "main"]`.
+
+```js title="rspack.config.js"
+module.exports = {
+  resolve: {
+    mainFields: ['module', 'main'],
+  },
+};
+```
+
+For example, consider an arbitrary library called `foo` with a `package.json` that contains the following fields:
+
+```json title="package.json"
 {
-  "name": "lib",
-  "module": "es/index.js"
+  "name": "foo",
+  "browser": "./dist/browser.js",
+  "module": "./dist/module.js"
 }
 ```
 
-then `import value from 'lib'` results in `lib/es/index.js`.
+When `import foo from 'foo'`, Rspack resolves to the module in the `browser` field, because the `browser` field has the highest priority in `mainFields` array.
 
 ## resolve.mainFiles
 
@@ -223,28 +263,16 @@ then `import value from 'lib'` results in `lib/es/index.js`.
 
 The filename suffix when resolving directories, e.g. `require('. /dir/')` will try to resolve `'. /dir/index'`.
 
-## resolve.exportsFields
-
-- **Type:** `string[]`
-- **Default:** `["exports"]`
-
-Customize the `exports` field in package.json. e.g.
+Can configure multiple filename suffixes:
 
-```json
-// lib/package.json
-{
-  "name": "lib",
-  "testExports": {
-    ".": "./test.js"
+```js title="rspack.config.js"
+module.exports = {
+  resolve: {
+    mainFiles: ['index', 'main'],
   },
-  "exports": {
-    ".": "./index.js"
-  }
-}
+};
 ```
 
-When this configuration is `["testExports", "exports"]`, the result of `import value from 'lib'` is `lib/test.js`.
-
 ## resolve.modules
 
 - **Type:** `string[]`

diff --git a/website/docs/zh/config/resolve.mdx b/website/docs/zh/config/resolve.mdx
@@ -73,6 +73,27 @@ module.exports = {
 };
 ```
 
+## resolve.exportsFields
+
+- **类型：** `string[]`
+- **默认值：** `["exports"]`
+
+自定义 package.json 中的 exports 字段，例如：
+
+```json title="lib/package.json"
+{
+  "name": "lib",
+  "testExports": {
+    ".": "./test.js"
+  },
+  "exports": {
+    ".": "./index.js"
+  }
+}
+```
+
+则当配置为 `["testExports", "exports"]` 时, `import value from 'lib'` 的结果为 `lib/test.js`。
+
 ## resolve.extensions
 
 - **类型：** `string[]`
@@ -172,78 +193,85 @@ module.exports = {
 };
 ```
 
-## resolve.mainFields
+## resolve.importsFields
 
 - **类型：** `string[]`
-- **默认值：**
-  - `target` 为 web 时为 `["browser", "module", "main"]`
-  - 其他则为 `["module", "main"]`
+- **默认值:** `['imports']`
+
+自定义 package.json 中的 imports 字段，用于提供包的内部请求（以 `#` 开头的请求被视为内部请求）
 
-尝试解析 package.json 中的字段，例如：
+例如：
 
-```json
-// package.json
+```json title="package.json"
 {
   "name": "lib",
-  "module": "es/index.js"
+  "imports": {
+    "#foo": "./src/foo.js",
+    "#common/*": "./src/common/*.js"
+  },
+  "testImports": {
+    "#foo": "./src/test/foo.js"
+  }
 }
 ```
 
-则 `import value from 'lib'` 的结果为 `lib/es/index.js`。
+则当配置为 ["testImports", "imports"] 时, 当前包内 `import value from '#foo'` 的结果为 `src/test/foo.js`。
 
-## resolve.mainFiles
+## resolve.mainFields
 
 - **类型：** `string[]`
-- **默认值：** `["index"]`
+- **默认值：** 根据 [target](/config/target) 选项确定
 
-解析目录时的文件名后缀，例如 `require('./dir/')` 会尝试解析 `'./dir/index'`。
+当从 npm 包导入时，例如 `import React from 'react'`，`resolve.mainFields` 用于确定其 `package.json` 中的哪些字段会被解析。
 
-## resolve.exportsFields
+当 `target` 配置为 `'web'`, `'webworker'`, 或未指定时，默认值为 `["browser", "module", "main"]`。
 
-- **类型：** `string[]`
-- **默认值：** `["exports"]`
+```js title="rspack.config.js"
+module.exports = {
+  resolve: {
+    mainFields: ['browser', 'module', 'main'],
+  },
+};
+```
 
-自定义 package.json 中的 exports 字段，例如：
+对于任何其他 `target`（包括 `'node'`）, 默认值为 `["module", "main"]`。
 
-```json
-// lib/package.json
-{
-  "name": "lib",
-  "testExports": {
-    ".": "./test.js"
+```js title="rspack.config.js"
+module.exports = {
+  resolve: {
+    mainFields: ['module', 'main'],
   },
-  "exports": {
-    ".": "./index.js"
-  }
+};
+```
+
+例如，对于一个名为 `foo` 的库，它的 `package.json` 包含以下字段：
+
+```json title="package.json"
+{
+  "name": "foo",
+  "browser": "./dist/browser.js",
+  "module": "./dist/module.js"
 }
 ```
 
-则当配置为 `["testExports", "exports"]` 时, `import value from 'lib'` 的结果为 `lib/test.js`。
+当 `import foo from 'foo'` 时，Rspack 会解析到 `browser` 字段中的模块，因为 `browser` 字段在 `mainFields` 数组中优先级最高。
 
-## resolve.importsFields
+## resolve.mainFiles
 
 - **类型：** `string[]`
-- **默认值:** `['imports']`
+- **默认值：** `["index"]`
 
-自定义 package.json 中的 imports 字段，用于提供包的内部请求（以 `#` 开头的请求被视为内部请求）
+解析目录时的文件名后缀，例如 `require('./dir/')` 会尝试解析 `'./dir/index'`。
 
-例如：
+可以配置多个文件名后缀：
 
+```js title="rspack.config.js"
+module.exports = {
+  resolve: {
+    mainFiles: ['index', 'main'],
+  },
+};
 ```
-// package.json
-{
-  "name": "lib",
-  "imports": {
-    "#foo": "./src/foo.js",
-    "#common/*": "./src/common/*.js"
-  }
-  "testImports": {
-    "#foo": "./src/test/foo.js",
-  }
-}
-```
-
-则当配置为 ["testImports", "imports"] 时, 当前包内 `import value from '#foo'` 的结果为 `src/test/foo.js`。
 
 ## resolve.modules