Skip to content

docs(configuration): update node page for webpack 5 #4078

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Nov 19, 2020
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 20 additions & 29 deletions src/content/configuration/node.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,29 +9,18 @@ contributors:
- byzyk
- EugeneHlushko
- anikethsaha
- chenxsan
---

The following Node.js options configure whether to polyfill or mock certain [Node.js globals](https://nodejs.org/docs/latest/api/globals.html) and modules. This allows code originally written for the Node.js environment to run in other environments like the browser.
The following Node.js options configure whether to polyfill or mock certain [Node.js globals](https://nodejs.org/docs/latest/api/globals.html).
Copy link
Member Author

@chenxsan chenxsan Oct 18, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

node option only defines three Node.js globals now https://github.com/webpack/webpack/blob/60f7ce301df553d8ab0276ba2838ddb60ead1c94/declarations/WebpackOptions.d.ts#L1365, so information related to modules is removed.

Copy link
Member Author

@chenxsan chenxsan Oct 18, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This allows code originally written for the Node.js environment to run in other environments like the browser. was removed as it's not true anymore, we have to polyfill Node.js modules like fs etc. as well, which is described in resolve.fallback section https://github.com/webpack/webpack/blob/master/lib/ModuleNotFoundError.js#L67.


This feature is provided by webpack's internal [`NodeStuffPlugin`](https://github.com/webpack/webpack/blob/master/lib/NodeStuffPlugin.js) plugin. If the target is "web" (default) or "webworker", the [`NodeSourcePlugin`](https://github.com/webpack/webpack/blob/master/lib/node/NodeSourcePlugin.js) plugin is also activated.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

NodeSourcePlugin is empty now https://github.com/webpack/webpack/blob/master/lib/node/NodeSourcePlugin.js, so no need to keep.

This feature is provided by webpack's internal [`NodeStuffPlugin`](https://github.com/webpack/webpack/blob/master/lib/NodeStuffPlugin.js) plugin.

W> As of webpack 5, You can configure only `global`, `__filename` or `__dirname` under `node` option. If you're looking for how to polyfill `fs` alike in Node.js under webpack 5, please check [resolve.fallback](/configuration/resolve/#resolvefallback) for help.

## `node`

`boolean = false` `object`

This is an object where each property is the name of a Node global or module and each value may be one of the following...

- `true`: Provide a polyfill.
- `'mock'`: Provide a mock that implements the expected interface but has little or no functionality.
- `'empty'`: Provide an empty object.
- `false`: Provide nothing. Code that expects this object may crash with a `ReferenceError`. Code that attempts to import the module using `require('modulename')` may trigger a `Cannot find module "modulename"` error.

W> Not every Node global supports all four options. The compiler will throw an error for property-value combinations that aren't supported (e.g. `global: 'empty'`). See the sections below for more details.

T> If you are using a module which needs global variables in it, use `ProvidePlugin` instead of `global`.

These are the defaults:
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've removed the whole part as I think they're already listed below, there's no need to duplicate them here. But I can revert it if you think it's better to keep.

`boolean: false` `object`

__webpack.config.js__

Expand All @@ -46,38 +35,40 @@ module.exports = {
};
```

Since webpack 3.0.0, the `node` option may be set to `false` to completely turn off the `NodeStuffPlugin` and `NodeSourcePlugin` plugins.
Since webpack 3.0.0, the `node` option may be set to `false` to completely turn off the `NodeStuffPlugin` plugin.

## `node.global`

`boolean = true`
`boolean`

Defaults to `false` for [targets](/configuration/target/) `node`, `async-node` and `electron-main`.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why remove this? Is there a summary of TARGETS I'm missing, or...?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't remember the specific reason. There're more than three targets having node.global set to false, which could be the reason I removed this.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The deleted info is outdated, indeed, but why not update it, instead of deleting it? How can I find out what it defaults to without digging into the code?

I'm concerned about this because I actually had an old todo, about improving this page, and by the time I got around to it, somebody already added the defaults, and when I went to look who did it, out of curiosity, I find that it got deleted 😄

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pr welcome.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't encourage me to contribute in this particular case. As it stands, it'll just get deleted a few months later again because of being slightly inaccurate.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, it's difficult to align with all changes happening in webpack core project. There will always some stale contents.

T> If you are using a module which needs global variables in it, use `ProvidePlugin` instead of `global`.

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

Options:

## `node.__filename`
- `true`: Provide a polyfill.
- `false`: Provide nothing. Code that expects this object may crash with a `ReferenceError`.

`boolean` `string = mock`
## `node.__filename`

Defaults to `false` for [targets](/configuration/target/) `node`, `async-node` and `electron-main`.
`boolean` `string: 'mock' | 'eval-only'`

Options:

- `true`: The filename of the __input__ file relative to the [`context` option](/configuration/entry-context/#context).
- `false`: The regular Node.js `__filename` behavior. The filename of the __output__ file when run in a Node.js environment.
- `'mock'`: The fixed value `'index.js'`.
- `false`: Webpack 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.
- `'mock'`: The fixed value `'/index.js'`.
- `'eval-only'`


## `node.__dirname`

`boolean` `string = mock`

Defaults to `false` for [targets](/configuration/target/) `node`, `async-node` and `electron-main`.
`boolean` `string: 'mock' | 'eval-only'`

Options:

- `true`: The dirname of the __input__ file relative to the [`context` option](/configuration/entry-context/#context).
- `false`: The regular Node.js `__dirname` behavior. The dirname of the __output__ file when run in a Node.js environment.
- `false`: Webpack 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.
- `'mock'`: The fixed value `'/'`.
- `'eval-only'`
Copy link
Member Author

@chenxsan chenxsan Oct 18, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It works same as false in my test, but I'm not sure of this value as there's no description in webpack repository.