webpack CLI

7.0.2 verified Thu Apr 23 auth: no javascript

webpack-cli is the official command-line interface for webpack, a widely adopted module bundler for modern JavaScript applications. It provides a robust set of commands and options to streamline the configuration and execution of webpack builds. Currently stable at version 7.0.2, it receives regular patch releases, with major version updates often coinciding with Node.js LTS cycles or significant shifts in the webpack ecosystem. A key differentiator is its ability to simplify the initialization and management of complex webpack configurations, offering a flexible approach to project setup that works both with and without a pre-existing `webpack.config.js` file. It consolidates common development tasks such as building, serving with a dev server, and watching for file changes, significantly enhancing developer productivity within the webpack environment.

Common errors

error Error: Cannot find module 'webpack' ↓

cause The 'webpack' package is not installed as a peer dependency.

fix

Install webpack: npm install --save-dev webpack or yarn add webpack --dev.

error Unknown command 'init' ↓

cause The `init` command (and `loader`, `plugin`) was removed in webpack-cli v6.0.0.

fix

Use npx create-webpack-app for scaffolding new webpack projects or migrating existing ones. Consult the webpack-cli documentation for alternative commands.

error Node.js vX.Y.Z is not supported. Please use Node.js v20.9.0 or higher. ↓

cause Your Node.js version does not meet the minimum requirement for webpack-cli v7+.

fix

Upgrade your Node.js to version 20.9.0 or newer. Recommended: nvm install 20 && nvm use 20.

error Error: Cannot find module 'webpack-dev-server' or Peer dependency 'webpack-dev-server@^5.0.0' not installed ↓

cause webpack-dev-server is missing or an incompatible version is installed when using the `serve` command.

fix

Install the correct version: npm install --save-dev webpack-dev-server@^5.0.0 or yarn add webpack-dev-server@^5.0.0 --dev.

Warnings

breaking webpack-cli v7.0.0 and above requires Node.js version 20.9.0 or higher. Earlier versions of Node.js are no longer supported. ↓

fix Upgrade your Node.js environment to version 20.9.0 or newer. Use `nvm install 20 && nvm use 20` or your preferred Node.js version manager.

breaking The `init`, `loader`, and `plugin` commands were removed in webpack-cli v6.0.0. They have been superseded by `create-webpack-app`. ↓

fix For new projects or scaffolding, use `npx create-webpack-app` instead. If you need to migrate existing scripts, adapt them to manually configure webpack or use `create-webpack-app`'s functionality.

breaking webpack-cli v6.0.0 dropped support for `webpack-dev-server@v4`. You must use `webpack-dev-server@v5` or newer for the `serve` command. ↓

fix Update your `webpack-dev-server` dependency to `^5.0.0` or later in your `package.json`.

breaking The minimum supported `webpack` version for webpack-cli v6.0.0 and higher is `5.82.0`. ↓

fix Ensure your `webpack` dependency is updated to `^5.82.0` or newer in your `package.json`.

breaking The `--define-process-env-node-env` option was renamed to `--config-node-env` in webpack-cli v6.0.0. ↓

fix Update your CLI commands or scripts to use `--config-node-env` instead of the old option name.

gotcha Since webpack-cli v7.0.0, configuration files (`webpack.config.js`) are primarily loaded using dynamic `import()` to leverage Node.js's native ES module and TypeScript support. It falls back to `require()` only if dynamic import fails. This can affect how `module.exports` or CJS-style configurations behave if not explicitly handled. ↓

fix For optimal compatibility and to utilize modern Node.js features, consider migrating your `webpack.config.js` to an ES module format (e.g., using `export default { ... }`) or naming it `webpack.config.mjs`. If sticking with CJS, ensure it's compatible with potential dynamic import fallbacks or use `--disable-interpret` if encountering issues.

Install

npm install webpack-cli

yarn add webpack-cli

pnpm add webpack-cli

Imports

WebpackCLI
wrong
```
import { WebpackCLI } from 'webpack-cli';
```
correct
```
import type { WebpackCLI } from 'webpack-cli';
```
webpack-cli is primarily a CLI tool; direct programmatic runtime imports are generally not intended. This import is useful for type declarations when extending or analyzing webpack-cli's structure in TypeScript projects.
CommandArgs
wrong
```
import { CommandArgs } from 'webpack-cli';
```
correct
```
import type { CommandArgs } from 'webpack-cli';
```
Use this import for type declarations to define expected arguments when programmatically interacting with or extending webpack-cli commands within TypeScript.
WebpackCLIOptions
wrong
```
import { WebpackCLIOptions } from 'webpack-cli';
```
correct
```
import type { WebpackCLIOptions } from 'webpack-cli';
```
Provides type definitions for the various options accepted by webpack-cli, valuable for strong type-checking in configuration files or custom scripts.

Quickstart

Demonstrates a basic webpack build using `webpack-cli` with a simple ES module configuration, including how to pass environment variables.

import path from 'path';
import { fileURLToPath } from 'url';

// Get __dirname equivalent for ES modules
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

export default {
  mode: 'development',
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
  },
  // Example of using an environment variable from webpack-cli --env
  // For example: npx webpack-cli build --env API_URL=http://localhost:3000
  plugins: [
    {
      apply: (compiler) => {
        compiler.hooks.environment.tap('LogEnvPlugin', () => {
          console.log('API_URL from --env:', process.env.API_URL || 'Not set');
        });
      },
    },
  ],
};

// --- src/index.js ---
// console.log('Hello from webpack!');

// --- Terminal Command ---
// npx webpack-cli build --env API_URL=https://api.example.com