From 6636c9846457839df624a78a25222fcb2b063d3b Mon Sep 17 00:00:00 2001 From: Rob Wu Date: Wed, 5 Jul 2017 02:30:39 +0200 Subject: [PATCH 1/2] docs(config): Document how to use built-in Node.js modules 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)). --- content/configuration/node.md | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/content/configuration/node.md b/content/configuration/node.md index 059a94055fd3..425f290ffb98 100644 --- a/content/configuration/node.md +++ b/content/configuration/node.md @@ -5,9 +5,12 @@ contributors: - sokra - skipjack - oneforwonder + - Rob--W --- -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). +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. ## `node` @@ -19,7 +22,8 @@ This is an object where each property is the name of a Node global or module and - `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 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. 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. `process: 'empty'`). See the sections below for more details. @@ -34,10 +38,12 @@ node: { __dirname: "mock", Buffer: true, setImmediate: true + + // See "Other node core libraries" for additional options. } ``` -Since webpack 3.0.0, the `node` option may be set to `false` to turn off the `NodeSourcePlugin` completely. +Since webpack 3.0.0, the `node` option may be set to `false` to completely turn off the `NodeStuffPlugin` and `NodeSourcePlugin` plugins. ## `node.console` @@ -109,9 +115,14 @@ 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, "web" or "webworker". + +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). + +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. -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')`. Example: From f053d09faac77eb1b820b0385a07b8350016f340 Mon Sep 17 00:00:00 2001 From: Greg Venech Date: Sat, 5 Aug 2017 14:10:37 -0400 Subject: [PATCH 2/2] docs(config): minor formatting changes in node.md --- content/configuration/node.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/content/configuration/node.md b/content/configuration/node.md index 425f290ffb98..7a5635341a98 100644 --- a/content/configuration/node.md +++ b/content/configuration/node.md @@ -9,8 +9,8 @@ contributors: --- 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. + +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. ## `node` @@ -22,8 +22,7 @@ This is an object where each property is the name of a Node global or module and - `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. +- `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. `process: 'empty'`). See the sections below for more details. @@ -117,8 +116,7 @@ Default: `true` W> This option is only activated (via `NodeSourcePlugin`) when the target is unspecified, "web" or "webworker". -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). +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). 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.