From 4d3b34778ca65632cb9491e27db3e48d66ff805e Mon Sep 17 00:00:00 2001 From: Eslam El-Hakmey Date: Fri, 17 May 2019 15:54:33 +0200 Subject: [PATCH 1/4] chore(docs): add documentation for liveReload option --- src/content/api/cli.md | 734 +++--- src/content/configuration/dev-server.md | 2733 ++++++++++++----------- 2 files changed, 1746 insertions(+), 1721 deletions(-) diff --git a/src/content/api/cli.md b/src/content/api/cli.md index 189fffca2fb8..b5e8051ebc2f 100644 --- a/src/content/api/cli.md +++ b/src/content/api/cli.md @@ -1,366 +1,368 @@ ---- -title: Command Line Interface -sort: 2 -contributors: - - evenstensberg - - simon04 - - tbroadley - - chenxsan - - rencire - - madhavarshney - - EugeneHlushko - - byzyk - - wizardofhogwarts -related: - - title: Analyzing Build Statistics - url: https://survivejs.com/webpack/optimizing-build/analyzing-build-statistics/ - - title: Three simple ways to inspect a webpack bundle - url: https://medium.com/@joeclever/three-simple-ways-to-inspect-a-webpack-bundle-7f6a8fe7195d#.7d2i06mjx - - title: Optimising your application bundle size with webpack - url: https://hackernoon.com/optimising-your-application-bundle-size-with-webpack-e85b00bab579#.5w5ko08pq - - title: Analyzing & optimizing your webpack bundle - url: https://medium.com/@ahmedelgabri/analyzing-optimizing-your-webpack-bundle-8590818af4df#.hce4vdjs9 - - title: Analysing and minimising the size of client side bundle with webpack and source-map-explorer - url: https://medium.com/@nimgrg/analysing-and-minimising-the-size-of-client-side-bundle-with-webpack-and-source-map-explorer-41096559beca#.c3t2srr8x ---- - -For proper usage and easy distribution of this configuration, webpack can be configured with `webpack.config.js`. Any parameters sent to the CLI will map to a corresponding parameter in the config file. - -Read the [installation guide](/guides/installation) if you don't already have webpack and CLI installed. - - -## Usage with config file - -```bash -webpack [--config webpack.config.js] -``` - -See [configuration](/configuration) for the options in the configuration file. - - -## Usage without config file - -```sh -webpack [] -o -``` - -__``__ - -A filename or a set of named filenames which act as the entry point to build your project. You can pass multiple entries (every entry is loaded on startup). If you pass a pair in the form `=` you can create an additional entry point. It will be mapped to the configuration option `entry`. - -__``__ - -A path and filename for the bundled file to be saved in. It will be mapped to the configuration options `output.path` and `output.filename`. - -__Example__ - -If your project structure is as follows - - -```bash -. -├── dist -├── index.html -└── src - ├── index.js - ├── index2.js - └── others.js -``` - -```bash -webpack src/index.js -o dist/bundle.js -``` - -This will bundle your source code with entry as `index.js` and the output bundle file will have a path of `dist` and the filename will be `bundle.js` - -```bash - | Asset | Size | Chunks | Chunk Names | - |-----------|---------|-------------|-------------| - | bundle.js | 1.54 kB | 0 [emitted] | index | - [0] ./src/index.js 51 bytes {0} [built] - [1] ./src/others.js 29 bytes {0} [built] -``` - -```bash -webpack index=./src/index.js entry2=./src/index2.js dist/bundle.js -``` - -This will form the bundle with both the files as separate entry points. - -```bash - | Asset | Size | Chunks | Chunk Names | - |-----------|---------|---------------|---------------| - | bundle.js | 1.55 kB | 0,1 [emitted] | index, entry2 | - [0] ./src/index.js 51 bytes {0} [built] - [0] ./src/index2.js 54 bytes {1} [built] - [1] ./src/others.js 29 bytes {0} {1} [built] -``` - - -### Common Options - -W> Note that Command Line Interface has a higher precedence for the arguments you use it with than your configuration file. For instance, if you pass [`--mode="production"`](/configuration/mode/#usage) to webpack CLI and your configuration file uses `development`, `production` will be used. - -__List all of the options available on the cli__ - -```bash -webpack --help -webpack -h -``` - -__Build source using a config file__ - -Specifies a different [configuration](/configuration) file to pick up. Use this if you want to specify something different from `webpack.config.js`, which is the default. - -```bash -webpack --config example.config.js -``` - -__Print result of webpack as a JSON__ - -```bash -webpack --json -webpack --json > stats.json -``` - -In every other case, webpack prints out a set of stats showing bundle, chunk and timing details. Using this option the output can be a JSON object. This response is accepted by webpack's [analyse tool](https://webpack.github.io/analyse/), or chrisbateman's [webpack-visualizer](https://chrisbateman.github.io/webpack-visualizer/), or th0r's [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer). The analyse tool will take in the JSON and provide all the details of the build in graphical form. - -### Environment Options - -When the webpack configuration [exports a function](/configuration/configuration-types#exporting-a-function), an "environment" may be passed to it. - -```bash -webpack --env.production # sets env.production == true -webpack --env.platform=web # sets env.platform == "web" -``` - -The `--env` argument accepts various syntaxes: - -Invocation | Resulting environment ----------------------------------------- | --------------------------- -`webpack --env prod` | `"prod"` -`webpack --env.prod` | `{ prod: true }` -`webpack --env.prod=1` | `{ prod: 1 }` -`webpack --env.prod=foo` | `{ prod: "foo" }` -`webpack --env.prod --env.min` | `{ prod: true, min: true }` -`webpack --env.prod --env min` | `[{ prod: true }, "min"]` -`webpack --env.prod=foo --env.prod=bar` | `{prod: [ "foo", "bar" ]}` - -T> See the [environment variables](/guides/environment-variables) guide for more information on its usage. - -### Config Options - -Parameter | Explanation | Input type | Default -------------------------- | ------------------------------------------- | ---------- | ------------------ -`--config` | Path to the config file | string | webpack.config.js or webpackfile.js -`--config-register, -r` | Preload one or more modules before loading the webpack configuration | array | -`--config-name` | Name of the config to use | string | -`--env` | Environment passed to the config, when it is a function | | -`--mode` | Mode to use, either "development" or "production" | string | - -### Output Options - -This set of options allows you to manipulate certain [output](/configuration/output) parameters of your build. - -Parameter | Explanation | Input type | Default -------------------------- | ------------------------------------------- | ---------- | ------------------ -`--output-chunk-filename` | The output filename for additional chunks | string | filename with [id] instead of [name] or [id] prefixed -`--output-filename` | The output filename of the bundle | string | [name].js -`--output-jsonp-function` | The name of the JSONP function used for chunk loading | string | webpackJsonp -`--output-library` | Expose the exports of the entry point as library | string | -`--output-library-target` | The type for exposing the exports of the entry point as library | string | var -`--output-path` | The output path for compilation assets | string | Current directory -`--output-pathinfo` | Include a comment with the request for every dependency | boolean | false -`--output-public-path` | The public path for the assets | string | / -`--output-source-map-filename` | The output filename for the SourceMap | string | [name].map or [outputFilename].map -`--build-delimiter` | Display custom text after build output | string | Default string is null. You could provide a string such as `=== Build done ===` - - -#### Example Usage - -```bash -webpack index=./src/index.js index2=./src/index2.js --output-path='./dist' --output-filename='[name][hash].bundle.js' - -| Asset | Size | Chunks | Chunk Names | -|--------------------------------------|---------|-------------|---------------| -| index2740fdca26e9348bedbec.bundle.js | 2.6 kB | 0 [emitted] | index2 | -| index740fdca26e9348bedbec.bundle.js | 2.59 kB | 1 [emitted] | index | - [0] ./src/others.js 29 bytes {0} {1} [built] - [1] ./src/index.js 51 bytes {1} [built] - [2] ./src/index2.js 54 bytes {0} [built] -``` - -```bash -webpack.js index=./src/index.js index2=./src/index2.js --output-path='./dist' --output-filename='[name][hash].bundle.js' --devtool source-map --output-source-map-filename='[name]123.map' - -| Asset | Size | Chunks | Chunk Names | -|--------------------------------------|---------|-------------|---------------| -| index2740fdca26e9348bedbec.bundle.js | 2.76 kB | 0 [emitted] | index2 | -| index740fdca26e9348bedbec.bundle.js | 2.74 kB | 1 [emitted] | index | -| index2123.map | 2.95 kB | 0 [emitted] | index2 | -| index123.map | 2.95 kB | 1 [emitted] | index | - [0] ./src/others.js 29 bytes {0} {1} [built] - [1] ./src/index.js 51 bytes {1} [built] - [2] ./src/index2.js 54 bytes {0} [built] -``` - - -### Debug Options - -This set of options allows you to better debug the application containing assets compiled with webpack - -Parameter | Explanation | Input type | Default value ------------- | ------------------------------------------------ | ---------- | ------------- -`--debug` | Switch loaders to debug mode | boolean | false -`--devtool` | Define [source map type](/configuration/devtool/) for the bundled resources | string | - -`--progress` | Print compilation progress in percentage | boolean | false -`--display-error-details` | Display details about errors | boolean | false - -### Module Options - -These options allow you to bind [modules](/configuration/module/) as allowed by webpack - -Parameter | Explanation | Usage --------------------- | -------------------------------------- | ---------------- -`--module-bind` | Bind a file extension to a loader | `--module-bind js=babel-loader` -`--module-bind-post` | Bind a file extension to a post loader | -`--module-bind-pre` | Bind a file extension to a pre loader | - - -### Watch Options - -These options make the build [watch](/configuration/watch/) for changes in files of the dependency graph and perform the build again. - -Parameter | Explanation -------------------------- | ---------------------- -`--watch`, `-w` | Watch the filesystem for changes -`--watch-aggregate-timeout` | Timeout for gathering changes while watching -`--watch-poll` | The polling interval for watching (also enable polling) -`--watch-stdin`, `--stdin` | Exit the process when stdin is closed - - -### Optimize Options - -These options allow you to manipulate optimisations for a production build using webpack - -Parameter | Explanation | Plugin Used ---------------------------- | -------------------------------------------------------|---------------------- -`--optimize-max-chunks` | Try to keep the chunk count below a limit | [LimitChunkCountPlugin](/plugins/limit-chunk-count-plugin) -`--optimize-min-chunk-size` | Try to keep the chunk size above a limit | [MinChunkSizePlugin](/plugins/min-chunk-size-plugin) -`--optimize-minimize` | Minimize javascript and switches loaders to minimizing | [TerserPlugin](/plugins/terser-webpack-plugin/) & [LoaderOptionsPlugin](/plugins/loader-options-plugin/) - - -### Resolve Options - -These allow you to configure the webpack [resolver](/configuration/resolve/) with aliases and extensions. - -Parameter | Explanation | Example ----------------------- | ------------------------------------------------------- | ------------- -`--resolve-alias` | Setup a module alias for resolving | --resolve-alias jquery-plugin=jquery.plugin -`--resolve-extensions` | Setup extensions that should be used to resolve modules | --resolve-extensions .es6 .js .ts -`--resolve-loader-alias` | Minimize javascript and switches loaders to minimizing | - - -### Stats Options - -These options allow webpack to display various [stats](/configuration/stats/) and style them differently in the console output. - -Parameter | Explanation | Type --------------------------------- | ------------------------------------------------------------------ | ------- -`--color`, `--colors` | Force colors on the console [default: enabled for TTY output only] | boolean -`--no-color`, `--no-colors` | Force no colors on the console | boolean -`--display` | Select [display preset](/configuration/stats) (verbose, detailed, normal, minimal, errors-only, none; since webpack 3.0.0) | string -`--display-cached` | Display also cached modules in the output | boolean -`--display-cached-assets` | Display also cached assets in the output | boolean -`--display-chunks` | Display chunks in the output | boolean -`--display-depth` | Display distance from entry point for each module | boolean -`--display-entrypoints` | Display entry points in the output | boolean -`--display-error-details` | Display details about errors | boolean -`--display-exclude` | Exclude modules in the output | boolean -`--display-max-modules` | Sets the maximum number of visible modules in output | number -`--display-modules` | Display even excluded modules in the output | boolean -`--display-optimization-bailout` | Scope hoisting fallback trigger (since webpack 3.0.0) | boolean -`--display-origins` | Display origins of chunks in the output | boolean -`--display-provided-exports` | Display information about exports provided from modules | boolean -`--display-reasons` | Display reasons about module inclusion in the output | boolean -`--display-used-exports` | Display information about used exports in modules (Tree Shaking) | boolean -`--hide-modules` | Hides info about modules | boolean -`--sort-assets-by` | Sorts the assets list by property in asset | string -`--sort-chunks-by` | Sorts the chunks list by property in chunk | string -`--sort-modules-by` | Sorts the modules list by property in module | string -`--verbose` | Show more details | boolean - - -### Advanced Options - -Parameter | Explanation | Usage ------------------ | ---------------------------------------- | ----- -`--bail` | Abort the compilation on first error | -`--cache` | Enable in memory caching [Enabled by default for watch] | `--cache=false` -`--define` | Define any free variable, see [shimming](/guides/shimming) | `--define process.env.NODE_ENV="'development'"` -`--hot` | Enables [Hot Module Replacement](/concepts/hot-module-replacement) | `--hot=true` -`--labeled-modules` | Enables labeled modules [Uses LabeledModulesPlugin] | -`--plugin` | Load this [plugin](/configuration/plugins/) | -`--prefetch` | Prefetch the particular file | `--prefetch=./files.js` -`--provide` | Provide these modules as globals, see [shimming](/guides/shimming) | `--provide jQuery=jquery` -`--records-input-path` | Path to the records file (reading) | -`--records-output-path` | Path to the records file (writing) | -`--records-path` | Path to the records file | -`--target` | The [targeted](/configuration/target/) execution environment | `--target='node'` - -### Shortcuts - -Shortcut | Replaces ----------|---------------------------- --d | `--debug --devtool cheap-module-eval-source-map --output-pathinfo` --p | `--optimize-minimize --define process.env.NODE_ENV="production"`, see [building for production](/guides/production) - -### Profiling - -The `--profile` option captures timing information for each step of the compilation and includes this in the output. - -```bash -webpack --profile - -⋮ -[0] ./src/index.js 90 bytes {0} [built] - factory:22ms building:16ms = 38ms -``` - -For each module, the following details are included in the output as applicable: - -- `factory`: time to collect module metadata (e.g. resolving the filename) -- `building`: time to build the module (e.g. loaders and parsing) -- `dependencies`: time to identify and connect the module’s dependencies - -Paired with `--progress`, `--profile` gives you an in-depth idea of which step in the compilation is taking how long. This can help you optimise your build in a more informed manner. - -```bash -webpack --progress --profile - -30ms building modules -1ms sealing -1ms optimizing -0ms basic module optimization -1ms module optimization -1ms advanced module optimization -0ms basic chunk optimization -0ms chunk optimization -1ms advanced chunk optimization -0ms module and chunk tree optimization -1ms module reviving -0ms module order optimization -1ms module id optimization -1ms chunk reviving -0ms chunk order optimization -1ms chunk id optimization -10ms hashing -0ms module assets processing -13ms chunk assets processing -1ms additional chunk assets processing -0ms recording -0ms additional asset processing -26ms chunk asset optimization -1ms asset optimization -6ms emitting -⋮ -``` +--- +title: Command Line Interface +sort: 2 +contributors: + - evenstensberg + - simon04 + - tbroadley + - chenxsan + - rencire + - madhavarshney + - EugeneHlushko + - byzyk + - wizardofhogwarts + - EslamHiko +related: + - title: Analyzing Build Statistics + url: https://survivejs.com/webpack/optimizing-build/analyzing-build-statistics/ + - title: Three simple ways to inspect a webpack bundle + url: https://medium.com/@joeclever/three-simple-ways-to-inspect-a-webpack-bundle-7f6a8fe7195d#.7d2i06mjx + - title: Optimising your application bundle size with webpack + url: https://hackernoon.com/optimising-your-application-bundle-size-with-webpack-e85b00bab579#.5w5ko08pq + - title: Analyzing & optimizing your webpack bundle + url: https://medium.com/@ahmedelgabri/analyzing-optimizing-your-webpack-bundle-8590818af4df#.hce4vdjs9 + - title: Analysing and minimising the size of client side bundle with webpack and source-map-explorer + url: https://medium.com/@nimgrg/analysing-and-minimising-the-size-of-client-side-bundle-with-webpack-and-source-map-explorer-41096559beca#.c3t2srr8x +--- + +For proper usage and easy distribution of this configuration, webpack can be configured with `webpack.config.js`. Any parameters sent to the CLI will map to a corresponding parameter in the config file. + +Read the [installation guide](/guides/installation) if you don't already have webpack and CLI installed. + + +## Usage with config file + +```bash +webpack [--config webpack.config.js] +``` + +See [configuration](/configuration) for the options in the configuration file. + + +## Usage without config file + +```sh +webpack [] -o +``` + +__``__ + +A filename or a set of named filenames which act as the entry point to build your project. You can pass multiple entries (every entry is loaded on startup). If you pass a pair in the form `=` you can create an additional entry point. It will be mapped to the configuration option `entry`. + +__``__ + +A path and filename for the bundled file to be saved in. It will be mapped to the configuration options `output.path` and `output.filename`. + +__Example__ + +If your project structure is as follows - + +```bash +. +├── dist +├── index.html +└── src + ├── index.js + ├── index2.js + └── others.js +``` + +```bash +webpack src/index.js -o dist/bundle.js +``` + +This will bundle your source code with entry as `index.js` and the output bundle file will have a path of `dist` and the filename will be `bundle.js` + +```bash + | Asset | Size | Chunks | Chunk Names | + |-----------|---------|-------------|-------------| + | bundle.js | 1.54 kB | 0 [emitted] | index | + [0] ./src/index.js 51 bytes {0} [built] + [1] ./src/others.js 29 bytes {0} [built] +``` + +```bash +webpack index=./src/index.js entry2=./src/index2.js dist/bundle.js +``` + +This will form the bundle with both the files as separate entry points. + +```bash + | Asset | Size | Chunks | Chunk Names | + |-----------|---------|---------------|---------------| + | bundle.js | 1.55 kB | 0,1 [emitted] | index, entry2 | + [0] ./src/index.js 51 bytes {0} [built] + [0] ./src/index2.js 54 bytes {1} [built] + [1] ./src/others.js 29 bytes {0} {1} [built] +``` + + +### Common Options + +W> Note that Command Line Interface has a higher precedence for the arguments you use it with than your configuration file. For instance, if you pass [`--mode="production"`](/configuration/mode/#usage) to webpack CLI and your configuration file uses `development`, `production` will be used. + +__List all of the options available on the cli__ + +```bash +webpack --help +webpack -h +``` + +__Build source using a config file__ + +Specifies a different [configuration](/configuration) file to pick up. Use this if you want to specify something different from `webpack.config.js`, which is the default. + +```bash +webpack --config example.config.js +``` + +__Print result of webpack as a JSON__ + +```bash +webpack --json +webpack --json > stats.json +``` + +In every other case, webpack prints out a set of stats showing bundle, chunk and timing details. Using this option the output can be a JSON object. This response is accepted by webpack's [analyse tool](https://webpack.github.io/analyse/), or chrisbateman's [webpack-visualizer](https://chrisbateman.github.io/webpack-visualizer/), or th0r's [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer). The analyse tool will take in the JSON and provide all the details of the build in graphical form. + +### Environment Options + +When the webpack configuration [exports a function](/configuration/configuration-types#exporting-a-function), an "environment" may be passed to it. + +```bash +webpack --env.production # sets env.production == true +webpack --env.platform=web # sets env.platform == "web" +``` + +The `--env` argument accepts various syntaxes: + +Invocation | Resulting environment +---------------------------------------- | --------------------------- +`webpack --env prod` | `"prod"` +`webpack --env.prod` | `{ prod: true }` +`webpack --env.prod=1` | `{ prod: 1 }` +`webpack --env.prod=foo` | `{ prod: "foo" }` +`webpack --env.prod --env.min` | `{ prod: true, min: true }` +`webpack --env.prod --env min` | `[{ prod: true }, "min"]` +`webpack --env.prod=foo --env.prod=bar` | `{prod: [ "foo", "bar" ]}` + +T> See the [environment variables](/guides/environment-variables) guide for more information on its usage. + +### Config Options + +Parameter | Explanation | Input type | Default +------------------------- | ------------------------------------------- | ---------- | ------------------ +`--config` | Path to the config file | string | webpack.config.js or webpackfile.js +`--config-register, -r` | Preload one or more modules before loading the webpack configuration | array | +`--config-name` | Name of the config to use | string | +`--env` | Environment passed to the config, when it is a function | | +`--mode` | Mode to use, either "development" or "production" | string | + +### Output Options + +This set of options allows you to manipulate certain [output](/configuration/output) parameters of your build. + +Parameter | Explanation | Input type | Default +------------------------- | ------------------------------------------- | ---------- | ------------------ +`--output-chunk-filename` | The output filename for additional chunks | string | filename with [id] instead of [name] or [id] prefixed +`--output-filename` | The output filename of the bundle | string | [name].js +`--output-jsonp-function` | The name of the JSONP function used for chunk loading | string | webpackJsonp +`--output-library` | Expose the exports of the entry point as library | string | +`--output-library-target` | The type for exposing the exports of the entry point as library | string | var +`--output-path` | The output path for compilation assets | string | Current directory +`--output-pathinfo` | Include a comment with the request for every dependency | boolean | false +`--output-public-path` | The public path for the assets | string | / +`--output-source-map-filename` | The output filename for the SourceMap | string | [name].map or [outputFilename].map +`--build-delimiter` | Display custom text after build output | string | Default string is null. You could provide a string such as `=== Build done ===` + + +#### Example Usage + +```bash +webpack index=./src/index.js index2=./src/index2.js --output-path='./dist' --output-filename='[name][hash].bundle.js' + +| Asset | Size | Chunks | Chunk Names | +|--------------------------------------|---------|-------------|---------------| +| index2740fdca26e9348bedbec.bundle.js | 2.6 kB | 0 [emitted] | index2 | +| index740fdca26e9348bedbec.bundle.js | 2.59 kB | 1 [emitted] | index | + [0] ./src/others.js 29 bytes {0} {1} [built] + [1] ./src/index.js 51 bytes {1} [built] + [2] ./src/index2.js 54 bytes {0} [built] +``` + +```bash +webpack.js index=./src/index.js index2=./src/index2.js --output-path='./dist' --output-filename='[name][hash].bundle.js' --devtool source-map --output-source-map-filename='[name]123.map' + +| Asset | Size | Chunks | Chunk Names | +|--------------------------------------|---------|-------------|---------------| +| index2740fdca26e9348bedbec.bundle.js | 2.76 kB | 0 [emitted] | index2 | +| index740fdca26e9348bedbec.bundle.js | 2.74 kB | 1 [emitted] | index | +| index2123.map | 2.95 kB | 0 [emitted] | index2 | +| index123.map | 2.95 kB | 1 [emitted] | index | + [0] ./src/others.js 29 bytes {0} {1} [built] + [1] ./src/index.js 51 bytes {1} [built] + [2] ./src/index2.js 54 bytes {0} [built] +``` + + +### Debug Options + +This set of options allows you to better debug the application containing assets compiled with webpack + +Parameter | Explanation | Input type | Default value +------------ | ------------------------------------------------ | ---------- | ------------- +`--debug` | Switch loaders to debug mode | boolean | false +`--devtool` | Define [source map type](/configuration/devtool/) for the bundled resources | string | - +`--progress` | Print compilation progress in percentage | boolean | false +`--display-error-details` | Display details about errors | boolean | false + +### Module Options + +These options allow you to bind [modules](/configuration/module/) as allowed by webpack + +Parameter | Explanation | Usage +-------------------- | -------------------------------------- | ---------------- +`--module-bind` | Bind a file extension to a loader | `--module-bind js=babel-loader` +`--module-bind-post` | Bind a file extension to a post loader | +`--module-bind-pre` | Bind a file extension to a pre loader | + + +### Watch Options + +These options make the build [watch](/configuration/watch/) for changes in files of the dependency graph and perform the build again. + +Parameter | Explanation +------------------------- | ---------------------- +`--watch`, `-w` | Watch the filesystem for changes +`--watch-aggregate-timeout` | Timeout for gathering changes while watching +`--watch-poll` | The polling interval for watching (also enable polling) +`--watch-stdin`, `--stdin` | Exit the process when stdin is closed + + +### Optimize Options + +These options allow you to manipulate optimisations for a production build using webpack + +Parameter | Explanation | Plugin Used +--------------------------- | -------------------------------------------------------|---------------------- +`--optimize-max-chunks` | Try to keep the chunk count below a limit | [LimitChunkCountPlugin](/plugins/limit-chunk-count-plugin) +`--optimize-min-chunk-size` | Try to keep the chunk size above a limit | [MinChunkSizePlugin](/plugins/min-chunk-size-plugin) +`--optimize-minimize` | Minimize javascript and switches loaders to minimizing | [TerserPlugin](/plugins/terser-webpack-plugin/) & [LoaderOptionsPlugin](/plugins/loader-options-plugin/) + + +### Resolve Options + +These allow you to configure the webpack [resolver](/configuration/resolve/) with aliases and extensions. + +Parameter | Explanation | Example +---------------------- | ------------------------------------------------------- | ------------- +`--resolve-alias` | Setup a module alias for resolving | --resolve-alias jquery-plugin=jquery.plugin +`--resolve-extensions` | Setup extensions that should be used to resolve modules | --resolve-extensions .es6 .js .ts +`--resolve-loader-alias` | Minimize javascript and switches loaders to minimizing | + + +### Stats Options + +These options allow webpack to display various [stats](/configuration/stats/) and style them differently in the console output. + +Parameter | Explanation | Type +-------------------------------- | ------------------------------------------------------------------ | ------- +`--color`, `--colors` | Force colors on the console [default: enabled for TTY output only] | boolean +`--no-color`, `--no-colors` | Force no colors on the console | boolean +`--display` | Select [display preset](/configuration/stats) (verbose, detailed, normal, minimal, errors-only, none; since webpack 3.0.0) | string +`--display-cached` | Display also cached modules in the output | boolean +`--display-cached-assets` | Display also cached assets in the output | boolean +`--display-chunks` | Display chunks in the output | boolean +`--display-depth` | Display distance from entry point for each module | boolean +`--display-entrypoints` | Display entry points in the output | boolean +`--display-error-details` | Display details about errors | boolean +`--display-exclude` | Exclude modules in the output | boolean +`--display-max-modules` | Sets the maximum number of visible modules in output | number +`--display-modules` | Display even excluded modules in the output | boolean +`--display-optimization-bailout` | Scope hoisting fallback trigger (since webpack 3.0.0) | boolean +`--display-origins` | Display origins of chunks in the output | boolean +`--display-provided-exports` | Display information about exports provided from modules | boolean +`--display-reasons` | Display reasons about module inclusion in the output | boolean +`--display-used-exports` | Display information about used exports in modules (Tree Shaking) | boolean +`--hide-modules` | Hides info about modules | boolean +`--sort-assets-by` | Sorts the assets list by property in asset | string +`--sort-chunks-by` | Sorts the chunks list by property in chunk | string +`--sort-modules-by` | Sorts the modules list by property in module | string +`--verbose` | Show more details | boolean + + +### Advanced Options + +Parameter | Explanation | Usage +----------------- | ---------------------------------------- | ----- +`--bail` | Abort the compilation on first error | +`--cache` | Enable in memory caching [Enabled by default for watch] | `--cache=false` +`--define` | Define any free variable, see [shimming](/guides/shimming) | `--define process.env.NODE_ENV="'development'"` +`--hot` | Enables [Hot Module Replacement](/concepts/hot-module-replacement) | `--hot=true` +`--labeled-modules` | Enables labeled modules [Uses LabeledModulesPlugin] | +`--live-reload` | Enables page live reloading | `--live-reload=true` +`--plugin` | Load this [plugin](/configuration/plugins/) | +`--prefetch` | Prefetch the particular file | `--prefetch=./files.js` +`--provide` | Provide these modules as globals, see [shimming](/guides/shimming) | `--provide jQuery=jquery` +`--records-input-path` | Path to the records file (reading) | +`--records-output-path` | Path to the records file (writing) | +`--records-path` | Path to the records file | +`--target` | The [targeted](/configuration/target/) execution environment | `--target='node'` + +### Shortcuts + +Shortcut | Replaces +---------|---------------------------- +-d | `--debug --devtool cheap-module-eval-source-map --output-pathinfo` +-p | `--optimize-minimize --define process.env.NODE_ENV="production"`, see [building for production](/guides/production) + +### Profiling + +The `--profile` option captures timing information for each step of the compilation and includes this in the output. + +```bash +webpack --profile + +⋮ +[0] ./src/index.js 90 bytes {0} [built] + factory:22ms building:16ms = 38ms +``` + +For each module, the following details are included in the output as applicable: + +- `factory`: time to collect module metadata (e.g. resolving the filename) +- `building`: time to build the module (e.g. loaders and parsing) +- `dependencies`: time to identify and connect the module’s dependencies + +Paired with `--progress`, `--profile` gives you an in-depth idea of which step in the compilation is taking how long. This can help you optimise your build in a more informed manner. + +```bash +webpack --progress --profile + +30ms building modules +1ms sealing +1ms optimizing +0ms basic module optimization +1ms module optimization +1ms advanced module optimization +0ms basic chunk optimization +0ms chunk optimization +1ms advanced chunk optimization +0ms module and chunk tree optimization +1ms module reviving +0ms module order optimization +1ms module id optimization +1ms chunk reviving +0ms chunk order optimization +1ms chunk id optimization +10ms hashing +0ms module assets processing +13ms chunk assets processing +1ms additional chunk assets processing +0ms recording +0ms additional asset processing +26ms chunk asset optimization +1ms asset optimization +6ms emitting +⋮ +``` diff --git a/src/content/configuration/dev-server.md b/src/content/configuration/dev-server.md index 1f1c1e9bfcfb..507723ed598f 100644 --- a/src/content/configuration/dev-server.md +++ b/src/content/configuration/dev-server.md @@ -1,1355 +1,1378 @@ ---- -title: DevServer -sort: 9 -contributors: - - sokra - - skipjack - - spacek33z - - charlespwd - - orteth01 - - byzyk - - EugeneHlushko - - Yiidiir - - Loonride - - dmohns - - EslamHiko ---- - -[webpack-dev-server](https://github.com/webpack/webpack-dev-server) can be used to quickly develop an application. See the [development guide](/guides/development/) to get started. - -This page describes the options that affect the behavior of webpack-dev-server (short: dev-server). - -T> Options that are compatible with [webpack-dev-middleware](https://github.com/webpack/webpack-dev-middleware) have 🔑 next to them. - - -## `devServer` - -`object` - -This set of options is picked up by [webpack-dev-server](https://github.com/webpack/webpack-dev-server) and can be used to change its behavior in various ways. Here's a simple example that gzips and serves everything from our `dist/` directory in the project root: - -__webpack.config.js__ - -```javascript -var path = require('path'); - -module.exports = { - //... - devServer: { - contentBase: path.join(__dirname, 'dist'), - compress: true, - port: 9000 - } -}; -``` - -When the server is started, there will be a message prior to the list of resolved modules: - -```bash -http://localhost:9000/ -webpack output is served from /build/ -Content not from webpack is served from /path/to/dist/ -``` - -that will give some background on where the server is located and what it's serving. - -If you're using dev-server through the Node.js API, the options in `devServer` will be ignored. Pass the options as a second parameter instead: `new WebpackDevServer(compiler, {...})`. [See here](https://github.com/webpack/webpack-dev-server/tree/master/examples/api/simple) for an example of how to use webpack-dev-server through the Node.js API. - -W> Be aware that when [exporting multiple configurations](/configuration/configuration-types/#exporting-multiple-configurations) only the `devServer` options for the first configuration will be taken into account and used for all the configurations in the array. - -T> If you're having trouble, navigating to the `/webpack-dev-server` route will show where files are served. For example, `http://localhost:9000/webpack-dev-server`. - -T> HTML template is required to serve the bundle, usually it is an `index.html` file. Make sure that script references are added into HTML, webpack-dev-server doesn't inject them automatically. - -## `devServer.after` - -`function (app, server)` - -Provides the ability to execute custom middleware after all other middleware -internally within the server. - -__webpack.config.js__ - -```javascript -module.exports = { - //... - devServer: { - after: function(app, server) { - // do fancy stuff - } - } -}; -``` - -## `devServer.allowedHosts` - -`array` - -This option allows you to whitelist services that are allowed to access the dev server. - -__webpack.config.js__ - -```javascript -module.exports = { - //... - devServer: { - allowedHosts: [ - 'host.com', - 'subdomain.host.com', - 'subdomain2.host.com', - 'host2.com' - ] - } -}; -``` - -Mimicking django's `ALLOWED_HOSTS`, a value beginning with `.` can be used as a subdomain wildcard. `.host.com` will match `host.com`, `www.host.com`, and any other subdomain of `host.com`. - -__webpack.config.js__ - -```javascript -module.exports = { - //... - devServer: { - // this achieves the same effect as the first example - // with the bonus of not having to update your config - // if new subdomains need to access the dev server - allowedHosts: [ - '.host.com', - 'host2.com' - ] - } -}; -``` - -To use this option with the CLI pass the `--allowed-hosts` option a comma-delimited string. - -```bash -webpack-dev-server --entry /entry/file --output-path /output/path --allowed-hosts .host.com,host2.com -``` - -## `devServer.before` - -`function (app, server)` - -Provides the ability to execute custom middleware prior to all other middleware -internally within the server. This could be used to define custom handlers, for -example: - -__webpack.config.js__ - -```javascript -module.exports = { - //... - devServer: { - before: function(app, server) { - app.get('/some/path', function(req, res) { - res.json({ custom: 'response' }); - }); - } - } -}; -``` - -## `devServer.bonjour` - -This option broadcasts the server via [ZeroConf](http://www.zeroconf.org/) networking on start - -__webpack.config.js__ - -```javascript -module.exports = { - //... - devServer: { - bonjour: true - } -}; -``` - -Usage via the CLI - -```bash -webpack-dev-server --bonjour -``` - - -## `devServer.clientLogLevel` - -`string: 'none' | 'info' | 'error' | 'warning'` - -When using _inline mode_, the console in your DevTools will show you messages e.g. before reloading, before an error or when [Hot Module Replacement](/concepts/hot-module-replacement/) is enabled. Defaults to `info`. - -`devServer.clientLogLevel` may be too verbose, you can turn logging off by setting it to `'none'`. - -__webpack.config.js__ - -```javascript -module.exports = { - //... - devServer: { - clientLogLevel: 'none' - } -}; -``` - -Usage via the CLI - -```bash -webpack-dev-server --client-log-level none -``` - -## `devServer.color` - CLI only - -`boolean` - -Enables/Disables colors on the console. - -```bash -webpack-dev-server --color -``` - - -## `devServer.compress` - -`boolean` - -Enable [gzip compression](https://betterexplained.com/articles/how-to-optimize-your-site-with-gzip-compression/) for everything served: - -__webpack.config.js__ - -```javascript -module.exports = { - //... - devServer: { - compress: true - } -}; -``` - -Usage via the CLI - -```bash -webpack-dev-server --compress -``` - - -## `devServer.contentBase` - -`boolean: false` `string` `[string]` `number` - -Tell the server where to serve content from. This is only necessary if you want to serve static files. [`devServer.publicPath`](#devserverpublicpath-) will be used to determine where the bundles should be served from, and takes precedence. - -T> It is recommended to use an absolute path. - -By default it will use your current working directory to serve content. To disable `contentBase` set it to `false`. - -__webpack.config.js__ - -```javascript -module.exports = { - //... - devServer: { - contentBase: path.join(__dirname, 'public') - } -}; -``` - -It is also possible to serve from multiple directories: - -__webpack.config.js__ - -```javascript -module.exports = { - //... - devServer: { - contentBase: [path.join(__dirname, 'public'), path.join(__dirname, 'assets')] - } -}; -``` - -Usage via the CLI - -```bash -webpack-dev-server --content-base /path/to/content/dir -``` - - -## `devServer.disableHostCheck` - -`boolean` - -When set to `true` this option bypasses host checking. __THIS IS NOT RECOMMENDED__ as apps that do not check the host are vulnerable to DNS rebinding attacks. - -__webpack.config.js__ - -```javascript -module.exports = { - //... - devServer: { - disableHostCheck: true - } -}; -``` - -Usage via the CLI - -```bash -webpack-dev-server --disable-host-check -``` - - -## `devServer.filename` 🔑 - -`string` - -This option lets you reduce the compilations in [lazy mode](#devserver-lazy-). -By default in [lazy mode](#devserver-lazy-), every request results in a new compilation. With `filename`, it's possible to only compile when a certain file is requested. - -If [`output.filename`](/configuration/output/#output-filename) is set to `'bundle.js'` and `devServer.filename` is used like this: - -__webpack.config.js__ - -```javascript -module.exports = { - //... - output: { - filename: 'bundle.js' - }, - devServer: { - lazy: true, - filename: 'bundle.js' - } -}; -``` - -It will now only compile the bundle when `/bundle.js` is requested. - -T> `filename` has no effect when used without [lazy mode](#devserver-lazy-). - - -## `devServer.headers` 🔑 - -`object` - -Adds headers to all responses: - -__webpack.config.js__ - -```javascript -module.exports = { - //... - devServer: { - headers: { - 'X-Custom-Foo': 'bar' - } - } -}; -``` - - -## `devServer.historyApiFallback` - -`boolean` `object` - -When using the [HTML5 History API](https://developer.mozilla.org/en-US/docs/Web/API/History), the `index.html` page will likely have to be served in place of any `404` responses. `devServer.historyApiFallback` is disabled by default. Enable it by passing: - -__webpack.config.js__ - -```javascript -module.exports = { - //... - devServer: { - historyApiFallback: true - } -}; -``` - -By passing an object this behavior can be controlled further using options like `rewrites`: - -__webpack.config.js__ - -```javascript -module.exports = { - //... - devServer: { - historyApiFallback: { - rewrites: [ - { from: /^\/$/, to: '/views/landing.html' }, - { from: /^\/subpage/, to: '/views/subpage.html' }, - { from: /./, to: '/views/404.html' } - ] - } - } -}; -``` - -When using dots in your path (common with Angular), you may need to use the `disableDotRule`: - -__webpack.config.js__ - -```javascript -module.exports = { - //... - devServer: { - historyApiFallback: { - disableDotRule: true - } - } -}; -``` - -Usage via the CLI - -```bash -webpack-dev-server --history-api-fallback -``` - -For more options and information, see the [connect-history-api-fallback](https://github.com/bripkens/connect-history-api-fallback) documentation. - - -## `devServer.host` - -`string` - -Specify a host to use. By default this is `localhost`. If you want your server to be accessible externally, specify it like this: - -__webpack.config.js__ - -```javascript -module.exports = { - //... - devServer: { - host: '0.0.0.0' - } -}; -``` - -Usage via the CLI - -```bash -webpack-dev-server --host 0.0.0.0 -``` - - -## `devServer.hot` - -`boolean` - -Enable webpack's [Hot Module Replacement](/concepts/hot-module-replacement/) feature: - -__webpack.config.js__ - -```javascript -module.exports = { - //... - devServer: { - hot: true - } -}; -``` - -T> Note that [`webpack.HotModuleReplacementPlugin`](/plugins/hot-module-replacement-plugin/) is required to fully enable HMR. If `webpack` or `webpack-dev-server` are launched with the `--hot` option, this plugin will be added automatically, so you may not need to add this to your `webpack.config.js`. See the [HMR concepts page](/concepts/hot-module-replacement/) for more information. - - -## `devServer.hotOnly` - -`boolean` - -Enables Hot Module Replacement (see [`devServer.hot`](#devserverhot)) without page refresh as fallback in case of build failures. - -__webpack.config.js__ - -```javascript -module.exports = { - //... - devServer: { - hotOnly: true - } -}; -``` - -Usage via the CLI - -```bash -webpack-dev-server --hot-only -``` - - -## `devServer.http2` - -`boolean: false` - -Serve over HTTP/2 using [spdy](https://www.npmjs.com/package/spdy). This option is ignored for Node 10.0.0 and above, as spdy is broken for those versions. The dev server will migrate over to Node's built-in HTTP/2 once [Express](https://expressjs.com/) supports it. - -If `devServer.http2` is not explicitly set to `false`, it will default to `true` when [`devServer.https`](#devserverhttps) is enabled. When `devServer.http2` is enabled but the server is unable to serve over HTTP/2, the server defaults to HTTPS. - -HTTP/2 with a self-signed certificate: - -__webpack.config.js__ - -```javascript -module.exports = { - //... - devServer: { - http2: true - } -}; -``` - -Provide your own certificate using the [https](#devserverhttps) option: - -__webpack.config.js__ - -```javascript -module.exports = { - //... - devServer: { - http2: true, - https: { - key: fs.readFileSync('/path/to/server.key'), - cert: fs.readFileSync('/path/to/server.crt'), - ca: fs.readFileSync('/path/to/ca.pem'), - } - } -}; -``` - -Usage via CLI - -```bash -webpack-dev-server --http2 -``` - -To pass your own certificate via CLI, use the following options - -```bash -webpack-dev-server --http2 --key /path/to/server.key --cert /path/to/server.crt --cacert /path/to/ca.pem -``` - - -## `devServer.https` - -`boolean` `object` - -By default dev-server will be served over HTTP. It can optionally be served over HTTP/2 with HTTPS: - -__webpack.config.js__ - -```javascript -module.exports = { - //... - devServer: { - https: true - } -}; -``` - -With the above setting a self-signed certificate is used, but you can provide your own: - -__webpack.config.js__ - -```javascript -module.exports = { - //... - devServer: { - https: { - key: fs.readFileSync('/path/to/server.key'), - cert: fs.readFileSync('/path/to/server.crt'), - ca: fs.readFileSync('/path/to/ca.pem'), - } - } -}; -``` - -This object is passed straight to Node.js HTTPS module, so see the [HTTPS documentation](https://nodejs.org/api/https.html) for more information. - -Usage via the CLI - -```bash -webpack-dev-server --https -``` - -To pass your own certificate via the CLI use the following options - -```bash -webpack-dev-server --https --key /path/to/server.key --cert /path/to/server.crt --cacert /path/to/ca.pem -``` - -## `devServer.index` - -`string` - -The filename that is considered the index file. - -__webpack.config.js__ - -```javascript -module.exports = { - //... - devServer: { - index: 'index.html' - } -}; -``` - - -## `devServer.info` - CLI only - -`boolean` - -Output cli information. It is enabled by default. - -```bash -webpack-dev-server --info=false -``` - - -## `devServer.inline` - -`boolean` - -Toggle between the dev-server's two different modes. By default the application will be served with _inline mode_ enabled. This means that a script will be inserted in your bundle to take care of live reloading, and build messages will appear in the browser console. - -It is also possible to use __iframe mode__, which uses an `