Skip to content

Commit 835babf

Browse files
Ash-MistyAsh-Misty
committed
docs: improve CLI documentation
1 parent f3ce903 commit 835babf

1 file changed

Lines changed: 208 additions & 27 deletions

File tree

‎src/content/api/cli.mdx‎

Lines changed: 208 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -32,33 +32,115 @@ related:
3232

3333
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.
3434

35+
## ⚡ Quick Start
36+
37+
Most commonly used commands:
38+
39+
- **Production build**
40+
41+
```bash
42+
npx webpack --mode production
43+
```
44+
45+
- **Start development server**
46+
47+
```bash
48+
npx webpack serve --open
49+
```
50+
51+
- **Watch for file changes**
52+
53+
```bash
54+
npx webpack --watch
55+
```
56+
57+
- **Run with config file**
58+
59+
```bash
60+
npx webpack --config webpack.config.js
61+
```
62+
63+
💡 Tip: Use `serve` during development instead of `watch` for live reload.
64+
3565
Read the [installation guide](/guides/installation) if you don't already have webpack and CLI installed.
3666

37-
W> `webpack-cli` v7.0.0+ requires node >= v20.9.0, `webpack >= v5.101.0`, and `webpack-dev-server >= v5.0.0`.
67+
> ⚠️ **Requirements**
68+
>
69+
> - Node.js >= 20.9.0
70+
> - webpack >= 5.101.0
71+
> - webpack-dev-server >= 5.0.0
3872
3973
W> If you want to run webpack using `npx` please make sure you have `webpack-cli` installed.
4074

75+
---
76+
4177
## Commands
4278

43-
webpack-cli offers a variety of commands to make working with webpack easier. By default webpack ships with
79+
webpack-cli offers a variety of commands to make working with webpack easier.
80+
81+
### Execution Commands
82+
83+
By default webpack ships with the following commands:
84+
85+
| Command | Purpose |
86+
| ---------- | -------------------------------- |
87+
| build | Create production bundle |
88+
| serve | Start dev server (hot reload) |
89+
| watch | Rebuild on file changes |
90+
| info | Show system/debug info |
91+
| configtest | Validate config |
92+
| version | Show package versions |
93+
| help | Show help for commands and flags |
94+
95+
### Project Scaffolding
96+
97+
These commands use the `create-webpack-app` package.
98+
99+
> ℹ️ These commands may prompt you to install `create-webpack-app` if not already installed.
100+
101+
Scaffolding-related commands:
102+
103+
| Command | Usage | Description |
104+
| -------- | ---------------------------------- | ------------------------------------------------------------ |
105+
| `init` | `init [generation-path] [options]` | Initialize a new webpack project using `create-webpack-app`. |
106+
| `loader` | `loader [output-path] [options]` | Scaffold a loader. |
107+
| `plugin` | `plugin [output-path] [options]` | Scaffold a plugin. |
44108

