diff --git a/src/content/api/cli.md b/src/content/api/cli.md index b3bb38ba5fc0..8211d26e372b 100644 --- a/src/content/api/cli.md +++ b/src/content/api/cli.md @@ -2,6 +2,7 @@ title: Command Line Interface sort: 1 contributors: + - anshumanv - evenstensberg - simon04 - tbroadley @@ -31,8 +32,74 @@ For proper usage and easy distribution of this configuration, webpack can be con Read the [installation guide](/guides/installation) if you don't already have webpack and CLI installed. +## Commands + +webpack-cli offers a variety of commands to make working with webpack easy. By default webpack ships with + +| Command | Alias | Description | +| --------- | ----- | ------------------------------------------------------ | +| `init` | c | Initialize a new webpack configuration | +| `migrate` | m | Migrate a configuration to a new version | +| `loader` | l | Scaffold a loader repository | +| `plugin` | p | Scaffold a plugin repository | +| `info` | i | Outputs information about your system and dependencies | +| `serve` | s | Run the webpack Dev Server | + +## Flags + +webpack-cli offers a variety of commands to make working with webpack easy. By default webpack ships with the following flags: + +Note: These are the flags with webpack v4, starting v5 CLI also supports [core flags](/api/cli/#core-flags) + +| Flag / Alias | Type | Description | +| ------------------- | --------------- | -------------------------------------------------------------------------------------------------------------- | +| `--entry` | string[] | The entry point(s) of your application e.g. `./src/main.js` | +| `--config, -c` | string[] | Provide path to a webpack configuration file e.g. `./webpack.config.js` | +| `--config-name` | string[] | Name of the configuration to use | +| `--name` | string[] | Name of the configuration. Used when loading multiple configurations | +| `--color` | boolean | Enable colors on console | +| `--no-color` | boolean | Disables colors on console | +| `--merge, -m` | boolean | Merge two or more configurations using webpack-merge e.g. `-c ./webpack.config.js -c ./webpack.test.config.js` | +| `--env` | string[] | Environment passed to the configuration when it is a function | +| `--progress` | boolean | Print compilation progress during build | +| `--help` | boolean | Outputs list of supported flags and commands | +| `--output-path, -o` | string | Output location of the file generated by webpack e.g. `./dist` | +| `--target, -t` | string | Sets the build target | +| `--watch, -w` | boolean | Watch for file changes | +| `--hot, -h` | boolean | Enables Hot Module Replacement | +| `--no-hot` | boolean | Disables Hot Module Replacement | +| `--devtool, -d` | string | Controls if and how source maps are generated. | +| `--prefetch` | string | Prefetch this request | +| `--json, -j` | boolean, string | Prints result as JSON or store it in a file | +| `--mode` | string | Defines the mode to pass to webpack | +| `--version, -v` | boolean | Get current version | +| `--stats` | boolean, string | It instructs webpack on how to treat the stats | +| `--no-stats` | boolean | Disables stats output | +| `--analyze` | boolean | It invokes `webpack-bundle-analyzer` plugin to get bundle information | + +### Negated Flags + +| Flag | Description | +| ---------- | ------------------------------------------------------------- | +| --no-color | Disabled any color on the console | +| --no-hot | Disabled hot reloading if you have it enabled via your config | +| --no-stats | Disables any compilation stats emitted by webpack | + +### Core Flags + +Starting CLI v4 and webpack v5, CLI imports the entire configuration schema from webpack core to allow tuning almost every configuration option from the command line. + +__Here's the list of all the core flags supported by webpack v5 with CLI v4 - [link](https://github.com/webpack/webpack-cli/tree/next/packages/webpack-cli#webpack-5)__ + +For example if you want to enable performance hints in your project you'd use [this](https://webpack.js.org/configuration/performance/#performancehints) option in configuration, with core flags you can do - -## Usage with configuration file +```bash +webpack --performance-hints warning` +``` + +## Usage + +### With configuration file ```bash webpack [--config webpack.config.js] @@ -40,11 +107,16 @@ webpack [--config webpack.config.js] See [configuration](/configuration) for the options in the configuration file. +### Without configuration file -## Usage without configuration file +```sh +webpack [] -o +``` + +__example__ ```sh -webpack [] -o +webpack --entry ./first.js --entry ./second.js --output-path /build ``` __``__ @@ -53,7 +125,7 @@ A filename or a set of named filenames which act as the entry point to build you __``__ -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`. +A path for the bundled file to be saved in. It will be mapped to the configuration options `output.path`. __Example__ @@ -70,49 +142,79 @@ If your project structure is as follows - ``` ```bash -webpack src/index.js -o dist/bundle.js +webpack ./src/index.js -o dist ``` -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` +This will bundle your source code with entry as `index.js`, and the output bundle file will have a path of `dist`. ```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] +asset main.js 142 bytes [compared for emit] [minimized] (name: main) +./src/index.js 30 bytes [built] [code generated] +./src/others.js 1 bytes [built] [code generated] +webpack 5.1.0 compiled successfully in 187 ms ``` ```bash -webpack ./src/index.js ./src.index2.js -o dist/bundle.js +webpack ./src/index.js ./src/others2.js -o dist/ ``` 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, index2 | - [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] +asset main.js 142 bytes [compared for emit] [minimized] (name: main) +./src/index.js 30 bytes [built] [code generated] +./src/others2.js 1 bytes [built] [code generated] +./src/others.js 1 bytes [built] [code generated] +webpack 5.1.0 compiled successfully in 198 ms ``` +## Default Configurations + +CLI will look for some default configurations in the path of your project, here are the config files picked up by CLI. + +If no `mode` is supplied via flags or config then this is the lookup order in increasing order -### Common Options +> example - config file lookup will be in order of .webpack/webpack.config.development.js > webpack.config.development.js > webpack.config.js + +```md +'webpack.config', +'webpack.config.dev', +'webpack.config.development', +'webpack.config.prod', +'webpack.config.production', +'.webpack/webpack.config', +'.webpack/webpack.config.none', +'.webpack/webpack.config.dev', +'.webpack/webpack.config.development', +'.webpack/webpack.config.prod', +'.webpack/webpack.config.production', +'.webpack/webpackfile', +``` + +If `mode` is supplied, say `production` then config looking order will be - + +`.webpack/webpack.config.production.* > .webpack/webpack.config.prod.* > webpack.config.production.* > webpack.config.prod.* > webpack.config.*` + +## 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__ +__List all of the commands and flags available on the cli__ ```bash webpack --help -webpack -h +``` + +__Show help for a single command or flag__ + +```bash +webpack --help +webpack --help -- ``` __Build source using a configuration 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. +Specifies a different [configuration](/configuration) file to pick up. Use this if you want to specify something different from `webpack.config.js`, which is one of the default. ```bash webpack --config example.config.js @@ -122,265 +224,64 @@ __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. +__If you want to store stats as json instead of printing it, you can use -__ ```bash -webpack --env.production # sets env.production == true -webpack --env.platform=web # sets env.platform == "web" +webpack --json stats.json ``` -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. - -### Configuration Options - -Parameter | Explanation | Input type | Default -------------------------- | ------------------------------------------- | ---------- | ------------------ -`--config` | Path to the configuration 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 configuration to use | string | -`--env` | Environment passed to the configuration, when it is a function | | -`--mode` | Mode to use | string | `'production'` - -### 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 ===` - +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. -#### Example Usage +## Environment Options -```bash -webpack index=./src/index.js index2=./src/index2.js --output-path='./dist' --output-filename='[name][fullhash].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] -``` +When the webpack configuration [exports a function](/configuration/configuration-types/#exporting-a-function), an "environment" may be passed to it. ```bash -webpack.js index=./src/index.js index2=./src/index2.js --output-path='./dist' --output-filename='[name][fullhash].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] +webpack --env production # sets env.production == true ``` +The `--env` argument accepts multiple values: -### 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 optimizations 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/) - - -### Resolve Options - -These allow you to configure the webpack [resolver](/configuration/resolve/) with aliases and extensions. +| Invocation | Resulting environment | +| ------------------------------ | --------------------------- | +| `webpack --env prod` | `{ prod: true }` | +| `webpack --env prod --env min` | `{ prod: true, min: true }` | -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` | Set 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` | Hide info about modules | `boolean` -`--sort-assets-by` | Sort the assets list by property in asset | `string` -`--sort-chunks-by` | Sort the chunks list by property in chunk | `string` -`--sort-modules-by` | Sort 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 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 +T> See the [environment variables](/guides/environment-variables/) guide for more information on its usage. -Shortcut | Replaces ----------|---------------------------- --d | `--debug --devtool cheap-module-eval-source-map --output-pathinfo` --p | `--mode production`, see [building for production](/guides/production/) +## Configuration Options -### Profiling +| Parameter | Explanation | Input type | Default | +| --------------- | -------------------------------------------------------------- | ---------- | --------------------------------------------------- | +| `--config` | Path to the configuration file | string | [Default Configs](/api/cli/#default-configurations) | +| `--config-name` | Name of the configuration to use | string | +| `--env` | Environment passed to the configuration, when it is a function | | +| `--mode` | Mode to use | string | `'production'` | -The `--profile` option captures timing information for each step of the compilation and includes this in the output. +## Analyzing Bundle -```bash -webpack --profile +You can also use `webpack-bundle-analyzer` to analyze your output bundles emitted by webpack. You can use `--analyze` flag to invoke it via CLI. -⋮ -[0] ./src/index.js 90 bytes {0} [built] - factory:22ms building:16ms = 38ms +```sh +webpack --analyze ``` -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 optimize 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 -⋮ -``` +W> Make sure you have `webpack-bundle-analyzer` installed in your project else CLI will prompt you to install it. ## Pass CLI arguments to Node.js -To pass arguments directly to Node.js process, you can use the `--node-args` option. All other flags and options will be received by the webpack-cli. +To pass arguments directly to Node.js process, you can use the `NODE_OPTIONS` option. For example, to increase the memory limit of Node.js process to 4 GB ```bash -webpack --node-args="--max-old-space-size=4096" +NODE_OPTIONS="--max-old-space-size=4096" webpack ``` Also, you can pass multiple options to Node.js process ```bash -webpack --node-args="--max-old-space-size=4096" --node-args="-r /path/to/preload/file.js" +NODE_OPTIONS="--max-old-space-size=4096 -r /path/to/preload/file.js" webpack ```