Skip to content

Commit 2e2784a

Browse files
chenjiahanCopilot
chenjiahan
and
Copilot
authored
docs: improve node configurations (#12547)
* docs: improve node configurations * docs * docs: update * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Apply suggestions from code review --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent 998d747 commit 2e2784a

2 files changed

Lines changed: 124 additions & 48 deletions

File tree

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

Lines changed: 62 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,13 @@ Controls whether Rspack should provide a polyfill for the Node.js `global` objec
1515

1616
See [the Node.js documentation](https://nodejs.org/api/globals.html#globals_global) for the exact behavior of this object.
1717

18-
Optional values:
18+
### Available values
1919

20-
- `true`: Rspack injects a polyfill so that `global` is available in the bundle. This ensures compatibility with code that relies on Node.js globals in non-Node runtimes.
21-
- `false`: No polyfill is provided. References to `global` remain untouched. If your target environment does not define `global`, accessing it will throw a `ReferenceError` at runtime.
22-
- `'warn'`: Inject a polyfill like `true`, but also emit a warning when `global` is used.
20+
- `true`: Rspack injects a polyfill so that `global` is available in the bundle. This ensures compatibility with code that relies on Node.js globals in non-Node runtimes
21+
- `false`: No polyfill is provided. References to `global` remain untouched. If your target environment does not define `global`, accessing it will throw a `ReferenceError` at runtime
22+
- `'warn'`: Inject a polyfill like `true`, but also emit a warning when `global` is used
23+
24+
### Examples
2325

2426
For example, to disable `global` polyfill:
2527

@@ -34,20 +36,24 @@ export default {
3436
## node.\_\_filename
3537

3638
- **Type:** `boolean | 'mock' | 'warn-mock' | 'eval-only'`
37-
- **Default:** `'warn-mock'`, `'node-module'` when [output.module](/config/output#outputmodule) is enabled
39+
- **Default:**
40+
- If `target` does not include `node`, defaults to `'warn-mock'`.
41+
- If `target` includes `node`, uses `'node-module'` if [output.module](/config/output#outputmodule) is enabled, otherwise `'eval-only'`.
42+
43+
Controls how Rspack handles the Node.js [`__filename`](https://nodejs.org/api/modules.html#__filename) and [`import.meta.filename`](https://nodejs.org/api/esm.html#importmetafilename) variables when bundling for non-Node environments.
3844

39-
Controls how Rspack handles the Node.js [`__filename`](https://nodejs.org/api/modules.html#__filename) variable when bundling for non-Node environments.
45+
### Available values
4046

41-
Optional values:
47+
- `true`: Replace with the source file path, relative to the [`context`](/config/context) option
48+
- `false`: Do nothing and keep the native behavior
49+
- `'mock'`: Replace with `/index.js`
50+
- `'mock'`: Replace with `'/index.js'`
51+
- `'warn-mock'`: Replace with `'/index.js'`, and emit a warning to indicate a potential Node.js dependency in the code
52+
- `'node-module'`: Only used when [output.module](/config/output#outputmodule) is enabled. Replace `__filename` in CommonJS with an equivalent implementation based on `import.meta.url`, suitable for ESM output
4253

43-
- `true`: The filename of the input file relative to the [`context`](/config/context) option.
44-
- `false`: Rspack won't touch your `__filename` code, which means you have the regular Node.js `__filename` behavior. The filename of the **output** file when run in a Node.js environment.
45-
- `'mock'`: The fixed value `'/index.js'`.
46-
- `'warn-mock'`: Use the fixed value of `'/index.js'` but show a warning.
47-
- `'node-module'`: Replace `__filename` in CommonJS modules to `fileURLToPath(import.meta.url)` when `output.module` is enabled.
48-
- `'eval-only'`: Equivalent to `false`.
54+
### Examples
4955

50-
For example, to leave `__filename` as it is:
56+
For example, to leave `__filename` and `import.meta.filename` as it is:
5157

5258
```js title="rspack.config.mjs"
5359
export default {
@@ -57,23 +63,41 @@ export default {
5763
};
5864
```
5965

66+
To replace `__filename` in ESM output with `fileURLToPath(import.meta.url)`:
67+
68+
```js title="rspack.config.mjs"
69+
export default {
70+
target: 'node',
71+
output: {
72+
module: true,
73+
},
74+
node: {
75+
__filename: 'node-module',
76+
},
77+
};
78+
```
79+
6080
## node.\_\_dirname
6181

6282
- **Type:** `boolean | 'mock' | 'warn-mock' | 'eval-only'`
63-
- **Default:** `'warn-mock'`, `'node-module'` when `output.module` is enabled
83+
- **Default:**
84+
- If `target` does not include `node`, defaults to `'warn-mock'`.
85+
- If `target` includes `node`, uses `'node-module'` if [output.module](/config/output#outputmodule) is enabled, otherwise `'eval-only'`.
6486

65-
Controls how Rspack handles the Node.js [`__dirname`](https://nodejs.org/api/modules.html#__dirname) variable when bundling for non-Node environments.
87+
Controls how Rspack handles the Node.js [`__dirname`](https://nodejs.org/api/modules.html#__dirname) and [`import.meta.dirname`](https://nodejs.org/api/esm.html#importmetadirname) variables when bundling for non-Node environments.
6688

67-
Optional values:
89+
### Available values
6890

69-
- `true`: The dirname of the **input** file relative to the [`context`](/config/context) option.
70-
- `false`: Rspack won't touch your `__dirname` code, which means you have the regular Node.js `__dirname` behavior. The dirname of the **output** file when run in a Node.js environment.
71-
- `'mock'`: The fixed value `'/'`.
72-
- `'warn-mock'`: Use the fixed value of `'/'` but show a warning.
73-
- `'node-module'`: Replace `__dirname` in CommonJS modules to `fileURLToPath(import.meta.url + "/..")` when `output.module` is enabled.
74-
- `'eval-only'`: Equivalent to `false`.
91+
- `true`: Replace with the directory path of the source file, relative to the [`context`](/config/context) option
92+
- `false`: Do nothing and keep the native behavior
93+
- `'mock'`: Replace with `'/'`
94+
- `'eval-only'`: Equivalent to `false`
95+
- `'warn-mock'`: Replace with `'/'`, and emit a warning to indicate a potential Node.js dependency in the code
96+
- `'node-module'`: Only used when [output.module](/config/output#outputmodule) is enabled. Replace `__dirname` in CommonJS with an equivalent implementation based on `import.meta.url`, suitable for ESM output
7597

76-
For example, to leave `__dirname` as it is:
98+
### Examples
99+
100+
For example, to leave `__dirname` and `import.meta.dirname` as it is:
77101

78102
```js title="rspack.config.mjs"
79103
export default {
@@ -82,3 +106,17 @@ export default {
82106
},
83107
};
84108
```
109+
110+
To replace `__dirname` in ESM output with `fileURLToPath(import.meta.url + "/..")`:
111+
112+
```js title="rspack.config.mjs"
113+
export default {
114+
target: 'node',
115+
output: {
116+
module: true,
117+
},
118+
node: {
119+
__dirname: 'node-module',
120+
},
121+
};
122+
```

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

Lines changed: 62 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,13 @@ import WebpackLicense from '@components/WebpackLicense';
1515

1616
关于该对象的具体行为，请参考 [Node.js 文档](https://nodejs.org/api/globals.html#globals_global)。
1717

18-
可选值有：
18+
### 可选值
1919

20-
- `true`：Rspack 会注入 polyfill，使打包产物中能够使用 `global`。适用于依赖 Node.js 全局变量、但运行在非 Node 环境的代码。
21-
- `false`：不注入 polyfill。对 `global` 的引用将保持原样。如果目标环境不支持 `global`，运行时会抛出 `ReferenceError`。
22-
- `'warn'`：行为与 `true` 相同，会注入 polyfill，同时在使用 `global` 时额外打印警告。
20+
- `true`：Rspack 会注入 polyfill，使打包产物中能够使用 `global`。适用于依赖 Node.js 全局变量、但运行在非 Node 环境的代码
21+
- `false`：不注入 polyfill。对 `global` 的引用将保持原样。如果目标环境不支持 `global`，运行时会抛出 `ReferenceError`
22+
- `'warn'`：行为与 `true` 相同，会注入 polyfill，同时在使用 `global` 时额外打印警告
23+
24+
### 示例
2325

2426
例如，禁用 `global` polyfill：
2527

@@ -34,20 +36,24 @@ export default {
3436
## node.\_\_filename
3537

3638
- **类型：** `boolean | 'mock' | 'warn-mock' | 'eval-only'`
37-
- **默认值：** `'warn-mock'`，当启用 [output.module](/config/output#outputmodule) 时为 `'node-module'`
39+
- **默认值：**
40+
- 当 `target` 不包含 `node` 时，默认值为 `'warn-mock'`。
41+
- 当 `target` 包含 `node` 时，启用 [output.module](/config/output#outputmodule) 则为 `'node-module'`，否则为 `'eval-only'`
42+
43+
控制 Rspack 在为非 Node 环境打包时，如何处理 Node.js 的 [`__filename`](https://nodejs.org/api/modules.html#__filename) 和 [`import.meta.filename`](https://nodejs.org/api/esm.html#importmetafilename) 变量。
3844

39-
控制 Rspack 在为非 Node 环境打包时，如何处理 Node.js 的 [`__filename`](https://nodejs.org/api/modules.html#__filename) 变量。
45+
### 可选值
4046

41-
可选值有：
47+
- `true`：替换为源文件的文件路径，相对于 [`context`](/config/context) 选项
48+
- `false`：不做任何处理，保持原生行为
49+
- `'mock'`：替换为 `'/index.js'`
50+
- `'eval-only'`：等同于 `false`
51+
- `'warn-mock'`：替换为 `'/index.js'`，并输出警告，用于提醒代码中存在潜在的 Node 依赖
52+
- `'node-module'`：仅在 [output.module](/config/output#outputmodule) 启用时使用。将 CommonJS 中的 `__filename` 替换为基于 `import.meta.url` 的等价实现，适合 ESM 产物
4253

43-
- `true`：输入文件的文件名，是相对于 [`context`](/config/context) 选项。
44-
- `false`：Rspack 不会更改 `__filename` 的代码。在 Node.js 环境中运行时输出文件的文件名。
45-
- `'mock'`：固定值为 '/index.js'。
46-
- `'warn-mock'`：使用固定值 '/index.js'，但会发出警告。
47-
- `'node-module'`：当 `output.module` 启用时，将 CommonJS 模块中的 `__filename` 替换为 `fileURLToPath(import.meta.url)`。
48-
- `'eval-only'`：等同于 `false`。
54+
### 示例
4955

50-
例如，不对 `__filename` 进行任何处理：
56+
例如，不对 `__filename` 和 `import.meta.filename` 进行任何处理：
5157

5258
```js title="rspack.config.mjs"
5359
export default {
@@ -57,23 +63,41 @@ export default {
5763
};
5864
```
5965

66+
将 ESM 产物中的 `__filename` 替换为 `fileURLToPath(import.meta.url)`：
67+
68+
```js title="rspack.config.mjs"
69+
export default {
70+
target: 'node',
71+
output: {
72+
module: true,
73+
},
74+
node: {
75+
__filename: 'node-module',
76+
},
77+
};
78+
```
79+
6080
## node.\_\_dirname
6181

6282
- **类型：** `boolean | 'mock' | 'warn-mock' | 'eval-only'`
63-
- **默认值：** `'warn-mock'`，当启用 [output.module](/config/output#outputmodule) 时为 `'node-module'`
83+
- **默认值：**
84+
- 当 `target` 不包含 `node` 时，默认值为 `'warn-mock'`。
85+
- 当 `target` 包含 `node` 时，启用 [output.module](/config/output#outputmodule) 则为 `'node-module'`，否则为 `'eval-only'`
6486

65-
控制 Rspack 在为非 Node 环境打包时，如何处理 Node.js 的 [`__dirname`](https://nodejs.org/api/modules.html#__dirname) 变量。
87+
控制 Rspack 在为非 Node 环境打包时，如何处理 Node.js 的 [`__dirname`](https://nodejs.org/api/modules.html#__dirname) 和 [`import.meta.dirname`](https://nodejs.org/api/esm.html#importmetadirname) 变量。
6688

67-
可选值有：
89+
### 可选值
6890

69-
- `true`：**输入** 文件的目录名，是相对于 [`context`](/config/context) 选项。
70-
- `false`：Rspack 不会更改 `__dirname` 的代码，这意味着你有常规 Node.js 中的 `__dirname` 的行为。在 Node.js 环境中运行时，**输出** 文件的目录名。
71-
- `'mock'`：value 填充为 `'/'`。
72-
- `'warn-mock'`：使用 `'/'` 但是会显示一个警告。
73-
- `'node-module'`: 当启用 `output.module` 时，将 CommonJS 模块中的 `__dirname` 替换为 `fileURLToPath(import.meta.url + "/..")`。
74-
- `'eval-only'`：等同于 `false`。
91+
- `true`：替换为源文件的目录路径，相对于 [`context`](/config/context) 选项
92+
- `false`：不做任何处理，保持原生行为
93+
- `'mock'`：替换为 `'/'`
94+
- `'eval-only'`：等同于 `false`
95+
- `'warn-mock'`：替换为 `'/'`，并输出警告，用于提醒代码中存在潜在的 Node 依赖
96+
- `'node-module'`：仅在 [output.module](/config/output#outputmodule) 启用时使用。将 CommonJS 中的 `__dirname` 替换为基于 `import.meta.url` 的等价实现，适合 ESM 产物
7597

76-
例如，不对 `__dirname` 进行任何处理：
98+
### 示例
99+
100+
例如，不对 `__dirname` 和 `import.meta.dirname` 进行任何处理：
77101

78102
```js title="rspack.config.mjs"
79103
export default {
@@ -82,3 +106,17 @@ export default {
82106
},
83107
};
84108
```
109+
110+
将 ESM 产物中的 `__dirname` 替换为 `fileURLToPath(import.meta.url + "/..")`：
111+
112+
```js title="rspack.config.mjs"
113+
export default {
114+
target: 'node',
115+
output: {
116+
module: true,
117+
},
118+
node: {
119+
__dirname: 'node-module',
120+
},
121+
};
122+
```

0 commit comments

Comments
 (0)