45-
| Command | Usage | Description |
46-
| --------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------- |
47-
| [`build`](#build) | `build\|bundle\|b [entries...] [options]` | Run webpack (default command, can be omitted). |
48-
| [`configtest`](#configtest) | `configtest\|t [config-path]` | Validate a webpack configuration. |
49-
| [`help`](#help) | `help\|h [command] [option]` | Display help for commands and options. |
50-
| [`info`](#info) | `info\|i [options]` | Outputs information about your system. |
51-
| [`serve`](#serve) | `serve\|server\|s [options]` | Run the `webpack-dev-server`. |
52-
| [`version`](#version) | `version\|v [commands...]` | Output the version number of 'webpack', 'webpack-cli' and 'webpack-dev-server' and other packages. |
53-
| [`watch`](#watch) | `watch\|w [entries...] [options]` | Run webpack and watch for files changes. |
109+
## When should I use each command?
110+
111+
- **build** → Create a production-ready bundle
112+
- **serve** → Run development server with live reload
113+
- **watch** → Rebuild automatically without dev server
114+
- **configtest** → Validate configuration file
115+
- **info** → Debug environment issues
116+
117+
## Common Use Cases
118+
119+
### Build for production
120+
121+
```bash
122+
npx webpack --mode production
123+
```
124+
125+
### Development with live reload
126+
127+
```bash
128+
npx webpack serve --mode development --open
129+
```
130+
131+
### Debug configuration
132+
133+
````bash
134+
npx webpack configtest
135+
``` |
54136
55137
### Build
56138
57139
Run webpack (default command, can be omitted).
58140
59141
```bash
60142
npx webpack build [options]
61-
```
143+
````
62144

63145
**example**
64146

@@ -253,9 +335,56 @@ npx webpack watch [options]
253335
npx webpack watch --mode development
254336
```
255337

338+
---
339+
256340
## Flags
257341

258-
By default webpack ships with the following flags:
342+
### Basic Flags
343+
344+
| Flag | Description |
345+
| ---------------- | ---------------------------------- |
346+
| `--mode` | Set development or production mode |
347+
| `--config`, `-c` | Specify config file |
348+
| `--watch`, `-w` | Enable watch mode |
349+
| `--progress` | Show build progress |
350+
351+
### Input / Output
352+
353+
| Flag | Description |
354+
| --------------------- | ---------------- |
355+
| `--entry` | Entry point |
356+
| `--output-path`, `-o` | Output directory |
357+
| `--target`, `-t` | Build target |
358+
359+
### Development & Debugging
360+
361+
| Flag | Description |
362+
| ----------------- | -------------------- |
363+
| `--devtool`, `-d` | Source maps |
364+
| `--stats` | Control output stats |
365+
| `--json`, `-j` | Output JSON stats |
366+
| `--analyze` | Analyze bundle |
367+
368+
### Advanced
369+
370+
| Flag | Description |
371+
| ----------------- | -------------------------- |
372+
| `--env` | Pass environment variables |
373+
| `--config-name` | Select config |
374+
| `--merge`, `-m` | Merge configs |
375+
| `--extends`, `-e` | Extend config |
376+
377+
### CLI Behavior
378+
379+
| Flag | Description |
380+
| ----------------- | ------------- |
381+
| `--color` | Enable colors |
382+
| `--help` | Show help |
383+
| `--version`, `-v` | Show version |
384+
385+
### Full flag reference
386+
387+
By default webpack also ships with the following flags:
259388

260389
| Flag / Alias | Type | Description |
261390
| --------------------------------------- | --------------- | ------------------------------------------------------------------------- |
@@ -306,6 +435,30 @@ For example if you want to enable performance hints in your project you'd use [t
306435
npx webpack --performance-hints warning
307436
```
308437

438+
---
439+
440+
## How CLI maps to configuration
441+
442+
Most CLI options map directly to `webpack.config.js`.
443+
444+
**example**
445+
446+
```bash
447+
npx webpack --output-path dist
448+
```
449+
450+
Equivalent config:
451+
452+
```js
453+
module.exports = {
454+
output: {
455+
path: "dist",
456+
},
457+
};
458+
```
459+
460+
---
461+
309462
## Usage
310463

311464
### With configuration file
@@ -351,6 +504,24 @@ npx webpack --entry-reset --entry ./first-entry.js ./other-entry.js
351504

352505
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.
353506

507+
### Example: Before vs After
508+
509+
Without `--entry-reset`:
510+
511+
```bash
512+
npx webpack --entry ./new.js
513+
```
514+
515+
Adds to existing entries.
516+
517+
With `--entry-reset`:
518+
519+
```bash
520+
npx webpack --entry-reset ./new.js
521+
```
522+
523+
Replaces all previous entries.
524+
354525
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']`
355526

356527
#### output-path
@@ -407,9 +578,7 @@ This is the lookup priority in increasing order
407578
> example - config file lookup will be in order of webpack.config.js > .webpack/webpack.config.js > .webpack/webpackfile.js
408579
409580
```text
410-
'webpack.config',
411-
'.webpack/webpack.config',
412-
'.webpack/webpackfile',
581+
'webpack.config','.webpack/webpack.config','.webpack/webpackfile',
413582
```
414583

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

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

739+
---
740+
570741
## Environment Options
571742

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

751+
Result:
752+
753+
```js
754+
env.production = true;
755+
```
756+
580757
The `--env` argument accepts multiple values:
581758

582-
| Invocation | Resulting environment |
583-
| ---------------------------------------------------------------- | ---------------------------------------------- |
584-
| `npx webpack --env prod` | `{ prod: true }` |
585-
| `npx webpack --env prod --env min` | `{ prod: true, min: true }` |
586-
| `npx webpack --env platform=app --env production` | `{ platform: "app", production: true }` |
587-
| `npx webpack --env foo=bar=app` | `{ foo: "bar=app"}` |
588-
| `npx webpack --env app.platform="staging" --env app.name="test"` | `{ app: { platform: "staging", name: "test" }` |
759+
| Invocation | Resulting environment |
760+
| ---------------------------------------------------------------- | ----------------------------------------------- |
761+
| `npx webpack --env prod` | `{ prod: true }` |
762+
| `npx webpack --env prod --env min` | `{ prod: true, min: true }` |
763+
| `npx webpack --env platform=app --env production` | `{ platform: "app", production: true }` |
764+
| `npx webpack --env foo=bar=app` | `{ foo: "bar=app"}` |
765+
| `npx webpack --env app.platform="staging" --env app.name="test"` | `{ app: { platform: "staging", name: "test" }}` |
589766

590767
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=\"\"`
591768

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

620797
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'`.
621798

622-
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.
799+
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.
623800

624801
```js
625802
export default (env, argv) => {
@@ -666,13 +843,13 @@ npx webpack --progress=profile
666843

667844
To pass arguments directly to Node.js process, you can use the `NODE_OPTIONS` option.
668845

669-
For example, to increase the memory limit of Node.js process to 4 GB
846+
For example, to increase the memory limit of Node.js process to 4 GB:
670847

671848
```bash
672849
NODE_OPTIONS="--max-old-space-size=4096" webpack
673850
```
674851

675-
Also, you can pass multiple options to Node.js process
852+
You can also pass multiple options to Node.js process:
676853

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

727-
## Troubleshooting
904+
---
905+
906+
## Using Webpack with TypeScript & ESM
907+
908+
Node.js requires a loader hook to understand `.ts` files when using ESM.
728909

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

0 commit comments

Comments
 (0)