Command Line Interface

npx webpack build [options]

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

npx create-webpack-app [generation-path] [options]

npx create-webpack-app ./my-app --force --template=default

npx create-webpack-app init ./my-app --force --template=default

npx create-webpack-app loader [output-path] [options]

npx create-webpack-app loader ./my-loader --template=default

npx create-webpack-app plugin [output-path] [options]

npx create-webpack-app plugin ./my-plugin --template=default

npx webpack info [options]

npx webpack info --output json --addition-package postcss

npx webpack info --additional-package postcss

npx webpack info --output markdown

npx webpack configtest [config-path]

npx webpack configtest ./webpack.config.js

npx webpack serve [options]

npx webpack serve --static --open

npx webpack watch [options]

npx webpack watch --mode development

npx webpack --performance-hints warning

npx webpack --output-path dist

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

npx webpack --mode production

npx webpack serve --mode development --open

npx webpack configtest
```

### With configuration file

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

See [configuration](/configuration) for the options in the configuration file.

### Without configuration file

```bash
npx webpack --entry <entry> --output-path <output-path>
```

**example**

```bash
npx webpack --entry ./first.js --entry ./second.js --output-path /build
```

#### entry

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).
Following are the multiple ways of specifying entry file(s) via CLI -

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

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

```bash
npx webpack --entry-reset ./first-entry.js ./other-entry.js
```

```bash
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

A path for the bundled file to be saved in. It will be mapped to the configuration options `output.path`.

**Example**

If your project structure is as follows -

```bash
.
├── dist
├── index.html
└── src
    ├── index.js
    ├── index2.js
    └── others.js
```

```bash
npx webpack ./src/index.js --output-path dist
```

This will bundle your source code with entry as `index.js`, and the output bundle file will have a path of `dist`.

```bash
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
npx webpack ./src/index.js ./src/others2.js --output-path dist/
```

This will form the bundle with both the files as separate entry points.

```bash
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.

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',
```

## 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.

### help

**List basic commands and flags available on the cli**

Both `webpack help [command] [option]` and `webpack [command] --help` are valid to get help:

```bash
npx webpack --help

# or

npx webpack help
```

**List all supported commands and flags by cli**

```bash
npx webpack --help=verbose
```

**See help for a specific command or option**

```bash
npx webpack help --mode
```

### version

**Output the version number of 'webpack', 'webpack-cli' and 'webpack-dev-server' and other packages**

To inspect the version of `webpack` and `webpack-cli` you are using, run the command:

```bash
npx webpack --version

# or

npx webpack version
```

This will output the following result:

```bash
webpack 5.31.2
webpack-cli 4.6.0
```

It will output the version of `webpack-dev-server` as well if you have it installed:

```bash
webpack 5.31.2
webpack-cli 4.6.0
webpack-dev-server 3.11.2
```

### config

**Build source using a configuration file**

Specify a different [configuration](/configuration) file other than `webpack.config.js`, which is one of the defaults.

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

### config-name

In case your configuration file exports multiple configurations, you can use `--config-name` to specify which configuration to run.

Consider the following `webpack.config.js`:

```js
export default [
  {
    output: {
      filename: "./dist-first.js",
    },
    name: "first",
    entry: "./src/first.js",
    mode: "development",
  },
  {
    output: {
      filename: "./dist-second.js",
    },
    name: "second",
    entry: "./src/second.js",
    mode: "development",
  },
  {
    output: {
      filename: "./dist-third.js",
    },
    name: "third",
    entry: "./src/third.js",
    mode: "none",
    stats: "verbose",
  },
];
```

To run only the `second` configuration:

```bash
npx webpack --config-name second
```

You can also pass multiple values:

```bash
npx webpack --config-name first --config-name second
```

### merge

You can merge two or more different webpack configurations with the help of `--merge`:

```bash
npx webpack --config ./first.js --config ./second.js --merge
```

### extends

<Badge text="webpack-cli v5.1.0+" />

You can extend existing webpack configurations with the help of `--extends`:

```bash
npx webpack --extends ./base.webpack.config.js
```

Read more about it in [extending configurations](/configuration/extending-configurations/).

### json

**Print result of webpack as JSON**

```bash
npx webpack --json
```

**If you want to store stats as json instead of printing it, you can use -**

```bash
npx 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/webpack-bundle-analyzer). The analyse tool will take in the JSON and provide all the details of the build in graphical form.

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.

### env

```bash
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" }}` |

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

