Using the Command Line

Almost everything you do with webpack goes through webpack-cli. It finds your configuration, loads webpack, runs the build, and prints the result. This guide covers what it does by default and how to steer it; the pages that follow go deeper on running builds, passing environments, scaffolding projects, and inspecting output.

npm install --save-dev webpack webpack-cli

Install it locally, per project, so that the version of the CLI is pinned alongside the version of webpack it drives. Run it through npx, or from an npm script where it is already on the path:

{
  "scripts": {
    "build": "webpack",
    "dev": "webpack serve"
  }
}

The CLI works with no configuration at all. Given a src/index.js, this bundles it to dist/main.js:

npx webpack

That is the build command running implicitly. Everything else the CLI offers is a matter of pointing it at a different configuration, a different entry, or a different kind of run.

Every command takes entries positionally and options as flags:

npx webpack build --config ./webpack.config.js --stats verbose

Scaffolding a new project, loader, or plugin is handled by a separate package, create-webpack-app.

If you don't pass --config, the CLI looks for a configuration file in this order and uses the first one it finds:

webpack.config
.webpack/webpack.config
.webpack/webpackfile

Each base name is tried with a set of extensions, and the common JavaScript and TypeScript ones win over the rest:

1. .js, .mjs, .cjs, .ts, .cts, .mts
2. Everything interpret knows about, such as .coffee
3. The data formats .json5, .yaml, .yml, and .toml (webpack-cli 7.1.0 and later)

So a project with both webpack.config.js and .webpack/webpack.config.ts uses the first one. If no configuration file exists at all, webpack falls back to its defaults.

Anything you pass on the command line takes precedence over the same setting in your configuration file. Running the following against a configuration whose mode is 'development' produces a production build:

npx webpack --mode production

This is what makes a single configuration file usable across environments: keep the shared setup in the file, and override the parts that differ per invocation.

Beyond the CLI's own flags, webpack-cli derives a flag for nearly every option in webpack's configuration schema. So an option you would normally write as performance.hints:

export default {
  performance: {
    hints: 'warning',
  },
};

can equally be passed as:

npx webpack --performance-hints warning

Because these are generated from the schema, they track whatever version of webpack you have installed. Run npx webpack --help=verbose to see the full list for your version.

Boolean options have a --no- counterpart that turns off something your configuration enables:

Both forms work, and either one accepts a command or an option to narrow the output:

npx webpack --help
npx webpack help

The default help lists the commands and the most commonly used flags. To see every flag the installed version of webpack supports, including the schema-derived core flags:

npx webpack --help=verbose

To read about one option in particular:

npx webpack help --mode

npx webpack --version

This prints the versions of webpack and webpack-cli, plus webpack-dev-server when it is installed:

webpack 5.109.2
webpack-cli 7.2.2
webpack-dev-server 6.0.0

Version mismatches are a common source of confusing errors, so this is usually the first thing worth checking when something behaves unexpectedly. For a fuller picture — operating system, Node.js version, browsers, and the versions of related packages — use webpack info.

• Running builds — building, watching, serving, and choosing which configuration to run.
• Environments and modes — passing values into a configuration that exports a function.
• Scaffolding projects — generating a project, loader, or plugin with create-webpack-app.
• Inspecting builds — progress, stats, bundle analysis, exit codes, and troubleshooting.