Skip to content

Commit 1228bcf

Browse files
chenjiahanchenjiahan
authored
docs: improve resolve.conditionNames documentation (#11216)
1 parent ffd0ebd commit 1228bcf

File tree

3 files changed

+202
-5
lines changed

3 files changed

+202
-5
lines changed

‎packages/rspack/src/config/types.ts

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -704,7 +704,10 @@ export type ResolveOptions = {
704704
/** Path alias */
705705
alias?: ResolveAlias;
706706

707-
/** Same as node's [conditionNames](https://nodejs.org/api/packages.html#conditional-exports) for the exports and imports fields in package.json. */
707+
/**
708+
* Specifies the condition names used to match entry points in the `exports` field of a package.
709+
* @link https://nodejs.org/api/packages.html#packages_exports
710+
*/
708711
conditionNames?: string[];
709712

710713
/**

‎website/docs/en/config/resolve.mdx

Lines changed: 99 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,106 @@ Define a field, such as `browser`, that should be parsed in accordance with [thi
3838
## resolve.conditionNames
3939

4040
- **Type:** `string[]`
41-
- **Default:** `[]`
4241

43-
Same as node's [conditionNames](https://nodejs.org/api/packages.html#conditional-exports) for the `exports` and `imports` fields in package.json.
42+
Specifies the condition names used to match entry points in the [`exports` field](https://nodejs.org/api/packages.html#packages_exports) of a package.
43+
44+
```js title="rspack.config.mjs"
45+
export default {
46+
resolve: {
47+
conditionNames: ['require', 'node'],
48+
},
49+
};
50+
```
51+
52+
### Default value
53+
54+
Rspack's default `conditionNames` are determined by [mode](/config/mode), [target](/config/target) and module type.
55+
56+
```js
57+
// For ES modules
58+
['import', 'module', 'webpack', mode, target];
59+
60+
// For CommonJS
61+
['require', 'module', 'webpack', mode, target];
62+
63+
// For CSS module
64+
['webpack', mode, 'style'];
65+
```
66+
67+
In the above example:
68+
69+
- `mode` is determined by [mode](/config/mode) config, which is `development` in development mode and `production` in other modes.
70+
- `target` is determined by [target](/config/target) config:
71+
- If `target` includes `web`, it will be `browser`.
72+
- If `target` includes `node`, it will be `node`.
73+
- If `target` includes `webworker`, it will be `worker`.
74+
- If `target` includes `electron`, it will be `electron`.
75+
- If `target` includes `nwjs`, it will be `nwjs`.
76+
77+
### Example
78+
79+
Rspack will match [export conditions](https://nodejs.org/api/packages.html#conditional-exports) that are listed within the `resolve.conditionNames` array.
80+
81+
Note that the key order in the `exports` object determines priority. During condition matching, earlier entries have higher priority than later entries.
82+
83+
For example:
84+
85+
```json title="package.json"
86+
{
87+
"name": "foo",
88+
"exports": {
89+
".": {
90+
"import": "./index-import.js",
91+
"require": "./index-require.js",
92+
"node": "./index-node.js"
93+
},
94+
"./bar": {
95+
"node": "./bar-node.js",
96+
"require": "./bar-require.js"
97+
},
98+
"./baz": {
99+
"import": "./baz-import.js",
100+
"node": "./baz-node.js"
101+
}
102+
}
103+
}
104+
```
105+
106+
```js title="rspack.config.mjs"
107+
export default {
108+
resolve: {
109+
conditionNames: ['require', 'node'],
110+
},
111+
};
112+
```
113+
114+
Importing:
115+
116+
- `'foo'` will resolve to `'foo/index-require.js'`
117+
- `'foo/bar'` will resolve to `'foo/bar-node.js'` as the `"node"` key comes before `"require"` key in the conditional exports object.
118+
- `'foo/baz'` will resolve to `'foo/baz-node.js'`
119+
120+
### Extend default value
121+
122+
If you want to add your custom conditions names while still retaining the default Rspack values, you can use `"..."`:
123+
124+
```js title="rspack.config.mjs"
125+
export default {
126+
resolve: {
127+
conditionNames: ['my-custom-condition', '...'],
128+
},
129+
};
130+
```
131+
132+
Alternatively, to prioritize the default value first and then add your custom condition names:
133+
134+
```js title="rspack.config.mjs"
135+
export default {
136+
resolve: {
137+
conditionNames: ['...', 'my-custom-condition'],
138+
},
139+
};
140+
```
44141

45142
## resolve.descriptionFiles
46143

‎website/docs/zh/config/resolve.mdx

Lines changed: 99 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,106 @@ import WebpackLicense from '@components/WebpackLicense';
3838
## resolve.conditionNames
3939

4040
- **类型：** `string[]`
41-
- **默认值：** `[]`
4241

43-
与 node 的 [conditionNames](https://nodejs.org/api/packages.html#conditional-exports) 相同，用于 package.json 中的 `exports` 和 `imports` 字段。
42+
指定用于匹配包 [`exports` 字段](https://nodejs.org/api/packages.html#packages_exports) 入口点的 condition names（条件名称）。
43+
44+
```js title="rspack.config.mjs"
45+
export default {
46+
resolve: {
47+
conditionNames: ['require', 'node'],
48+
},
49+
};
50+
```
51+
52+
### 默认值
53+
54+
Rspack 默认的 `conditionNames` 由 [mode](/config/mode)、[target](/config/target) 和模块类型共同决定。
55+
56+
```js
57+
// 针对 ES modules
58+
['import', 'module', 'webpack', mode, target];
59+
60+
// 针对 CommonJS
61+
['require', 'module', 'webpack', mode, target];
62+
63+
// 针对 CSS 模块
64+
['webpack', mode, 'style'];
65+
```
66+
67+
在上述示例中：
68+
69+
- `mode` 由 [mode](/config/mode) 配置决定，开发模式下为 `development`，其他模式为 `production`。
70+
- `target` 由 [target](/config/target) 配置决定：
71+
- 如果 `target` 包含 `web`，则为 `browser`。
72+
- 如果 `target` 包含 `node`，则为 `node`。
73+
- 如果 `target` 包含 `webworker`，则为 `worker`。
74+
- 如果 `target` 包含 `electron`，则为 `electron`。
75+
- 如果 `target` 包含 `nwjs`，则为 `nwjs`。
76+
77+
### 示例
78+
79+
Rspack 会匹配 `resolve.conditionNames` 数组中列出的 [export conditions](https://nodejs.org/api/packages.html#conditional-exports)。
80+
81+
注意，`exports` 对象中 key 的顺序决定了优先级。在条件匹配时，前面的入口优先级高于后面的入口。
82+
83+
例如：
84+
85+
```json title="package.json"
86+
{
87+
"name": "foo",
88+
"exports": {
89+
".": {
90+
"import": "./index-import.js",
91+
"require": "./index-require.js",
92+
"node": "./index-node.js"
93+
},
94+
"./bar": {
95+
"node": "./bar-node.js",
96+
"require": "./bar-require.js"
97+
},
98+
"./baz": {
99+
"import": "./baz-import.js",
100+
"node": "./baz-node.js"
101+
}
102+
}
103+
}
104+
```
105+
106+
```js title="rspack.config.mjs"
107+
export default {
108+
resolve: {
109+
conditionNames: ['require', 'node'],
110+
},
111+
};
112+
```
113+
114+
导入时：
115+
116+
- `'foo'` 会被解析为 `'foo/index-require.js'`
117+
- `'foo/bar'` 会被解析为 `'foo/bar-node.js'`，因为在条件导出对象中 `"node"` 键优先于 `"require"` 键
118+
- `'foo/baz'` 会被解析为 `'foo/baz-node.js'`
119+
120+
### 扩展默认值
121+
122+
如果你希望在保留 Rspack 默认值的同时添加自定义的 condition names，可以使用 `"..."`：
123+
124+
```js title="rspack.config.mjs"
125+
export default {
126+
resolve: {
127+
conditionNames: ['my-custom-condition', '...'],
128+
},
129+
};
130+
```
131+
132+
或者，如果你想让默认值优先，再追加自定义 condition names：
133+
134+
```js title="rspack.config.mjs"
135+
export default {
136+
resolve: {
137+
conditionNames: ['...', 'my-custom-condition'],
138+
},
139+
};
140+
```
44141

45142
## resolve.descriptionFiles
46143

0 commit comments

Comments
 (0)