webpack-cli

webpack-cli is the official command-line tool for webpack, giving developers a full set of commands — build, serve, watch, configtest, info, and version — for driving a webpack configuration from the terminal instead of writing custom Node scripts. It resolves and validates webpack config files written in JavaScript, TypeScript, JSON5, YAML, or TOML, delegates automatically to a locally installed webpack-cli so global and local installs never conflict, and exposes an extension point (CLIPlugin) that lets other webpack plugins register their own commands and options.

Beyond the base CLI, the monorepo also ships create-webpack-app, an interactive scaffolding tool for bootstrapping new webpack projects. Maintained as part of the core webpack organization, webpack-cli is the default entry point that the vast majority of webpack-based projects use to invoke webpack, whether directly from the terminal or through a framework’s own build scripts.

What You Get

• Full command set — build, serve, watch, configtest, info, version, help, and complete — covering the entire webpack development lifecycle from one CLI.
• Automatic config-format support for .js, .ts, .mjs, .cjs, .json5, .yaml, and .toml webpack configuration files, loading optional parsers only when needed.
• Local-install delegation via import-local, so a globally installed webpack-cli automatically defers to a project’s own local version to avoid version drift.
• Shell completion for zsh, bash, fish, and PowerShell driven by webpack’s own command schema.
• A CLIPlugin extension point that lets webpack plugins register additional CLI commands and options.

Common Use Cases

• Running webpack builds and dev servers from package.json scripts without hand-rolling a Node build script.
• Validating a webpack configuration file in CI with configtest before a real build runs.
• Scaffolding a brand-new webpack project with create-webpack-app’s interactive prompts.
• Debugging environment-specific build issues using the info command’s environment report.

Under The Hood

Architecture

The CLI is centered on a single orchestrator class (WebpackCLI in packages/webpack-cli/src/webpack-cli.ts, backed by Commander.js for argument parsing) that lazily loads each command’s implementation on demand through #loadCommandByName rather than registering all commands and their ~850 combined options upfront. Non-JS configuration formats (JSON5/YAML/TOML) are handled by a small DATA_FORMAT_LOADERS table that imports the matching parser package from the user’s own project only when that format is actually used, and a dedicated ConfigurationLoadingError class carries structured failure info back to the top-level error handler. A CLIPlugin extension point lets external webpack plugins register additional commands, giving the CLI a degree of pluggable, event-driven extensibility layered on top of what is otherwise a monolithic command dispatcher.

Tech Stack

Written in strict TypeScript (ES2022 target, NodeNext module resolution) and built with tsc --build across an npm-workspaces monorepo (packages/webpack-cli and packages/create-webpack-app). Core dependencies are Commander for CLI parsing, webpack-merge for config merging, cross-spawn, envinfo for the info command, import-local for local-install delegation, interpret/rechoir for loading arbitrary config file types, and @discoveryjs/json-ext for streaming large stats output. Shell completion is provided by the optional @bomb.sh/tab peer dependency. Releases are versioned and published via Changesets, with pkg-pr-new providing per-PR preview publishes.

Code Quality

The test suite spans over a dozen categories (build, serve, watch, configtest, complete, info, version, help, api, external-command, create-webpack-app, and more) run with Jest through @swc/jest, exercising the CLI end-to-end against real fixture configs rather than only mocking internals. Linting combines eslint-config-webpack with cspell spellchecking, enforced through lint-staged and Husky pre-commit hooks, and formatting is standardized with Prettier. CI runs on GitHub Actions (nodejs.yml) alongside a dependency-review workflow, and the codebase leans on strict TypeScript typing and dedicated error classes rather than ad hoc error objects.

API Design The CLI’s public surface is its command set (build/bundle/b, serve/s, watch/w, configtest/t, info/i, version/v, help/h, complete), with short aliases for the most common commands and consistent, documented exit codes (0 success, 1 webpack error, 2 CLI/config error). Optional peer dependencies (js-yaml, json5, toml, @bomb.sh/tab, webpack-bundle-analyzer, webpack-dev-server) are pulled in lazily so the base install stays light, and import-local delegation means a single global install can transparently proxy to whichever local version a project depends on.