T> See the [environment variables](/guides/environment-variables/) guide for more information on its usage.

In addition to the customized `env` showed above, there are some built-in ones under `env` to be used inside your webpack configuration:

| Environment Variable | Description                                  |
| -------------------- | -------------------------------------------- |
| `WEBPACK_SERVE`      | `true` if `serve\|server\|s` is being used.  |
| `WEBPACK_BUILD`      | `true` if `build\|bundle\|b` is being used.  |
| `WEBPACK_WATCH`      | `true` if `--watch\|watch\|w` is being used. |

Note that you can not access those built-in environment variables inside the bundled code.

```js
export default (env, argv) => ({
  mode: env.WEBPACK_SERVE ? "development" : "production",
});
```

### config-node-env

<Badge text="webpack-cli v6.0.0+" />

Set `process.env.NODE_ENV` for your configuration:

```bash
npx webpack --config-node-env production   # process.env.NODE_ENV = 'production' in `webpack.config.js`
```

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.

```js
export default (env, argv) => {
  console.log(argv.defineProcessEnvNodeEnv); // 'production' if --config-node-env production is used
  return {
    // your configuration
  };
};
```

## Configuration Options

| 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 | string[]   |                                                     |

## Analyzing Bundle

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.

```bash
npx webpack --analyze
```

W> Make sure you have `webpack-bundle-analyzer` installed in your project else CLI will prompt you to install it.

## Progress

To check the progress of any webpack compilation you can use the `--progress` flag.

```bash
npx webpack --progress
```

To collect profile data for progress steps you can pass `profile` as value to `--progress` flag.

```bash
npx webpack --progress=profile
```

## Pass CLI arguments to Node.js

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
NODE_OPTIONS="--max-old-space-size=4096" webpack
```

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
```

## Exit codes and their meanings

| Exit Code | Description                                        |
| --------- | -------------------------------------------------- |
| `0`       | Success                                            |
| `1`       | Errors from webpack                                |
| `2`       | Configuration/options problem or an internal error |

## CLI Environment Variables

| Environment Variable                  | Description                                                         |
| ------------------------------------- | ------------------------------------------------------------------- |
| `WEBPACK_CLI_SKIP_IMPORT_LOCAL`       | when `true` it will skip using the local instance of `webpack-cli`. |
| `WEBPACK_CLI_FORCE_LOAD_ESM_CONFIG`   | when `true` it will force load the ESM config.                      |
| [`WEBPACK_PACKAGE`](#webpack_package) | Use a custom webpack version in CLI.                                |
| `WEBPACK_DEV_SERVER_PACKAGE`          | Use a custom webpack-dev-server version in CLI.                     |
| `WEBPACK_CLI_HELP_WIDTH`              | Use a custom width for help output.                                 |

```bash
WEBPACK_CLI_FORCE_LOAD_ESM_CONFIG=true npx webpack --config ./webpack.config.esm
```

### WEBPACK_PACKAGE

Use a custom webpack version in CLI. Considering the following content in your `package.json`:

```json
{
  "webpack": "^4.0.0",
  "webpack-5": "npm:webpack@^5.32.0",
  "webpack-cli": "^4.5.0"
}
```

To use `webpack v4.0.0`:

```bash
npx webpack
```

To use `webpack v5.32.0`:

```bash
WEBPACK_PACKAGE=webpack-5 npx webpack
```

---

## 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

You might encounter this error in the case of using native ESM in TypeScript (i.e. `type: "module"` in `package.json`).

`webpack-cli` supports configuration in both `CommonJS` and `ESM` format, at first it tries to load a configuration using `import()`, once it fails it would try to load the configuration using `require()`.
However, the `import()` method won't work with `ts-node` without [loader hooks](https://nodejs.org/api/esm.html#esm_experimental_loaders) enabled (described at [`TypeStrong/ts-node#1007`](https://github.com/TypeStrong/ts-node/issues/1007)).

To fix the error above use the following command:

```bash
NODE_OPTIONS="--import=data:text/javascript,import { register } from 'node:module'; import { pathToFileURL } from 'node:url'; register('ts-node/esm', pathToFileURL('./'));" npx webpack --entry ./src/index.js --mode production
```

For more information, see our documentation on [writing a webpack configuration in `TypeScript`](/configuration/configuration-languages/#typescript).