Skip to content

docs: improve CLI documentation clarity #8059

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Ash-Misty wants to merge 6 commits into from
Closed

docs: improve CLI documentation clarity #8059

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
835babf
docs: improve CLI documentation
Ash-Misty Mar 19, 2026
1c85314
docs: move Common Use Cases section per review feedback
Ash-Misty Mar 19, 2026
e4efbb4
commit changes
Ash-Misty Mar 19, 2026
7dc8b69
solved all conflicts
Ash-Misty Mar 19, 2026
b2b1449
apply script fixes
Ash-Misty Mar 19, 2026
3156e33
chore: update yarn.lock after adding cross-env dependency
Ash-Misty Mar 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,3 +15,4 @@ internal-links.tap
stats.json
printable.mdx
repositories/*.json
.prettierrc
2 changes: 2 additions & 0 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,8 @@
"react-tiny-popover": "^8.1.6",
"react-use": "^17.6.0",
"webpack-pwa-manifest": "^4.3.0",
"workbox-cacheable-response": "^7.4.0",
"workbox-expiration": "^7.4.0",
"workbox-window": "^7.4.0"
},
"devDependencies": {
Expand Down
286 changes: 234 additions & 52 deletions src/content/api/cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,25 +32,87 @@ related:

For proper usage and easier 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 configuration file.

## ⚡ Quick Start

Most commonly used commands:

- **Production build**

```bash
npx webpack --mode production
```

- **Start development server**

```bash
npx webpack serve --open
```

- **Watch for file changes**

```bash
npx webpack --watch
```

- **Run with config file**

```bash
npx webpack --config webpack.config.js
```

💡 Tip: Use `serve` during development instead of `watch` for live reload.

Read the [installation guide](/guides/installation) if you don't already have webpack and CLI installed.

W> `webpack-cli` v7.0.0+ requires node >= v20.9.0, `webpack >= v5.101.0`, and `webpack-dev-server >= v5.0.0`.
> ⚠️ **Requirements**
>
> - Node.js >= 20.9.0
> - webpack >= 5.101.0
> - webpack-dev-server >= 5.0.0

W> If you want to run webpack using `npx` please make sure you have `webpack-cli` installed.

---

## Commands

webpack-cli offers a variety of commands to make working with webpack easier. By default webpack ships with
webpack-cli offers a variety of commands to make working with webpack easier.

### Execution Commands

By default webpack ships with the following commands:

| Command | Purpose |
| ---------- | -------------------------------- |
| build | Create production bundle |
| serve | Start dev server (hot reload) |
| watch | Rebuild on file changes |
| info | Show system/debug info |
| configtest | Validate config |
| version | Show package versions |
| help | Show help for commands and flags |

### Project Scaffolding

These commands use the `create-webpack-app` package.

> ℹ️ These commands may prompt you to install `create-webpack-app` if not already installed.

| Command | Usage | Description |
| --------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------- |
| [`build`](#build) | `build\|bundle\|b [entries...] [options]` | Run webpack (default command, can be omitted). |
| [`configtest`](#configtest) | `configtest\|t [config-path]` | Validate a webpack configuration. |
| [`help`](#help) | `help\|h [command] [option]` | Display help for commands and options. |
| [`info`](#info) | `info\|i [options]` | Outputs information about your system. |
| [`serve`](#serve) | `serve\|server\|s [options]` | Run the `webpack-dev-server`. |
| [`version`](#version) | `version\|v [commands...]` | Output the version number of 'webpack', 'webpack-cli' and 'webpack-dev-server' and other packages. |
| [`watch`](#watch) | `watch\|w [entries...] [options]` | Run webpack and watch for files changes. |
Scaffolding-related commands:

| Command | Usage | Description |
| -------- | ---------------------------------- | ------------------------------------------------------------ |
| `init` | `init [generation-path] [options]` | Initialize a new webpack project using `create-webpack-app`. |
| `loader` | `loader [output-path] [options]` | Scaffold a loader. |
| `plugin` | `plugin [output-path] [options]` | Scaffold a plugin. |

## When should I use each command?

- **build** → Create a production-ready bundle
- **serve** → Run development server with live reload
- **watch** → Rebuild automatically without dev server
- **configtest** → Validate configuration file
- **info** → Debug environment issues

### Build

Expand Down Expand Up @@ -253,35 +315,82 @@ npx webpack watch [options]
npx webpack watch --mode development
```

---

## Flags

By default webpack ships with the following flags:

| Flag / Alias | Type | Description |
| --------------------------------------- | --------------- | ------------------------------------------------------------------------- |
| [`--entry`](#entry) | string[] | The entry point(s) of your application e.g. `./src/main.js` |
| [`--config, -c`](#config) | string[] | Provide path to a webpack configuration file e.g. `./webpack.config.js` |
| [`--config-name`](#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 |
| [`--merge, -m`](#merge) | boolean | Merge two or more configurations using `webpack-merge` |
| [`--env`](#env) | string[] | Environment passed to the configuration when it is a function |
| [`--config-node-env`](#config-node-env) | string | Set `process.env.NODE_ENV` to the specified value |
| [`--progress`](#progress) | boolean, string | Print compilation progress during build |
| [`--help`](#help) | boolean | Outputs list of supported flags and commands |
| [`--output-path, -o`](#output-path) | 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 |
| `--watch-options-stdin` | boolean | Stop watching when stdin stream has ended |
| `--devtool, -d` | string | Controls if and how source maps are generated. |
| [`--json, -j`](#json) | boolean, string | Prints result as JSON or store it in a file |
| `--mode` | string | Defines the mode to pass to webpack |
| [`--version, -v`](#version) | boolean | Get current version |
| `--stats` | boolean, string | It instructs webpack on how to treat the stats |
| `--disable-interpret` | boolean | Disable interpret for loading the config file. |
| `--fail-on-warnings` | boolean | Stop webpack-cli process with non-zero exit code on warnings from webpack |
| [`--analyze`](#analyzing-bundle) | boolean | It invokes `webpack-bundle-analyzer` plugin to get bundle information |
| [`--extends, -e`](#extends) | string[] | Extend an existing configuration |
### Basic Flags

| Flag | Description |
| ---------------- | ---------------------------------- |
| `--mode` | Set development or production mode |
| `--config`, `-c` | Specify config file |
| `--watch`, `-w` | Enable watch mode |
| `--progress` | Show build progress |

### Input / Output

| Flag | Description |
| --------------------- | ---------------- |
| `--entry` | Entry point |
| `--output-path`, `-o` | Output directory |
| `--target`, `-t` | Build target |

### Development & Debugging

| Flag | Description |
| ----------------- | -------------------- |
| `--devtool`, `-d` | Source maps |
| `--stats` | Control output stats |
| `--json`, `-j` | Output JSON stats |
| `--analyze` | Analyze bundle |

### Advanced

| Flag | Description |
| ----------------- | -------------------------- |
| `--env` | Pass environment variables |
| `--config-name` | Select config |
| `--merge`, `-m` | Merge configs |
| `--extends`, `-e` | Extend config |

### CLI Behavior

| Flag | Description |
| ----------------- | ------------- |
| `--color` | Enable colors |
| `--help` | Show help |
| `--version`, `-v` | Show version |

### Full flag reference

By default webpack also ships with the following 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 |
| `--merge, -m` | boolean | Merge two or more configurations using `webpack-merge` |
| `--env` | string[] | Environment passed to the configuration when it is a function |
| `--config-node-env` | string | Set `process.env.NODE_ENV` to the specified value |
| `--progress` | boolean, string | 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 |
| `--watch-options-stdin` | boolean | Stop watching when stdin stream has ended |
| `--devtool, -d` | string | Controls if and how source maps are generated. |
| `--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 |
| `--disable-interpret` | boolean | Disable interpret for loading the config file. |
| `--fail-on-warnings` | boolean | Stop webpack-cli process with non-zero exit code on warnings from webpack |
| `--analyze` | boolean | It invokes `webpack-bundle-analyzer` plugin to get bundle information |
| `--extends, -e` | string[] | Extend an existing configuration |

### Negated Flags

Expand All @@ -306,8 +415,52 @@ For example if you want to enable performance hints in your project you'd use [t
npx webpack --performance-hints warning
```

---

## How CLI maps to configuration

Most CLI options map directly to `webpack.config.js`.

**example**

```bash
npx webpack --output-path dist
```

Equivalent config:

```js
module.exports = {
output: {
path: "dist",
},
};
```

---

## Usage

## Common Use Cases

### Build for production

```bash
npx webpack --mode production
```

### Development with live reload

```bash
npx webpack serve --mode development --open
```

### Debug configuration

````bash
npx webpack configtest
```

### With configuration file

```bash
Expand Down Expand Up @@ -351,6 +504,24 @@ npx webpack --entry-reset --entry ./first-entry.js ./other-entry.js

W> The `--entry-reset` option is required to replace the existing [entry](/configuration/entry-context/#entry) option, without it the `--entry` option will add another entry to the existing entries.

### Example: Before vs After

Without `--entry-reset`:

```bash
npx webpack --entry ./new.js
```

Adds to existing entries.

With `--entry-reset`:

```bash
npx webpack --entry-reset ./new.js
```

Replaces all previous entries.

T> Use `webpack [command] --entry-reset [entries...] [option]` syntax because some options can accept multiple values so `webpack --target node ./entry.js` means `target: ['node', './entry.js']`

#### output-path
Expand Down Expand Up @@ -407,9 +578,7 @@ This is the lookup priority in increasing order
> example - config file lookup will be in order of webpack.config.js > .webpack/webpack.config.js > .webpack/webpackfile.js

```text
'webpack.config',
'.webpack/webpack.config',
'.webpack/webpackfile',
'webpack.config','.webpack/webpack.config','.webpack/webpackfile',
```

## Common Options
Expand Down Expand Up @@ -567,6 +736,8 @@ In every other case, webpack prints out a set of stats showing bundle, chunk and

T> See the [stats data api](/api/stats) to read more about the stats generated here.

---

## Environment Options

When the webpack configuration [exports a function](/configuration/configuration-types/#exporting-a-function), an "environment" may be passed to it.
Expand All @@ -577,15 +748,21 @@ When the webpack configuration [exports a function](/configuration/configuration
npx webpack --env production # env.production = true
```

Result:

```js
env.production = true;
```

The `--env` argument accepts multiple values:

| Invocation | Resulting environment |
| ---------------------------------------------------------------- | ---------------------------------------------- |
| `npx webpack --env prod` | `{ prod: true }` |
| `npx webpack --env prod --env min` | `{ prod: true, min: true }` |
| `npx webpack --env platform=app --env production` | `{ platform: "app", production: true }` |
| `npx webpack --env foo=bar=app` | `{ foo: "bar=app"}` |
| `npx webpack --env app.platform="staging" --env app.name="test"` | `{ app: { platform: "staging", name: "test" }` |
| Invocation | Resulting environment |
| ---------------------------------------------------------------- | ----------------------------------------------- |
| `npx webpack --env prod` | `{ prod: true }` |
| `npx webpack --env prod --env min` | `{ prod: true, min: true }` |
| `npx webpack --env platform=app --env production` | `{ platform: "app", production: true }` |
| `npx webpack --env foo=bar=app` | `{ foo: "bar=app"}` |
| `npx webpack --env app.platform="staging" --env app.name="test"` | `{ app: { platform: "staging", name: "test" }}` |

T> If you want to explicitly set a variable to empty string (`""`), you may need to escape characters on terminal like `npx webpack --env foo=\"\"`

Expand Down Expand Up @@ -619,7 +796,7 @@ npx webpack --config-node-env production # process.env.NODE_ENV = 'production'

When the `mode` option is not specified in the configuration, you can use the `--config-node-env` option to set the `mode`. For example, using `--config-node-env production` will set both `process.env.NODE_ENV` and `mode` to `'production'`.

If your configuration exports a function, the value of `--config-node-env` is assigned to mode after the function returns. This means that `mode` will not be available in the function arguments (`env` and `argv`). However, the value of `--config-node-env` is accessible as `argv.nodeEnv` within the function and can be used accordingly.
If your configuration exports a function, the value of `--config-node-env` is assigned to `mode` after the function returns. This means that `mode` will not be available in the function arguments (`env` and `argv`). However, the value of `--config-node-env` is accessible as `argv.nodeEnv` within the function and can be used accordingly.

```js
export default (env, argv) => {
Expand Down Expand Up @@ -666,13 +843,13 @@ npx webpack --progress=profile

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
For example, to increase the memory limit of Node.js process to 4 GB:

```bash
NODE_OPTIONS="--max-old-space-size=4096" webpack
```

Also, you can pass multiple options to Node.js process
You can also pass multiple options to Node.js process:

```bash
NODE_OPTIONS="--max-old-space-size=4096 -r /path/to/preload/file.js" webpack
Expand Down Expand Up @@ -724,7 +901,11 @@ To use `webpack v5.32.0`:
WEBPACK_PACKAGE=webpack-5 npx webpack
```

## Troubleshooting
---

## Using Webpack with TypeScript & ESM

Node.js requires a loader hook to understand `.ts` files when using ESM.

### TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for ./webpack.config.ts

Expand All @@ -740,3 +921,4 @@ NODE_OPTIONS="--import=data:text/javascript,import { register } from 'node:modul
```

For more information, see our documentation on [writing a webpack configuration in `TypeScript`](/configuration/configuration-languages/#typescript).
````
1 change: 1 addition & 0 deletions src/sw.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
/* eslint-disable import/no-extraneous-dependencies */

import { CacheableResponsePlugin } from "workbox-cacheable-response";
import { cacheNames } from "workbox-core";
import { ExpirationPlugin } from "workbox-expiration";
Expand Down
Loading