docs(config): Document how to use built-in Node.js modules #1368

Rob--W · 2017-07-05T00:33:08Z

The documentation about using built-in Node.js modules was very poor (i.e. non-existent). This PR expands the documentation of the "node" configuration option, and shows how one can require built-in modules if desired.

Furthermore, all possible effects of the options are explicitly documented. Instead of being vague of what happens when false is used, it is explicitly spelled out what happens.

References:

https://github.com/webpack/webpack/blob/a589a6c9789a9d342fc630e36ab81827dd20289b/lib/WebpackOptionsApply.js
shows when the NodeStuffPlugin and NodeSourcePlugin plugins are used.
https://github.com/webpack/webpack/blob/a589a6c9789a9d342fc630e36ab81827dd20289b/lib/NodeStuffPlugin.js
is the plugin that is used for every target.
https://github.com/webpack/webpack/blob/a589a6c9789a9d342fc630e36ab81827dd20289b/lib/node/NodeSourcePlugin.js
is the plugin that is only used for "web" and "webworker" targets.
https://github.com/webpack/webpack/blob/a589a6c9789a9d342fc630e36ab81827dd20289b/lib/MultiModule.js#L65-L67
is the generated "webpackMissingModule" code for unresolved modules. (when the NodeSourcePlugin is not used, the environment's "require" is used. In Node.js, this also throws a "Cannot find module 'modulename'" error (with single quotes instead of double quotes).

wearhere · 2017-07-05T23:46:32Z

content/configuration/node.md


-By default, Webpack will polyfill each library if there is a known polyfill or do nothing if there is not one.
+T> To import a built-in module, use [`__non_webpack_require__`](/api/module-variables/#__non_webpack_require__-webpack-specific-),


to import a built-in module

Instead of a polyfill, you mean?

Also. Importing using the default require instead of a polyfill, mock, or erroring.

wearhere · 2017-07-05T23:46:50Z

content/configuration/node.md

@@ -109,9 +120,18 @@ Default: `true`

 `boolean | "mock" | "empty"`

-Many other Node.js core libraries can be configured as well. See the list of [Node.js core libraries and their polyfills](https://github.com/webpack/node-libs-browser).
+W> This option is only activated (via `NodeSourcePlugin`) when the target is unspecified, "browser" or "webworker".


This puts the text in a warning box. T> is a tip box, ?> is a TODO box.

skipjack

Sorry for the delay on this PR and thanks for your contribution. The changes look great for the most part, just added a few minor comments. Once those things are addressed we should be able to get this merged.

skipjack · 2017-07-25T02:40:52Z

content/configuration/node.md

+[`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.


Can you leave the formatting as is? We may automatically enforce a max line length at some point (webpack-contrib/webpack-defaults#73) but for now we typically keep paragraphs all on one line and encourage contributors to word-wrap while editing these files. That said, it probably makes sense to split it into 2 paragraphs as such:

These 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. 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.

Done. Note that I did not just split the paragraph, I also added "plugin" after "NodeStuffPlugin", so that it has become "NodeStuffPlugin plugin".

skipjack · 2017-07-25T02:43:20Z

content/configuration/node.md

- `false`: Provide nothing. Code that expects this object to be defined may crash.
+- `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.


I'm not sure this extra description is necessary. I see where you're going with it, but there could be any number of errors that occur so just specifying that it may crash should be enough.

I added explicit error messages so that search engines can find the documentation more easily.

skipjack · 2017-07-25T02:45:44Z

content/configuration/node.md

+Polyfills for Node.js core libraries from
+[`node-libs-browser`](https://github.com/webpack/node-libs-browser) are used if
+available, when the `NodeSourcePlugin` plugin is enabled.
+See the list of [Node.js core libraries and their polyfills](https://github.com/webpack/node-libs-browser#readme).


Again, the changes here look 👍 but please drop the line breaks as it's all one paragraph.

I combined the first three lines that formed one sentence in one line. The last sentence is still separate because the message that it conveys is not depending on the previous line.

skipjack · 2017-07-25T02:46:07Z

content/configuration/node.md

+See the list of [Node.js core libraries and their polyfills](https://github.com/webpack/node-libs-browser#readme).
+
+By default, webpack will polyfill each library if there is a known polyfill or do nothing if there is not one.
+In the latter case, webpack will behave as if the module name was configured with the `false` value.


skipjack · 2017-07-25T02:46:55Z

content/configuration/node.md


-By default, Webpack will polyfill each library if there is a known polyfill or do nothing if there is not one.
+T> To import a built-in module, use [`__non_webpack_require__`](/api/module-variables/#__non_webpack_require__-webpack-specific-),
+   i.e. `__non_webpack_require__('modulename')` instead of `require('modulename')`.


Same here -- i.e. the whole T> should all fall on line 133.

The documentation about using built-in Node.js modules was very poor (i.e. non-existent). This expands the documentation of the "node" configuration option, and shows how one can require built-in modules if desired. Furthermore, all possible effects of the options are explicitly documented. Instead of being vague of what happens when `false` is used, it is explicitly spelled out what happens. References: - https://github.com/webpack/webpack/blob/a589a6c9789a9d342fc630e36ab81827dd20289b/lib/WebpackOptionsApply.js shows when the NodeStuffPlugin and NodeSourcePlugin plugins are used. - https://github.com/webpack/webpack/blob/a589a6c9789a9d342fc630e36ab81827dd20289b/lib/NodeStuffPlugin.js is the plugin that is used for every target. - https://github.com/webpack/webpack/blob/a589a6c9789a9d342fc630e36ab81827dd20289b/lib/node/NodeSourcePlugin.js is the plugin that is only used for "web" and "webworker" targets. - https://github.com/webpack/webpack/blob/a589a6c9789a9d342fc630e36ab81827dd20289b/lib/MultiModule.js#L65-L67 is the generated "webpackMissingModule" code for unresolved modules. (when the NodeSourcePlugin is not used, the environment's "require" is used. In Node.js, this also throws a "Cannot find module 'modulename'" error (with single quotes instead of double quotes)).

* docs(config): change `global` to `root` in externals (#1214) The currently deployed documentation indicates that there are 4 module contexts you can specify under the externals config... - `global` - `commonjs` - `commonjs2` - `amd` ... which contradicts both the examples that surround it, and the actual library functionality. This just changes the word "global" to "root" in the section that lists the module contexts. * docs(config): clarify that HMR plugin can be added via a flag (#1478) * fix(markdown): resolve some odd code display bugs (#1486) Fix list formatting in `/development/plugin-patterns/`. Remove the `inline-block` declaration to let inline code flow more naturally and prevent this odd wrapping if other badly formatted lists slip in. * docs(guides): add note about chunkFilename (#1483) * docs(config): clarify the meaning of `Rule.parser` options (#1489) Fixes #1484 * docs(config): improve node documentation (#1368) The documentation about using built-in Node.js modules was very poor (i.e. non-existent). This expands the documentation of the "node" configuration option, and shows how one can require built-in modules if desired. Furthermore, all possible effects of the options are explicitly documented. Instead of being vague of what happens when `false` is used, it is explicitly spelled out what happens. References: - https://github.com/webpack/webpack/blob/a589a6c9789a9d342fc630e36ab81827dd20289b/lib/WebpackOptionsApply.js shows when the NodeStuffPlugin and NodeSourcePlugin plugins are used. - https://github.com/webpack/webpack/blob/a589a6c9789a9d342fc630e36ab81827dd20289b/lib/NodeStuffPlugin.js is the plugin that is used for every target. - https://github.com/webpack/webpack/blob/a589a6c9789a9d342fc630e36ab81827dd20289b/lib/node/NodeSourcePlugin.js is the plugin that is only used for "web" and "webworker" targets. - https://github.com/webpack/webpack/blob/a589a6c9789a9d342fc630e36ab81827dd20289b/lib/MultiModule.js#L65-L67 is the generated "webpackMissingModule" code for unresolved modules. (when the NodeSourcePlugin is not used, the environment's "require" is used. In Node.js, this also throws a "Cannot find module 'modulename'" error (with single quotes instead of double quotes)). * docs(config): correct substitutions in output.md (#1487) Correct `output.filename` substitutions and move the others to `output.sourceMapFilename`. Also fix `related` link in the context- replacement-plugin. Fixes #1467

skipjack added Configuration Enhancement labels Jul 5, 2017

wearhere reviewed Jul 5, 2017

View reviewed changes

Rob--W force-pushed the document-node-require branch from 570bb55 to f403a05 Compare July 6, 2017 10:51

skipjack requested changes Jul 25, 2017

View reviewed changes

Rob--W force-pushed the document-node-require branch from f403a05 to 21b1fc3 Compare August 4, 2017 10:15

Rob--W force-pushed the document-node-require branch from 21b1fc3 to 6636c98 Compare August 4, 2017 10:16

Merge branch 'master' into document-node-require

368ef05

skipjack approved these changes Aug 5, 2017

View reviewed changes

docs(config): minor formatting changes in node.md

f053d09

skipjack merged commit 1fdd547 into webpack:master Aug 6, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(config): Document how to use built-in Node.js modules #1368

docs(config): Document how to use built-in Node.js modules #1368

Rob--W commented Jul 5, 2017 •

edited

Loading

wearhere Jul 5, 2017

Rob--W Jul 5, 2017

wearhere Jul 5, 2017

Rob--W Jul 5, 2017

skipjack left a comment •

edited

Loading

skipjack Jul 25, 2017

Rob--W Aug 4, 2017

skipjack Jul 25, 2017

Rob--W Aug 4, 2017

skipjack Jul 25, 2017

Rob--W Aug 4, 2017

skipjack Jul 25, 2017

Rob--W Aug 4, 2017

skipjack Jul 25, 2017

Rob--W Aug 4, 2017


		By default, Webpack will polyfill each library if there is a known polyfill or do nothing if there is not one.
		T> To import a built-in module, use [`__non_webpack_require__`](/api/module-variables/#__non_webpack_require__-webpack-specific-),

docs(config): Document how to use built-in Node.js modules #1368

docs(config): Document how to use built-in Node.js modules #1368

Conversation

Rob--W commented Jul 5, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

skipjack left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Rob--W commented Jul 5, 2017 •

edited

Loading

skipjack left a comment •

edited

Loading