When a build is slow, too large, or simply wrong, the CLI can tell you a lot before you reach for a plugin. This guide covers the flags that report on a build, the commands that inspect a setup without running it, and what the process exits with when things go wrong.
--progress prints the compilation's phases as they happen, which is useful when a build is slow enough that you want to know whether it is stuck:
npx webpack --progressPassing profile adds timing data for each step, so you can see which phase is actually costing you:
npx webpack --progress=profileSince webpack 5.109 a progress bar is built into webpack itself through infrastructureLogging.progress. Setting it to 'auto' shows the interactive bar in a real terminal and stays quiet in CI logs, which is usually what you want in a committed configuration.
By default webpack prints a summary of the assets, chunks, and modules it produced. --stats changes how much of it you see:
npx webpack --stats detailed
npx webpack --stats minimalThe presets and the individual toggles are documented under the stats option. --no-stats suppresses the output entirely.
--json prints the same information as a machine-readable object instead of a formatted report:
npx webpack --jsonGive it a path to write to a file rather than stdout — which you almost always want, since the object is large:
npx webpack --json stats.jsonThat file is the input format for most of the bundle-inspection tooling out there, including the official analyse tool and webpack-bundle-analyzer.
--analyze runs webpack-bundle-analyzer over the build and opens a treemap of what ended up in each bundle:
npx webpack --analyzeThe plugin is not bundled with the CLI, so install it first; otherwise the CLI prompts you to. This is the fastest way to answer "why is this bundle so big" — the treemap usually makes an accidentally-included dependency obvious at a glance. Once you have found it, the tree shaking and code splitting guides cover what to do about it.
configtest loads and validates a configuration without building anything:
npx webpack configtest
npx webpack configtest ./webpack.prod.jsThe path defaults to the usual discovery order. This is worth running as a pre-commit or CI step on projects with several configuration files, since it catches a typo'd option in a second rather than after a full build.
info prints the environment a build runs in: operating system, Node.js and npm versions, browsers, and the versions of webpack-related packages that are installed.
npx webpack infoInclude this in bug reports. --output picks a format, and markdown is the one to use when pasting into an issue:
npx webpack info --output markdown--additional-package adds packages that aren't in the default list, which is handy when the problem involves one of your loaders:
npx webpack info --additional-package postcssWarnings do not fail a build by default. In CI, where a warning nobody reads is a warning nobody fixes, you can promote them:
npx webpack --fail-on-warnings| Exit code | Meaning |
|---|---|
0 | Success. |
1 | webpack reported errors in the build. |
2 | A configuration or options problem, or an internal error. |
The distinction is worth knowing in a pipeline: 1 means your code failed to compile, while 2 means webpack never got far enough to try — usually a bad configuration, a missing dependency, or a configuration file it could not load.
TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for ./webpack.config.tsThis shows up when the configuration is TypeScript and the project is native ESM ("type": "module" in package.json).
webpack-cli tries import() first and falls back to require(). Modern Node.js strips TypeScript types natively, so on Node.js 22.6 or later this usually just works. On older versions, import() needs a loader hook registered, which ts-node does not install by itself:
NODE_OPTIONS="--import=data:text/javascript,import { register } from 'node:module'; import { pathToFileURL } from 'node:url'; register('ts-node/esm', pathToFileURL('./'));" npx webpackInstalling tsx instead avoids the incantation — webpack-cli picks it up automatically. See the TypeScript guide for configuring the build itself.
By default the CLI prefers a project-local installation over a global one, which is almost always right. If you need the global copy for a moment, opt out:
WEBPACK_CLI_SKIP_IMPORT_LOCAL=true webpackCheck that its name and location match the discovery order, and remember that --config disables discovery entirely. npx webpack configtest confirms which file is loaded and whether it validates.
- Build performance — making a slow build faster once you know where the time goes.
- Debugging — attaching a debugger to webpack itself.