Node Interface | webpack

Webpack provides a Node.js API which can be used directly in Node.js runtime.
The Node.js API is useful in scenarios in which you need to customize the build or development process since all the reporting and error handling must be done manually and webpack only does the compiling part. For this reason the stats configuration options will not have any effect in the webpack() call.
To start using the webpack Node.js API, first install webpack if you haven’t yet:
Then import the webpack module in your Node.js script:
The imported webpack function is fed a webpack Configuration Object and runs the webpack compiler if a callback function is provided:
The err object will not include compilation errors. Those must be handled separately using stats.hasErrors(), which will be covered in detail in the Error Handling section of this guide. The err object will only contain webpack-related issues, such as misconfiguration, etc.
You can provide the webpack function with an array of configurations. See the MultiCompiler section below for more information.
If you don’t pass the webpack runner function a callback, it will return a webpack Compiler instance. This instance can be used to manually trigger the webpack runner or have it build and watch for changes, much like the CLI. The Compiler instance provides the following methods:
Typically, only one master Compiler instance is created, although child compilers can be created in order to delegate specific tasks. The Compiler is ultimately a function which performs bare minimum functionality to keep a lifecycle running. It delegates all the loading, bundling, and writing work to registered plugins.
The hooks property on a Compiler instance is used to register a plugin to any hook event in the Compiler's lifecycle. The WebpackOptionsDefaulter and WebpackOptionsApply utilities are used by webpack to configure its Compiler instance with all the built-in plugins.
The platform property on a Compiler instance describes the target environment resolved from target. It is a read-only object of platform flags (web, browser, webworker, node, electron, nwjs, deno, bun and universal), where each flag is true, false, or null when the platform is left neutral. Plugins and loaders can read it to adapt to the build target. Since webpack 5.108.0, platform.universal is true for target: "universal" and for the equivalent target: ["web", "node"].
The run method is then used to kickstart all compilation work. Upon completion, the given callback function is executed. The final logging of stats and errors should be done in this callback function.
The API only supports a single concurrent compilation at a time. When using run or watch, call close and wait for it to finish before calling run or watch again. Concurrent compilations will corrupt the output files.
Calling the run method on the Compiler instance is much like the quick run method mentioned above:
Don't forget to close the compiler, so that low-priority work (like persistent caching) have the opportunity to complete.
Calling the watch method triggers the webpack runner, but then watches for changes (much like CLI: webpack --watch), as soon as webpack detects a change, runs again. Returns an instance of Watching.
Watching options are covered in detail here.
Filesystem inaccuracies may trigger multiple builds for a single change. In the example above, the console.log statement may fire multiple times for a single modification. Users should expect this behavior and may check stats.hash to see if the file hash has actually changed.
The watch method returns a Watching instance that exposes .close(callback) method. Calling this method will end watching:
It’s not allowed to watch or run again before the existing watcher has been closed.
Using watching.invalidate, you can manually invalidate the current compiling round, without stopping the watch process:
The stats object that is passed as a second argument of the webpack() callback, is a good source of information about the code compilation process. It includes:
The webpack CLI uses this information to display nicely formatted output in your console.
When using the MultiCompiler, a MultiStats instance is returned that fulfills the same interface as stats, i.e. the methods described below.
This stats object exposes the following methods:
Can be used to check if there were errors while compiling. Returns true or false.
Can be used to check if there were warnings while compiling. Returns true or false.
Returns compilation information as a JSON object. options can be either a string (a preset) or an object for more granular control:
All available options and presets are described in the stats documentation.
Here’s an example of this function’s output.
Returns a formatted string of the compilation information (similar to CLI output).
Options are the same as stats.toJson(options) with one addition:
Here’s an example of stats.toString() usage:
The MultiCompiler module allows webpack to run multiple configurations in separate compilers. If the options parameter in the webpack's NodeJS api is an array of options, webpack applies separate compilers and calls the callback after all compilers have been executed.
Multiple configurations are run in parallel by default (parallelism: Infinity). Use the parallelism option on the configuration array or dependencies in a configuration to limit or order them.
A MultiCompiler exposes the child compilers' hooks as one, so a plugin can tap the set instead of every child:
Since webpack 5.110.0 the done hook is also handed the compilers whose build actually ran, in configuration order. In watch mode a change usually invalidates only some of the children, and the others are reported from their previous stats, so this is how a plugin tells what is new:
On the first build every child is reported as changed. shutdown was added in the same release and lets a plugin release resources once, for the whole set, rather than tapping each child's own shutdown.