webpack-dev-server Documentation

1. Project Overview & Quickstart (webpack/webpack-dev-server) Copy Chapter

File: README.md Copy Chapter

webpack-dev-server

Use webpack with a development server that provides
live reloading. This should be used for development only.

It uses webpack-dev-middleware under the hood, which provides
fast in-memory access to the webpack assets.

Table of Contents Copy Chapter

• Getting Started
• Usage
  • With the CLI
  • With NPM Scripts
  • With the API
  • With TypeScript
  • The Result
• Browser Support
• Support
• Contributing
• Attribution
• License

Getting Started Copy Chapter

First things first, install the module:

npm install webpack-dev-server --save-dev

or

yarn add -D webpack-dev-server

or

pnpm add -D webpack-dev-server

Note: While you can install and run webpack-dev-server globally, we recommend
installing it locally. webpack-dev-server will always use a local installation
over a global one.

Usage Copy Chapter

There are two main, recommended methods of using the module:

With the CLI Copy Section

The easiest way to use it is with the webpack CLI. In the directory where your
webpack.config.js is, run:

npx webpack serve

Following options are available with webpack serve:

/* Detailed source-code truncated for AI context efficiency. */

[!NOTE]

Detailed documentation for above options is available on this link.

With NPM Scripts Copy Section

NPM package.json scripts are a convenient and useful means to run locally installed
binaries without having to be concerned about their full paths. Simply define a
script as such:

{
  "scripts": {
    "serve": "webpack serve"
  }
}

And run the following in your terminal/console:

npm run serve

NPM will automatically refer to the the binary in node_modules for you, and
execute the file or command.

With the API Copy Section

While it's recommended to run webpack-dev-server via the CLI, you may also choose to start a server via the API.

See the related API documentation for webpack-dev-server.

With TypeScript Copy Section

If you use TypeScript in the webpack config, you'll need to properly type devServer property in order to avoid TS errors (e.g. 'devServer' does not exist in type 'Configuration'). For that use either:

/// <reference path="node_modules/webpack-dev-server/types/lib/Server.d.ts"/>
import { type Configuration } from "webpack";

// Your logic

Or you can import the type from webpack-dev-server, i.e.

import { type Configuration } from "webpack";
import { type Configuration as DevServerConfiguration } from "webpack-dev-server";

const devServer: DevServerConfiguration = {};
const config: Configuration = { devServer };

// module.exports
export default config;

The Result Copy Section

Either method will start a server instance and begin listening for connections
from localhost on port 8080.

webpack-dev-server is configured by default to support live-reload of files as
you edit your assets while the server is running.

See the documentation for more use cases and options.

Browser Support Copy Chapter

While webpack-dev-server transpiles the client (browser) scripts to an ES5
state, the project only officially supports the last two versions of major
browsers. We simply don't have the resources to support every whacky
browser out there.

If you find a bug with an obscure / old browser, we would actively welcome a
Pull Request to resolve the bug.

Support Copy Chapter

We do our best to keep issues in the repository focused on bugs, features, and
needed modifications to the code for the module. Because of that, we ask users
with general support, "how-to", or "why isn't this working" questions to try one
of the other support channels that are available.

Your first-stop-shop for support for webpack-dev-server should be the excellent
documentation for the module. If you see an opportunity for improvement
of those docs, please head over to the webpack.js.org repo and open a
pull request.

From there, we encourage users to visit the webpack discussions and
talk to the fine folks there. If your quest for answers comes up dry in chat,
head over to StackOverflow and do a quick search or open a new
question. Remember; It's always much easier to answer questions that include your
webpack.config.js and relevant files!

If you're twitter-savvy you can tweet #webpack with your question
and someone should be able to reach out and lend a hand.

If you have discovered a :bug:, have a feature suggestion, or would like to see
a modification, please feel free to create an issue on Github. Note: The issue
template isn't optional, so please be sure not to remove it, and please fill it
out completely.

Contributing Copy Chapter

We welcome your contributions! Please have a read of CONTRIBUTING.md for more information on how to get involved.

Attribution Copy Chapter

This project is heavily inspired by peerigon/nof5.

License Copy Chapter

[MIT](./LICENSE)

File: examples/proxy/README.md Copy Chapter

proxy

Proxying some URLs can be useful when you have a separate API backend development server and you want to send API requests on the same domain.

webpack.config.js

module.exports = {
  // ...
  devServer: {
    proxy: {
      "/proxy": {
        target: "http://localhost:5000",
      },
    },
  },
};

To run this example use the following command:

npx webpack serve --open

What Should Happen Copy Chapter

1. The script start a proxy server on http://localhost:5000/ and open http://localhost:8080/ in your default browser.
2. You should see the text on the page itself change to read Success! Now visit /proxy.
3. Now visit the /proxy route by clicking on the /proxy text, you should see the text on the page itself change to read response from proxy.

File: examples/open-target-multiple/README.md Copy Chapter

Open Target Option (Multiple)

webpack.config.js

module.exports = {
  // ...
  devServer: {
    open: {
      target: ["/example1.html", "example2.html"],
    },
  },
};

Usage via CLI:

npx webpack serve --open-target example1.html --open-target example2.html

Some applications may consist of multiple pages. During development it may
be useful to directly open multiple pages at the same time. The pages to open
may be specified as the argument to the open-target option.

What Should Happen Copy Chapter

The script should open http://localhost:8080/example1.html and
http://localhost:8080/example2.html in your default browser.
You should see the text on the page itself change to read Success!.

File: examples/open-target/README.md Copy Chapter

Open Target Option

Open default generated URL in browser: Copy Chapter

webpack.config.js

module.exports = {
  // ...
  devServer: {
    open: {
      target: "",
    },
  },
};

Usage via CLI:

npx webpack serve --open-target

Open specific page in browser: Copy Chapter

webpack.config.js

module.exports = {
  // ...
  devServer: {
    open: {
      target: "/example.html#page1",
    },
  },
};

Usage via CLI:

npx webpack serve --open-target /example.html#page1

Open specific browser: Copy Chapter

webpack.config.js

module.exports = {
  // ...
  devServer: {
    open: {
      app: "firefox",
    },
  },
};

Usage via CLI:

npx webpack serve --open-app-name firefox

Open specific page in specific browser: Copy Chapter

webpack.config.js

module.exports = {
  // ...
  devServer: {
    open: {
      target: "/example.html#page1",
      app: "firefox",
    },
  },
};

Usage via CLI:

npx webpack serve --open-target example.html#page1 --open-app-name firefox

Some applications may consist of multiple pages. During development it may
be useful to directly open a particular page. The page to open may be specified
as the argument to the open-target option.

What Should Happen Copy Chapter

The script should open http://localhost:8080/example.html#page1 in your
default/specified browser. You should see the text on the page itself change to read Success!.

File: examples/on-listening/README.md Copy Chapter

onListening

Provides the ability to execute a custom function when webpack-dev-server starts listening for connections on a port.

webpack.config.js

module.exports = {
  // ...
  devServer: {
    onListening: (devServer) => {
      const { port } = devServer.server.address();
      console.log("Listening on port:", port);
    },
  },
};

To run this example use the following command:

npx webpack serve --open

What Should Happen Copy Chapter

1. The script should open http://localhost:8080/ in your default browser.
2. You should see the text on the page itself change to read Success!.
3. Check the terminal output, you should see Listening on port: 8080 in the output.

File: examples/node-false/README.md Copy Chapter

Webpack `node` Option

npx webpack serve --open

What should happen Copy Chapter

1. The script should open http://localhost:8080/ in your default browser.
2. You should see the text on the page itself change to read Success!.

File: examples/multi-compiler/README.md Copy Chapter

Multi Compiler

webpack-dev-server should be able to compile multiple webpack configs.

npx webpack serve --open

What Should Happen Copy Chapter

1. The script should open http://localhost:8080/ in your default browser.
2. You should see the text on the page itself change to read Success!.
3. In app.js write code containing a syntax error and save the file.
4. The page should now refresh and show a full screen error overlay, displaying
   the syntax error.

File: examples/ipc/README.md Copy Chapter

IPC

The Unix socket to listen to (instead of a host).

true Copy Chapter

Setting it to true will listen to a socket at /your-os-temp-dir/webpack-dev-server.sock:

webpack.config.js

module.exports = {
  // ...
  devServer: {
    ipc: true,
  },
};

Usage via CLI:

npx webpack serve --ipc

string Copy Chapter

You can also listen to a different socket with:

webpack.config.js

const path = require("node:path");

module.exports = {
  // ...
  devServer: {
    ipc: path.join(__dirname, "my-socket.sock"),
  },
};

Usage via CLI:

npx webpack serve --ipc ./my-socket.sock

What Should Happen Copy Chapter

1. The script should listen to the socket provided.
2. A proxy server should be created.
3. Go to http://localhost:8080/, you should see the text on the page itself change to read Success!.

File: examples/host-and-port/README.md Copy Chapter

Host and Port Options

You may choose to wish to change the host and port on which webpack-dev-server
will run. The host and port options allow for that.

host Copy Chapter

IPv4 Copy Section

webpack.config.js

module.exports = {
  // ...
  devServer: {
    host: "0.0.0.0",
    port: 5000,
  },
};

Usage via CLI:

npx webpack serve --open --port 5000 --host 0.0.0.0

IPv6 Copy Section

This also works with IPv6

webpack.config.js

module.exports = {
  // ...
  devServer: {
    host: "::",
    port: 5000,
  },
};

Usage via CLI:

npx webpack serve --open --port 5000 --host ::

local-ip Copy Section

Specifying local-ip as host will try to resolve the host option as your local IPv4 address if available, if IPv4 is not available it will try to resolve your local IPv6 address.

module.exports = {
  // ...
  devServer: {
    host: "local-ip",
    port: 5000,
  },
};

Usage via CLI:

npx webpack serve --open --port 5000 --host local-ip

local-ipv4 Copy Section

Specifying local-ipv4 as host will try to resolve the host option as your local IPv4 address.

module.exports = {
  // ...
  devServer: {
    host: "local-ipv4",
    port: 5000,
  },
};

Usage via CLI:

npx webpack serve --open --port 5000 --host local-ipv4

local-ipv6 Copy Section

Specifying local-ipv6 as host will try to resolve the host option as your local IPv6 address.

module.exports = {
  // ...
  devServer: {
    host: "local-ipv6",
    port: 5000,
  },
};

Usage via CLI:

npx webpack serve --open --port 5000 --host local-ipv6

What Should Happen

1. The script should open http://0.0.0.0:5000/ if specifying the IPv4 option,
   or http://[::]:5000/ for IPv6, in your default browser.
2. You should see the text on the page itself change to read Success!.

port Copy Chapter

specific port Copy Section

Tell the server to connect to a specific port with the following:

module.exports = {
  // ...
  devServer: {
    port: 9000,
  },
};

Usage via CLI:

npx webpack serve --open --port 9000

What Should Happen

1. The script should open http://localhost:9000/ in your default browser.
2. You should see the text on the page itself change to read Success!.

auto Copy Section

Specifying auto as port will try to connect the server to the default port 8080 and if not available it will automatically search for another free port.

module.exports = {
  // ...
  devServer: {
    port: "auto",
  },
};

Usage via CLI:

npx webpack serve --open --port auto

What Should Happen

1. The script should open http://localhost:8080/ in your default browser.
2. You should see the text on the page itself change to read Success!.
3. Keep the server open and switch to a new terminal window.
4. Run the script once again.
5. The script should open http://localhost:8081/ (or any other port if it is not free) in your default browser.

File: examples/hmr/only/README.md Copy Chapter

Hot Module Reloading

Hot Module Replacement (HMR) exchanges, adds, or removes modules while an application is running, without a full reload of the page.

only Copy Chapter

Enables Hot Module Replacement without page refresh as a fallback in case of build failures.

webpack.config.js

module.exports = {
  // ...
  devServer: {
    hot: "only",
  },
};

Usage via CLI:

npx webpack serve --open --hot only

What Should Happen Copy Chapter

1. The script should open http://localhost:8080/ in your default browser.
2. In your editor, open example.js and change any part of the innerHTML string.
3. Open the console in your browser's devtools.

In the devtools console you should see:

[webpack-dev-server] App updated. Recompiling...
[webpack-dev-server] App hot update...
[HMR] Checking for updates on the server...
 ⚠️ Ignored an update to unaccepted module ./example.js -> ./app.js
[HMR] Nothing hot Updated.
[HMR] App is up to date.

5. Refresh the page and see the text on the page itself change to match your edits in example.js.

2. Official Technical Reference & Guides (webpack/webpack.js.org) Copy Chapter

File: README.md Copy Chapter

Content Progress Copy Chapter

Now that we've covered much of the backlog of missing documentation, we are
starting to heavily review each section of the site's content to sort and
structure it appropriately. The following issues should provide a pretty good
idea of where things are, and where they are going:

• Guides - Review and Simplify
• Concepts - Review and Organize

We haven't created issues for the other sections yet, but they will be coming
soon. For dev-related work please see General - Updates & Fixes.

Translation Copy Chapter

To help translate this documentation please jump to the translation branch.

Versioning Copy Chapter

Since webpack 4 we have created a subdomain-based archive for older states of documentation
matching older webpack version. Webpack 4's documentation is available at
https://v4.webpack.js.org/ and is deployed from gh-pages branch of v4.webpack.js.org repository

There are various known issues that need fixing (#3366).

Contributing Copy Chapter

Read through the writer's guide if you're interested in editing the
content on this site. See the contributors page to learn how to set up and
start working on the site locally.

License Copy Chapter

The content is available under the Creative Commons BY 4.0 license.

Special Thanks Copy Chapter

If you want to reach us at webpack, contact us and we can arrange something in return for your donations!

Vercel has given us a Pro account.

File: examples/module-federation/README.md Copy Chapter

Module Federation

How to use Copy Chapter

Run the following commands in the root directory.

npm install
npm start

Both app1 and app2 are independently deployed apps:

• app1: http://localhost:3001
• app2: http://localhost:3002

Check out this link below for more examples:

https://github.com/module-federation/module-federation-examples

File: examples/getting-started/README.md Copy Chapter

Getting Started

How to use Copy Chapter

Run the following commands in the root directory.

npm install
npm run build
npm run start

File: repositories/README.md Copy Chapter

webpack documentation repositories

The files in this directory are auto generated from fetch-package-repos.mjs and should not be edited by hand. Any manual changes will be overwritten by the automation next time it runs.

File: src/content/api/cli.mdx Copy Chapter

title: Command Line Interface
sort: 1
contributors:

• anshumanv
• rishabh3112
• snitin315
• evenstensberg
• simon04
• tbroadley
• chenxsan
• rencire
• madhavarshney
• EugeneHlushko
• byzyk
• wizardofhogwarts
• EslamHiko
• smelukov
• anikethsaha
• jamesgeorge007
• burhanuday
  related:
• title: Analyzing Build Statistics
  url: https://survivejs.com/webpack/optimizing-build/analyzing-build-statistics/
• title: Three simple ways to inspect a webpack bundle
  url: https://medium.com/@joeclever/three-simple-ways-to-inspect-a-webpack-bundle-7f6a8fe7195d#.7d2i06mjx
• title: Optimising your application bundle size with webpack
  url: https://hackernoon.com/optimising-your-application-bundle-size-with-webpack-e85b00bab579#.5w5ko08pq
• title: Analysing and minimising the size of client-side bundle with webpack and source-map-explorer
  url: https://medium.com/@nimgrg/analysing-and-minimising-the-size-of-client-side-bundle-with-webpack-and-source-map-explorer-41096559beca#.c3t2srr8x

For proper usage and easier distribution of this configuration, webpack can be configured with webpack.config.js. Any parameters sent to the CLI will map to a corresponding parameter in the configuration file.

Read the installation guide if you don't already have webpack and CLI installed.

W> webpack-cli v7.0.0+ requires node >= v20.9.0, webpack >= v5.101.0, and webpack-dev-server >= v5.0.0.

W> If you want to run webpack using npx please make sure you have webpack-cli installed.

Commands Copy Chapter

webpack-cli offers a variety of commands to make working with webpack easier. By default webpack ships with

Build Copy Section

Run webpack (default command, can be omitted).

npx webpack build [options]

example

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

Init Copy Section

Used to initialize a new webpack project using create-webpack-app.

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

example

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

Alias to:

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

Generation Path

Location of where to generate the configuration. Defaults to process.cwd().

Options

-t, --template

string = 'default'

Name of template to generate.

-f, --force

boolean

To generate a project without questions. When enabled, the default answer for each question will be used.

Templates supported

• --template=default - Default template with basic configuration.
• --template=react - Template with React configuration.
• --template=vue - Template with Vue configuration.
• --template=svelte - Template with Svelte configuration.`

Loader Copy Section

Scaffold a loader.

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

example

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

Output Path

Path to the output directory, e.g. ./loader-name.

Options

-t, --template

string = 'default'

Type of template.

Plugin Copy Section

Scaffold a plugin.

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

example

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

Output Path

Path to the output directory, e.g. ./plugin-name.

Options

-t, --template

string = 'default'

Type of template.

T> See the full documentation of create-webpack-app.

Info Copy Section

Outputs information about your system.

npx webpack info [options]

example

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

Options for info

-a, --additional-package

string

Adds additional packages to the output.

example

npx webpack info --additional-package postcss

-o, --output

string : 'json' | 'markdown'

To get the output in a specified format.

example

npx webpack info --output markdown

Configtest Copy Section

Validate a webpack configuration.

npx webpack configtest [config-path]

example

npx webpack configtest ./webpack.config.js

Config Path

Path to your webpack configuration file. Defaults to ./webpack.config.js.

Serve Copy Section

Run the webpack dev server.

npx webpack serve [options]

example

npx webpack serve --static --open

T> See the full list of options for webpack serve command and related documentation for webpack-dev-server.

Watch Copy Section

Run webpack and watch for files changes.

npx webpack watch [options]

example

npx webpack watch --mode development

Flags Copy Chapter

By default webpack ships with the following flags:

Negated Flags Copy Section

Core Flags Copy Section

Starting CLI v4 and webpack v5, CLI imports the entire configuration schema from webpack core to allow tuning almost every configuration option from the command line.

Here's the list of all the core flags supported by webpack v5 with CLI v4 - link

For example if you want to enable performance hints in your project you'd use this option in configuration, with core flags you can do -

npx webpack --performance-hints warning

Usage Copy Chapter

With configuration file Copy Section

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

See configuration for the options in the configuration file.

Without configuration file Copy Section

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

example

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 -

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

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

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

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

W> The --entry-reset option is required to replace the existing entry option, without it the --entry option will add another entry to the existing 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 -

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

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.

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

npx webpack ./src/index.js ./src/others2.js --output-path dist/

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

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 Copy Chapter

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

'webpack.config',
'.webpack/webpack.config',
'.webpack/webpackfile',

Each base name is resolved against the supported extensions — JavaScript and TypeScript variants (.js, .mjs, .cjs, .ts, .cts, .mts), other supported languages such as .coffee, and, since webpack-cli 7.1.0, the data formats .json5, .yaml/.yml and .toml.

Common Options Copy Chapter

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" to webpack CLI and your configuration file uses development, production will be used.

help Copy Section

List basic commands and flags available on the cli

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

npx webpack --help

# or

npx webpack help

List all supported commands and flags by cli

npx webpack --help=verbose

See help for a specific command or option

npx webpack help --mode

version Copy Section

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:

npx webpack --version

# or

npx webpack version

This will output the following result:

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:

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

config Copy Section

Build source using a configuration file

Specify a different configuration file other than webpack.config.js, which is one of the defaults.

npx webpack --config example.config.js

config-name Copy Section

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:

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:

npx webpack --config-name second

You can also pass multiple values:

npx webpack --config-name first --config-name second

merge Copy Section

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

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

extends Copy Section

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

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

Read more about it in extending configurations.

json Copy Section

Print result of webpack as JSON

npx webpack --json

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

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, or chrisbateman's webpack-visualizer, or th0r's 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 to read more about the stats generated here.

Environment Options Copy Chapter

When the webpack configuration exports a function, an "environment" may be passed to it.

env Copy Section

npx webpack --env production    # env.production = true

The --env argument accepts multiple values:

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

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

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

config-node-env Copy Section

Set process.env.NODE_ENV for your configuration:

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.

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

Configuration Options Copy Chapter

Analyzing Bundle Copy Chapter

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.

npx webpack --analyze

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

Progress Copy Chapter

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

npx webpack --progress

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

npx webpack --progress=profile

Pass CLI arguments to Node.js Copy Chapter

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

NODE_OPTIONS="--max-old-space-size=4096" webpack

Also, you can pass multiple options to Node.js process

NODE_OPTIONS="--max-old-space-size=4096 -r /path/to/preload/file.js" webpack

Exit codes and their meanings Copy Chapter

CLI Environment Variables Copy Chapter

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

WEBPACK_PACKAGE Copy Section

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

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

To use webpack v4.0.0:

npx webpack

To use webpack v5.32.0:

WEBPACK_PACKAGE=webpack-5 npx webpack

Troubleshooting Copy Chapter

TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for ./webpack.config.ts Copy Section

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 enabled (described at TypeStrong/ts-node#1007).

To fix the error above use the following command:

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.

File: src/content/api/compilation-hooks.mdx Copy Chapter

title: Compilation Hooks
group: Plugins
sort: 10
contributors:

• slavafomin
• byzyk
• madhavarshney
• misterdev
• wizardofhogwarts
• EugeneHlushko
• chenxsan
• jamesgeorge007
• snitin315

The Compilation module is used by the Compiler to create new compilations
(or builds). A compilation instance has access to all modules and their
dependencies (most of which are circular references). It is the literal
compilation of all the modules in the dependency graph of an application.
During the compilation phase, modules are loaded, sealed, optimized, chunked,
hashed and restored.

The Compilation class also extends Tapable and provides the following
lifecycle hooks. They can be tapped the same way as compiler hooks:

compilation.hooks.someHook.tap(/* ... */);

As with the compiler, tapAsync and tapPromise may also be available
depending on the type of hook.

W> Since webpack 5, hooks are no longer extendable. Use a WeakMap to add custom hooks.

buildModule Copy Chapter

SyncHook

Triggered before a module build has started, can be used to modify the module.

• Callback Parameters: module

compilation.hooks.buildModule.tap(
  "SourceMapDevToolModuleOptionsPlugin",
  (module) => {
    module.useSourceMap = true;
  },
);

rebuildModule Copy Chapter

SyncHook

Fired before rebuilding a module.

• Callback Parameters: module

failedModule Copy Chapter

SyncHook

Run when a module build has failed.

• Callback Parameters: module error

succeedModule Copy Chapter

SyncHook

Executed when a module has been built successfully.

• Callback Parameters: module

finishModules Copy Chapter

AsyncSeriesHook

Called when all modules have been built without errors.

• Callback Parameters: modules

finishRebuildingModule Copy Chapter

SyncHook

Executed when a module has been rebuilt, in case of both success or with errors.

• Callback Parameters: module

seal Copy Chapter

SyncHook

Fired when the compilation stops accepting new modules.

unseal Copy Chapter

SyncHook

Fired when a compilation begins accepting new modules.

optimizeDependencies Copy Chapter

SyncBailHook

Fired at the beginning of dependency optimization.

• Callback Parameters: modules

afterOptimizeDependencies Copy Chapter

SyncHook

Fired after the dependency optimization.

• Callback Parameters: modules

afterChunks Copy Chapter

SyncHook

The afterChunks hook is invoked following the creation of the chunks and module graph, and prior to their optimization.
This hook provides an opportunity to examine, analyze, and modify the chunk graph if necessary.

Here's an example of how to utilize the compilation.hooks.afterChunks hook.

• Callback Parameters: chunks

optimize Copy Chapter

SyncHook

Triggered at the beginning of the optimization phase.

optimizeModules Copy Chapter

SyncBailHook

Called at the beginning of the module optimization phase. A plugin can tap into this hook to perform optimizations on modules.

• Callback Parameters: modules

afterOptimizeModules Copy Chapter

SyncHook

Called after modules optimization has completed.

• Callback Parameters: modules

optimizeChunks Copy Chapter

SyncBailHook

Called at the beginning of the chunk optimization phase. A plugin can tap into this hook to perform optimizations on chunks.

• Callback Parameters: chunks

afterOptimizeChunks Copy Chapter

SyncHook

Fired after chunk optimization has completed.

• Callback Parameters: chunks

optimizeTree Copy Chapter

AsyncSeriesHook

Called before optimizing the dependency tree. A plugin can tap into this hook to perform a dependency tree optimization.

• Callback Parameters: chunks modules

afterOptimizeTree Copy Chapter

SyncHook

Called after the dependency tree optimization has completed with success.

• Callback Parameters: chunks modules

optimizeChunkModules Copy Chapter

SyncBailHook

Called after the tree optimization, at the beginning of the chunk modules optimization. A plugin can tap into this hook to perform optimizations of chunk modules.

• Callback Parameters: chunks modules

afterOptimizeChunkModules Copy Chapter

SyncHook

Called after the chunkmodules optimization has completed successfully.

• Callback Parameters: chunks modules

shouldRecord Copy Chapter

SyncBailHook

Called to determine whether or not to store records. Returning anything !== false will prevent every other "record" hook from being executed (record, recordModules, recordChunks and recordHash).

reviveModules Copy Chapter

SyncHook

Restore module information from records.

• Callback Parameters: modules records

beforeModuleIds Copy Chapter

SyncHook

Executed before assigning an id to each module.

• Callback Parameters: modules

moduleIds Copy Chapter

SyncHook

Called to assign an id to each module.

• Callback Parameters: modules

optimizeModuleIds Copy Chapter

SyncHook

Called at the beginning of the modules id optimization.

• Callback Parameters: modules

afterOptimizeModuleIds Copy Chapter

SyncHook

Called when the modules id optimization phase has completed.

• Callback Parameters: modules

reviveChunks Copy Chapter

SyncHook

Restore chunk information from records.

• Callback Parameters: chunks records

beforeChunkIds Copy Chapter

SyncHook

Executed before assigning an id to each chunk.

• Callback Parameters: chunks

chunkIds Copy Chapter

SyncHook

Called to assign an id to each chunk.

• Callback Parameters: chunks

optimizeChunkIds Copy Chapter

SyncHook

Called at the beginning of the chunks id optimization phase.

• Callback Parameters: chunks

afterOptimizeChunkIds Copy Chapter

SyncHook

Triggered after chunk id optimization has finished.

• Callback Parameters: chunks

recordModules Copy Chapter

SyncHook

Store module info to the records. This is triggered if shouldRecord returns a truthy value.

• Callback Parameters: modules records

recordChunks Copy Chapter

SyncHook

Store chunk info to the records. This is only triggered if shouldRecord returns a truthy value.

• Callback Parameters: chunks records

beforeModuleHash Copy Chapter

SyncHook

Called before modules are hashed.

afterModuleHash Copy Chapter

syncHook

Called after modules are hashed.

beforeHash Copy Chapter

SyncHook

Called before the compilation is hashed.

afterHash Copy Chapter

SyncHook

Called after the compilation is hashed.

recordHash Copy Chapter

SyncHook

Store information about record hash to the records. This is only triggered if shouldRecord returns a truthy value.

• Callback Parameters: records

record Copy Chapter

SyncHook

Store information about the compilation to the records. This is only triggered if shouldRecord returns a truthy value.

• Callback Parameters: compilation records

beforeModuleAssets Copy Chapter

SyncHook

Executed before module assets creation.

additionalChunkAssets Copy Chapter

SyncHook

W> additionalChunkAssets is deprecated (use the Compilation.hook.processAssets instead and use one of the Compilation.PROCESS_ASSETS_STAGE_* as a stage option)

Create additional assets for the chunks.

• Callback Parameters: chunks

shouldGenerateChunkAssets Copy Chapter

SyncBailHook

Called to determine whether or not generate chunks assets. Returning anything !== false will allow chunk assets generation.

beforeChunkAssets Copy Chapter

SyncHook

Executed before creating the chunks assets.

additionalAssets Copy Chapter

AsyncSeriesHook

W> additionalAssets is deprecated (use the Compilation.hook.processAssets hook instead and use one of the Compilation.PROCESS_ASSETS_STAGE_* as a stage option)

Create additional assets for the compilation. This hook can be used to download
an image, for example:

compilation.hooks.additionalAssets.tapAsync("MyPlugin", (callback) => {
  download("https://img.shields.io/npm/v/webpack.svg", (resp) => {
    if (resp.status === 200) {
      compilation.assets["webpack-version.svg"] = toAsset(resp);
      callback();
    } else {
      callback(
        new Error("[webpack-example-plugin] Unable to download the image"),
      );
    }
  });
});

optimizeChunkAssets Copy Chapter

AsyncSeriesHook

W> optimizeChunkAssets is deprecated (use the Compilation.hook.processAssets instead and use one of the Compilation.PROCESS_ASSETS_STAGE_* as a stage option)

Optimize any chunk assets. The assets are stored in compilation.assets. A
Chunk has a property files which points to all files created by a chunk.
Any additional chunk assets are stored in compilation.additionalChunkAssets.

• Callback Parameters: chunks

Here's an example that adds a banner to each chunk.

compilation.hooks.optimizeChunkAssets.tapAsync(
  "MyPlugin",
  (chunks, callback) => {
    for (const chunk of chunks) {
      for (const file of chunk.files) {
        compilation.assets[file] = new ConcatSource(
          "/**Sweet Banner**/",
          "\n",
          compilation.assets[file],
        );
      }
    }

    callback();
  },
);

afterOptimizeChunkAssets Copy Chapter

SyncHook

W> afterOptimizeChunkAssets is deprecated (use the Compilation.hook.processAssets instead and use one of the Compilation.PROCESS_ASSETS_STAGE_* as a stage option)

The chunk assets have been optimized.

• Callback Parameters: chunks

Here's an example plugin from @boopathi that outputs exactly what went into each chunk.

compilation.hooks.afterOptimizeChunkAssets.tap("MyPlugin", (chunks) => {
  for (const chunk of chunks) {
    console.log({
      id: chunk.id,
      name: chunk.name,
      includes: chunk.getModules().map((module) => module.request),
    });
  }
});

optimizeAssets Copy Chapter

AsyncSeriesHook

W> optimizeAssets is deprecated (use the Compilation.hook.processAssets hook instead)

Optimize all assets stored in compilation.assets.

• Callback Parameters: assets

afterOptimizeAssets Copy Chapter

SyncHook

W> afterOptimizeAssets is deprecated (use the Compilation.hook.afterProcessAssets hook instead)

The assets have been optimized.

• Callback Parameters: assets

processAssets Copy Chapter

AsyncSeriesHook

Asset processing.

Hook parameters:

• name: string — a name of the plugin
• stage: Stage — a stage to tap into (see the list of supported stages below)
• additionalAssets?: true | (assets, [callback]) => (void | Promise<void>) — a callback for additional assets (see below)

Callback parameters:

• assets: { [pathname: string]: Source } — a plain object, where key is the asset's pathname, and the value is data of the asset represented by the Source.

Example:

compilation.hooks.processAssets.tap(
  {
    name: "MyPlugin",
    stage: Compilation.PROCESS_ASSETS_STAGE_ADDITIONS, // see below for more stages
  },
  (assets) => {
    console.log("List of assets and their sizes:");
    for (const [pathname, source] of Object.entries(assets)) {
      console.log(`— ${pathname}: ${source.size()} bytes`);
    }
  },
);

Additional assets Copy Section

In addition to name and stage, you can pass an additionalAssets option which accepts either a value of true or a callback function that receives assets as a first argument:

1. true — run the provided callback again for assets added later by plugins.

   In this mode, the callback will be called multiple times: once for assets added prior to the specified stage, and additional times for assets added by plugins later (on this or next stages).

   js Copy

   compilation.hooks.processAssets.tap(
     {
       name: "MyPlugin",
       stage: Compilation.PROCESS_ASSETS_STAGE_DEV_TOOLING,
       additionalAssets: true,
     },
     (assets) => {
       // this function will be called multiple times with each bulk of assets
     },
   );

2. (assets, [callback]) => (void | Promise<void>) — run the specified callback against assets added by plugins later (on this or next stages). The callback must respect the type of the tap method used (e.g. when used with tapPromise(), it should return a promise).

   js Copy

   compilation.hooks.processAssets.tap(
     {
       name: "MyPlugin",
       stage: Compilation.PROCESS_ASSETS_STAGE_DEV_TOOLING,
       additionalAssets: (assets) => {
         // this function potentially could be called multiple times for assets added on later stages
       },
     },
     (assets) => {
       // this function will be called once with assets added by plugins on prior stages
     },
   );

List of asset processing stages Copy Section

Here's a list of supported stages (in the order of processing):

• PROCESS_ASSETS_STAGE_ADDITIONAL — add additional assets to the compilation.
• PROCESS_ASSETS_STAGE_PRE_PROCESS — basic preprocessing of the assets.
• PROCESS_ASSETS_STAGE_DERIVED — derive new assets from the existing assets.
• PROCESS_ASSETS_STAGE_ADDITIONS — add additional sections to the existing assets e.g. banner or initialization code.
• PROCESS_ASSETS_STAGE_OPTIMIZE — optimize existing assets in a general way.
• PROCESS_ASSETS_STAGE_OPTIMIZE_COUNT — optimize the count of existing assets, e.g. by merging them.
• PROCESS_ASSETS_STAGE_OPTIMIZE_COMPATIBILITY — optimize the compatibility of existing assets, e.g. add polyfills or vendor prefixes.
• PROCESS_ASSETS_STAGE_OPTIMIZE_SIZE — optimize the size of existing assets, e.g. by minimizing or omitting whitespace.
• PROCESS_ASSETS_STAGE_DEV_TOOLING — add development tooling to the assets, e.g. by extracting a source map.
• PROCESS_ASSETS_STAGE_OPTIMIZE_INLINE — optimize the numbers of existing assets, e.g. by inlining assets into other assets.
• PROCESS_ASSETS_STAGE_SUMMARIZE — summarize the list of existing assets.
• PROCESS_ASSETS_STAGE_OPTIMIZE_HASH — optimize the hashes of the assets, e.g. by generating real hashes of the asset content.
• PROCESS_ASSETS_STAGE_OPTIMIZE_TRANSFER — optimize the transfer of existing assets, e.g. by preparing a compressed (gzip) file as separate asset.
• PROCESS_ASSETS_STAGE_ANALYSE — analyze the existing assets.
• PROCESS_ASSETS_STAGE_REPORT — creating assets for the reporting purposes.

Assets info Copy Section

The "asset info" metadata is not automatically provided for this hook. If needed, you will have to resolve this metadata manually using the compilation instance and the provided asset pathname. This will be improved in a future version of the webpack.

Example:

compilation.hooks.processAssets.tap(
  {
    /** … */
  },
  (assets) => {
    for (const [pathname, source] of Object.entries(assets)) {
      const assetInfo = compilation.assetsInfo.get(pathname);
      // @todo: do something with "pathname", "source" and "assetInfo"
    }
  },
);

afterProcessAssets Copy Chapter

SyncHook

Called after the processAssets hook had finished without error.

needAdditionalSeal Copy Chapter

SyncBailHook

Called to determine if the compilation needs to be unsealed to include other files.

afterSeal Copy Chapter

AsyncSeriesHook

Executed right after needAdditionalSeal.

chunkHash Copy Chapter

SyncHook

Triggered to emit the hash for each chunk.

• Callback Parameters: chunk chunkHash

moduleAsset Copy Chapter

SyncHook

Called when an asset from a module was added to the compilation.

• Callback Parameters: module filename

chunkAsset Copy Chapter

SyncHook

Triggered when an asset from a chunk was added to the compilation.

• Callback Parameters: chunk filename

assetPath Copy Chapter

SyncWaterfallHook

Called to determine the path of an asset.

• Callback Parameters: path options

needAdditionalPass Copy Chapter

SyncBailHook

Called to determine if an asset needs to be processed further after being emitted.

childCompiler Copy Chapter

SyncHook

Executed after setting up a child compiler.

• Callback Parameters: childCompiler compilerName compilerIndex

normalModuleLoader Copy Chapter

Since webpack v5 normalModuleLoader hook was removed. Now to access the loader use NormalModule.getCompilationHooks(compilation).loader instead.

statsPreset Copy Chapter

HookMap

This HookMap is like a list of actions that gets triggered when a preset is used. It takes in an options object. When a plugin manages a preset, it should change settings in this object carefully without replacing existing ones.

• Callback Parameters: options context

Here's an illustrative plugin example:

compilation.hooks.statsPreset.for("my-preset").tap("MyPlugin", (options) => {
  if (options.all === undefined) options.all = true;
});

This plugin ensures that for the preset 'my-preset', if the all option is undefined, it defaults to true.

statsNormalize Copy Chapter

SyncHook

This hook is used to transform an options object into a consistent format that can be easily used by subsequent hooks. It also ensures that missing options are set to their default values.

• Callback Parameters: options context

Here's an illustrative plugin example:

compilation.hooks.statsNormalize.tap("MyPlugin", (options) => {
  if (options.myOption === undefined) options.myOption = [];

  if (!Array.isArray(options.myOption)) options.myOptions = [options.myOptions];
});

In this plugin, if the myOption is missing, it sets it to an empty array. Additionally, it ensures that myOption is always an array even if it was originally defined as a single value.

statsFactory Copy Chapter

This hook provides access to the StatsFactory class for specific options.

• Callback Parameters: statsFactory options

StatsFactory.hooks.extract Copy Section

HookMap

• Callback Parameters: object data context

data contains the class. object is an object to which properties should be added. context provides contextual information, such as classes on the path.

Example:

compilation.hooks.statsFactory.tap("MyPlugin", (statsFactory, options) => {
  statsFactory.hooks.extract
    .for("compilation")
    .tap("MyPlugin", (object, compilation) => {
      object.customProperty = MyPlugin.getCustomValue(compilation);
    });
});

StatsFactory.hooks.result Copy Section

HookMap

Called with the result on each level.

• Callback Parameters: result context

statsPrinter Copy Chapter

This hook provides access to the StatsPrinter class for specific options.

• Callback Parameters: statsPrinter options

StatsPrinter.hooks.print Copy Section

HookMap

This hook is called when a part should be printed.

• Callback Parameters: object context

StatsPrinter.hooks.result Copy Section

HookMap

This hook is called for the resulting string for a part.

• Callback Parameters: result context

CssModulesPlugin.getCompilationHooks(compilation) Copy Chapter

When experiments.css is enabled, the internal CssModulesPlugin exposes a set of per-compilation hooks for plugin authors. Access them via the static getCompilationHooks(compilation) method:

const webpack = require("webpack");

class MyCssPlugin {
  apply(compiler) {
    compiler.hooks.thisCompilation.tap("MyCssPlugin", (compilation) => {
      const hooks =
        webpack.css.CssModulesPlugin.getCompilationHooks(compilation);
      // tap into hooks here
    });
  }
}

W> These hooks are only registered when experiments.css is enabled and may evolve while the CSS feature is experimental.

orderModules Copy Section

SyncBailHook<[Chunk, Module[], Compilation], Module[] | undefined>

Called once per CSS source type (CSS imports and CSS modules) with the chunk's modules pre-sorted by full module name. Taps may return an ordered Module[] to override webpack's default import-order topological sort, or return undefined to keep the default order.

The hook is the recommended escape hatch when webpack's topological sort surfaces a Conflicting order between css ... warning that cannot be resolved by restructuring imports. Returning the pre-sorted array (or any deterministic order) lets the build pick a stable order without changing application code.

• Callback Parameters: chunk modules compilation

const webpack = require("webpack");

class CssOrderByPathPlugin {
  apply(compiler) {
    compiler.hooks.thisCompilation.tap(
      "CssOrderByPathPlugin",
      (compilation) => {
        const hooks =
          webpack.css.CssModulesPlugin.getCompilationHooks(compilation);

        // Modules arrive pre-sorted by full module name; return as-is to
        // enforce a deterministic file-path order across rebuilds and
        // side-step the conflicting-order warning.
        hooks.orderModules.tap(
          "CssOrderByPathPlugin",
          (_chunk, modules) => modules,
        );
      },
    );
  }
}

The hook is a SyncBailHook, so the first tap to return a non-undefined value wins. Subsequent taps are not invoked for that call.

HtmlModulesPlugin.getCompilationHooks(compilation) Copy Chapter

When experiments.html is enabled, the internal HtmlModulesPlugin exposes a set of per-compilation hooks for injecting and transforming the emitted HTML pages. Access them via the static getCompilationHooks(compilation) method:

const webpack = require("webpack");

class MyHtmlPlugin {
  apply(compiler) {
    compiler.hooks.thisCompilation.tap("MyHtmlPlugin", (compilation) => {
      const hooks =
        webpack.html.HtmlModulesPlugin.getCompilationHooks(compilation);
      // tap into hooks here
    });
  }
}

W> These hooks are only registered when experiments.html is enabled and may evolve while the HTML feature is experimental.

injectTags Copy Section

AsyncSeriesWaterfallHook<[HtmlTagDescriptor[], { outputName, html }]>

Called with the list of extra tags to inject into each page (initially empty) plus the current HTML. Push descriptors and return the list; webpack serializes and places them. It runs before output.html.csp, so injected inline <script> / <style> tags are hashed like the page's own.

Each HtmlTagDescriptor accepts:

• tag (string): tag name, e.g. 'script' / 'link' / 'meta'.
• attrs (object): attributes; true renders a bare boolean attribute, false / undefined omits it.
• children (string): inner content (ignored for void elements like <link> / <meta>).
• injectTo ('head' | 'body' | 'head-prepend' | 'body-prepend'): placement, defaults to 'head'.
• voidTag (boolean): force a void element (no closing tag); inferred from the tag name when omitted.

hooks.injectTags.tap("MyHtmlPlugin", (tags) => {
  tags.push({
    tag: "meta",
    attrs: { name: "theme-color", content: "#2b3a42" },
  });
  return tags;
});

transformTags Copy Section

AsyncSeriesHook<[HtmlMutableTag[], { outputName, html }]>

Called with the page's existing <script> / <link> / <style> / <meta> tags (webpack's own and any injected) as mutable descriptors. Mutate attrs (add a nonce / data-* attribute, switch defer and async, ...), set remove: true, or change injectTo to move a tag between <head> and ``; webpack rewrites the changed tags. Add new tags with injectTags instead, and don't reorder the array itself.

transformHtml Copy Section

AsyncSeriesWaterfallHook<[string, { outputName: string }]>

Called with each emitted page's final HTML (all placeholders resolved) just before it is written. Return the (possibly transformed) HTML, e.g. to minify it:

hooks.transformHtml.tapPromise("MyHtmlPlugin", async (html, { outputName }) =>
  html.replace("", "..."),
);

htmlEmitted Copy Section

AsyncSeriesHook<[{ outputName: string }]>

Called once each page's HTML asset has been finalized — a post-emit notification.

File: src/content/api/compilation-object.mdx Copy Chapter

title: Compilation Object
group: Objects
sort: 14
contributors:

• EugeneHlushko
• wizardofhogwarts
• jamesgeorge007
• snitin315

The Compilation object has many methods and hooks available. On this page, we will list the available methods and properties.

compilation object methods Copy Chapter

getStats Copy Section

function

Returns Stats object for the current compilation.

addModule Copy Section

function (module, callback)

Adds a module to the current compilation.

Parameters:

• module - module to be added
• callback - a callback after the module has been added

getModule Copy Section

function (module)

Fetches a module from a compilation by its identifier.

Parameters:

• module - module to be fetched. The identifier is extracted from the module by the compilation using module.identifier() method.

findModule Copy Section

function (module)

Attempts to search for a module by its identifier.

Parameters:

• module - module to be searched for. The identifier is extracted from the module by the compilation using module.identifier() method.

buildModule Copy Section

function (module, optional, origin, dependencies)

Builds the given module.

Parameters:

• module - the module to be built.
• optional - optional flag.
• origin - origin module from which this module build was requested.
• dependencies - optional dependencies of the module to be built.

processModuleDependencies Copy Section

function (module, callback)

Process the given module dependencies.

Parameters:

• module - module to be processed for the dependencies.
• callback - function to be invoked when dependencies of the module had been processed.

addEntry Copy Section

function (context, entry, name, callback)

Adds an entry to the compilation.

Parameters:

• context - context path for entry.
• entry - entry dependency.
• name - the name of entry.
• callback - function to be invoked when addEntry finishes.

rebuildModule Copy Section

function (module, thisCallback)

Triggers a re-build of the module.

Parameters:

• module - module to be rebuilt.
• thisCallback - function to be invoked when the module finishes rebuilding.

finish Copy Section

function (callback)

Finishes compilation and invokes the given callback.

Parameters:

• callback - function to be invoked when the compilation has been finished.

seal Copy Section

function (callback)

Seals the compilation.

Parameters:

• callback - function to be invoked when the compilation has been sealed.

unseal Copy Section

function

Unseals the compilation.

Parameters:

• callback - function to be invoked when the compilation has been unsealed.

reportDependencyErrorsAndWarnings Copy Section

function (module, blocks)

Adds errors and warnings of the given module to the compilation errors and warnings.

Parameters:

• module - the module whose errors and warnings are to be reported.
• blocks - a set of dependency blocks to report from.

addChunkInGroup Copy Section

function (groupOptions, module, loc, request)

Adds module to an existing chunk group or creates a new one. Returns a chunkGroup.

Parameters:

• groupOptions - options for the chunk group.
• module - a module that references the chunk group.
• loc - the location from which the chunk group is referenced (inside of the module).
• request - the request from which the chunk group is referenced.

addChunk Copy Section

function (name)

Creates and adds a new chunk to the compilation.chunks. Returns that chunk.

Parameters:

• name - the name of the chunk.

assignDepth Copy Section

function (module)

Assigns depth to the given module and its dependency blocks recursively.

Parameters:

• module - the module to assign depth to.

getDependencyReference Copy Section

function (module, dependency)

Returns the reference to the dependency from a given module.

Parameters:

• module - the module at question.
• dependency - the dependency to get reference to.

processDependenciesBlocksForChunkGroups Copy Section

function (inputChunkGroups)

Creates the Chunk graph from the Module graph. The process is done in two phases. Phase one: traverse the module graph and build a basic chunks graph in chunkDependencies. Phase two: traverse every possible way through the basic chunk graph and track the available modules. While traversing, processDependenciesBlocksForChunkGroups connects chunks with each other and Blocks with Chunks. It stops traversing when all modules for a chunk are already available and it doesn't connect unneeded chunks.

Parameters:

• inputChunkGroups - chunk groups that are processed.

removeReasonsOfDependencyBlock Copy Section

function (module, block)

Removes relation of the module to the dependency block.

Parameters:

• module - a module relationship to be removed.
• block - dependency block.

patchChunksAfterReasonRemoval Copy Section

function (module, chunk)

Patches ties of module and chunk after removing dependency reasons. Called automatically by removeReasonsOfDependencyBlock.

Parameters:

• module - a module to patch tie.
• chunk - a chunk to patch tie.

removeChunkFromDependencies Copy Section

function (block, chunk)

Removes given chunk from a dependencies block module and chunks after removing dependency reasons. Called automatically by removeReasonsOfDependencyBlock.

Parameters:

• block - block tie for Chunk.
• chunk - a chunk to remove from dependencies.

sortItemsWithChunkIds Copy Section

function

summarizeDependencies Copy Section

function

createHash Copy Section

function

createModuleAssets Copy Section

function

createChunkAssets Copy Section

function

getPath Copy Section

function (filename, data)

Returns the interpolated path.

Parameters:

• filename - used to get asset path with hash.
• data - data object.

getPathWithInfo Copy Section

function (filename, data)

Returns interpolated path and asset information.

Parameters:

• filename - used to get asset path with hash.
• data - data object.

createChildCompiler Copy Section

function (name, outputOptions, plugins)

Allows running another instance of webpack inside of webpack. However, as a child with different settings and configurations applied. It copies all hooks and plugins from the parent (or top-level compiler) and creates a child Compiler instance. Returns the created Compiler.

Parameters:

• name - name for the child Compiler.
• outputOptions - output options object.
• plugins - webpack plugins that will be applied.

checkConstraints Copy Section

function

emitAsset Copy Section

function (file, source, assetInfo = {})

Parameters:

• file - file name of the asset
• source - the source of the asset
• assetInfo - additional asset information

updateAsset Copy Section

function (file, newSourceOrFunction, assetInfoUpdateOrFunction)

Parameters:

• file - file name of the asset
• newSourceOrFunction - new asset source or function converting old to new
• assetInfoUpdateOrFunction - new asset info or function converting old to new

deleteAsset Copy Section

function (file)

Parameters:

• file - file name of the asset

getAssets Copy Section

function

Returns array of all assets under the current compilation.

getAsset Copy Section

function (name)

Parameters:

• name - the name of the asset to return

File: src/content/api/compiler-hooks.mdx Copy Chapter

title: Compiler Hooks
group: Plugins
sort: 9
contributors:

• rishantagarwal
• byzyk
• madhavarshney
• misterdev
• EugeneHlushko
• superburrito
• chenxsan
• snitin315

The Compiler module is the main engine that creates a compilation instance
with all the options passed through the CLI or Node API. It extends the
Tapable class in order to register and call plugins. Most user-facing plugins
are first registered on the Compiler.

When developing a plugin for webpack, you might want to know where each hook is called. To learn this, search for hooks.<hook name>.call across the webpack source.

W> Since webpack 5, hooks are no longer extendable. Use a WeakMap to add custom hooks.

Watching Copy Chapter

The Compiler supports watching which monitors the file
system and recompiles as files change. When in watch mode, the compiler will
emit the additional events such as watchRun, watchClose, and invalid.
This is typically used in development, usually under
the hood of tools like webpack-dev-server, so that the developer doesn't
need to re-compile manually every time. Watch mode can also be entered via the
CLI.

Hooks Copy Chapter

The following lifecycle hooks are exposed by the compiler and can be accessed
as such:

compiler.hooks.someHook.tap("MyPlugin", (params) => {
  /* ... */
});

Depending on the hook type, tapAsync and tapPromise may also be available.

For the description of hook types, see the Tapable docs.

environment Copy Section

SyncHook

Called while preparing the compiler environment, right after initializing the plugins in the configuration file.

afterEnvironment Copy Section

SyncHook

Called right after the environment hook, when the compiler environment setup is complete.

entryOption Copy Section

SyncBailHook

Called after the entry configuration from webpack options has been processed.

• Callback Parameters: context, entry

compiler.hooks.entryOption.tap("MyPlugin", (context, entry) => {
  /* ... */
});

afterPlugins Copy Section

SyncHook

Called after setting up initial set of internal plugins.

• Callback Parameters: compiler

afterResolvers Copy Section

SyncHook

Triggered after resolver setup is complete.

• Callback Parameters: compiler

validate Copy Section

SyncHook

Called to register validation work for webpack configuration, plugins, and loaders. Plugin authors can tap this hook and use compiler.validate(...) to participate in webpack's built-in validation flow.

W> The hook is always available. compiler.validate(...) skips validation when validate: false is set. With experiments.futureDefaults, webpack keeps validation enabled by default in development and disables it by default in production.

compiler.hooks.validate.tap("MyPlugin", () => {
  compiler.validate(
    () => require("./schema/MyPlugin.json"),
    options,
    { name: "My Plugin", baseDataPath: "options" },
    (validatedOptions) => require("./schema/MyPlugin.check")(validatedOptions),
  );
});

initialize Copy Section

SyncHook

Called when a compiler object is initialized.

beforeRun Copy Section

AsyncSeriesHook

Adds a hook right before running the compiler.

• Callback Parameters: compiler

run Copy Section

AsyncSeriesHook

Hook into the compiler before it begins reading records.

• Callback Parameters: compiler

watchRun Copy Section

AsyncSeriesHook

Executes a plugin during watch mode after a new compilation is triggered but before the compilation is actually started.

• Callback Parameters: compiler

normalModuleFactory Copy Section

SyncHook

Called after a NormalModuleFactory is created.

• Callback Parameters: normalModuleFactory

contextModuleFactory Copy Section

SyncHook

Runs a plugin after a ContextModuleFactory is created.

• Callback Parameters: contextModuleFactory

beforeCompile Copy Section

AsyncSeriesHook

Executes a plugin after compilation parameters are created.

• Callback Parameters: compilationParams

The compilationParams variable is initialized as follows:

compilationParams = {
  normalModuleFactory,
  contextModuleFactory,
};

This hook can be used to add/modify the compilation parameters:

compiler.hooks.beforeCompile.tapAsync("MyPlugin", (params, callback) => {
  params["MyPlugin - data"] = "important stuff my plugin will use later";
  callback();
});

compile Copy Section

SyncHook

Called right after beforeCompile, before a new compilation is created. This hook is not copied to child compilers.

• Callback Parameters: compilationParams

thisCompilation Copy Section

SyncHook

Executed while initializing the compilation, right before emitting the compilation event. This hook is not copied to child compilers.

• Callback Parameters: compilation, compilationParams

compilation Copy Section

SyncHook

Runs a plugin after a compilation has been created.

• Callback Parameters: compilation, compilationParams

make Copy Section

AsyncParallelHook

Executed before finishing the compilation. This hook is not copied to child compilers.

• Callback Parameters: compilation

afterCompile Copy Section

AsyncSeriesHook

Called after finishing and sealing the compilation.

• Callback Parameters: compilation

shouldEmit Copy Section

SyncBailHook

Called before emitting assets. Should return a boolean telling whether to emit.

• Callback Parameters: compilation

compiler.hooks.shouldEmit.tap(
  "MyPlugin",
  (compilation) =>
    // return true to emit the output, otherwise false
    true,
);

emit Copy Section

AsyncSeriesHook

Executed right before emitting assets to output dir. This hook is not copied to child compilers.

• Callback Parameters: compilation

afterEmit Copy Section

AsyncSeriesHook

Called after emitting assets to output directory. This hook is not copied to child compilers.

• Callback Parameters: compilation

assetEmitted Copy Section

AsyncSeriesHook

Executed when an asset has been emitted. Provides access to information about the emitted asset, such as its output path and byte content.

• Callback Parameters: file, info

For example, you may access the asset's content buffer via info.content:

compiler.hooks.assetEmitted.tap(
  "MyPlugin",
  (file, { content, source, outputPath, compilation, targetPath }) => {
    console.log(content); // 
  },
);

done Copy Section

AsyncSeriesHook

Executed when the compilation has completed. This hook is not copied to child compilers.

• Callback Parameters: stats

additionalPass Copy Section

AsyncSeriesHook

This hook allows you to do a one more additional pass of the build.

failed Copy Section

SyncHook

Called if the compilation fails.

• Callback Parameters: error

invalid Copy Section

SyncHook

Executed when a watching compilation has been invalidated. This hook is not copied to child compilers.

• Callback Parameters: fileName, changeTime

watchClose Copy Section

SyncHook

Called when a watching compilation has stopped.

shutdown Copy Section

AsyncSeriesHook

Called when the compiler is closing.

infrastructureLog Copy Section

SyncBailHook

Allows to use infrastructure logging when enabled in the configuration via infrastructureLogging option.

• Callback Parameters: name, type, args

log Copy Section

SyncBailHook

Allows to log into stats when enabled, see stats.logging, stats.loggingDebug and stats.loggingTrace options.

• Callback Parameters: origin, logEntry

File: src/content/api/contextmodulefactory-hooks.mdx Copy Chapter

title: ContextModuleFactory Hooks
group: Plugins
sort: 11
contributors:

• iguessitsokay

The ContextModuleFactory module is used by the Compiler to generate dependencies from webpack specific require.context API. It resolves the requested directory, generates requests for each file and filters against passed regExp. Matching dependencies then passes through NormalModuleFactory.

The ContextModuleFactory class extends Tapable and provides the following
lifecycle hooks. They can be tapped the same way as compiler hooks:

ContextModuleFactory.hooks.someHook.tap(/* ... */);

As with the compiler, tapAsync and tapPromise may also be available
depending on the type of hook.

beforeResolve Copy Chapter

AsyncSeriesWaterfallHook

Called before resolving the requested directory. The request can be ignored by returning false.

• Callback Parameters: data

afterResolve Copy Chapter

AsyncSeriesWaterfallHook

Called after the requested directory resolved.

• Callback Parameters: data

contextModuleFiles Copy Chapter

SyncWaterfallHook

Called after directory contents are read. On recursive mode, calls for each sub-directory as well. Callback parameter is an array of all file and folder names in each directory.

• Callback Parameters: fileNames

alternativeRequests Copy Chapter

AsyncSeriesWaterfallHook

Called for each file after the request is created but before filtering against regExp.

• Callback Parameters: request options

File: src/content/api/hot-module-replacement.mdx Copy Chapter

title: Hot Module Replacement
sort: 4
contributors:

• sokra
• skipjack
• tbroadley
• byzyk
• wizardofhogwarts
• snitin315
  related:
• title: Concepts - Hot Module Replacement
  url: /concepts/hot-module-replacement
• title: Guides - Hot Module Replacement
  url: /guides/hot-module-replacement

If Hot Module Replacement has been enabled via the HotModuleReplacementPlugin, its interface will be exposed under the module.hot property as well as import.meta.webpackHot property. Note that only import.meta.webpackHot can be used in strict ESM.

Typically, users will check to see if the interface is accessible, then begin working with it. As an example, here's how you might accept an updated module:

if (module.hot) {
  module.hot.accept("./library.js", () => {
    // Do something with the updated library module...
  });
}

// or
if (import.meta.webpackHot) {
  import.meta.webpackHot.accept("./library.js", () => {
    // Do something with the updated library module…
  });
}

The following methods are supported...

Module API Copy Chapter

accept Copy Section

Accept updates for the given dependencies and fire a callback to react to those updates, in addition, you can attach an optional error handler:

module.hot.accept(
  dependencies, // Either a string or an array of strings
  callback, // Function to fire when the dependencies are updated
  errorHandler, // (err, {moduleId, dependencyId}) => {}
);

// or
import.meta.webpackHot.accept(
  dependencies, // Either a string or an array of strings
  callback, // Function to fire when the dependencies are updated
  errorHandler, // (err, {moduleId, dependencyId}) => {}
);

When using ESM import all imported symbols from dependencies are automatically updated. Note: The dependency string must match exactly with the from string in the import. In some cases callback can even be omitted. Using require() in the callback doesn't make sense here.

When using CommonJS you need to update dependencies manually by using require() in the callback. Omitting the callback doesn't make sense here.

errorHandler for accept

(err, {moduleId, dependencyId}) => {}

• err: the error thrown by the callback in second argument or during dependency execution when using ESM dependencies.
• moduleId: the current module id.
• dependencyId: the module id of the (first) changed dependency.

accept (self) Copy Section

Accept updates for itself.

module.hot.accept(
  errorHandler, // Function to handle errors when evaluating the new version
);

// or
import.meta.webpackHot.accept(
  errorHandler, // Function to handle errors when evaluating the new version
);

When this module or dependencies are updated, this module can be disposed and re-evaluated without informing parents. This makes sense if this module has no exports (or exports are updated in another way).

The errorHandler is fired when the evaluation of this module (or dependencies) has thrown an exception.

errorHandler for self accept

(err, {moduleId, module}) => {}

• err: the error when evaluating the new version.
• moduleId: the current module id.
• module: the current module instance.
  • module.hot: allow to use the HMR API of the errored module instance. A common scenario is to self accept it again. It also makes sense to add a dispose handler to pass data along. Note that the errored module might be already partially executed, so make sure to not get into a inconsistent state. You can use module.hot.data to store partial state.
  • module.exports: can be overridden, but be careful since property names might be mangled in production mode.

decline Copy Section

Reject updates for the given dependencies forcing the update to fail with a 'decline' code.

module.hot.decline(
  dependencies, // Either a string or an array of strings
);

// or
import.meta.webpackHot.decline(
  dependencies, // Either a string or an array of strings
);

Flag a dependency as not-update-able. This makes sense when changing exports of this dependency can't be handled or handling is not implemented yet. Depending on your HMR management code, an update to these dependencies (or unaccepted dependencies of it) usually causes a full-reload of the page.

decline (self) Copy Section

Reject updates for itself.

module.hot.decline();

// or
import.meta.webpackHot.decline();

Flag this module as not-update-able. This makes sense when this module has irreversible side-effects, or HMR handling is not implemented for this module yet. Depending on your HMR management code, an update to this module (or unaccepted dependencies) usually causes a full-reload of the page.

dispose (or addDisposeHandler) Copy Section

Add a handler which is executed when the current module code is replaced. This should be used to remove any persistent resource you have claimed or created. If you want to transfer state to the updated module, add it to the given data parameter. This object will be available at module.hot.data after the update.

module.hot.dispose((data) => {
  // Clean up and pass data to the updated module...
});

// or
import.meta.webpackHot.dispose((data) => {
  // Clean up and pass data to the updated module...
});

invalidate Copy Section

Calling this method will invalidate the current module, which disposes and recreates it when the HMR update is applied. This bubbles like a normal update of this module. invalidate can't be self-accepted by this module.

When called during the idle state, a new HMR update will be created containing this module. HMR will enter the ready state.

When called during the ready or prepare state, this module will be added to the current HMR update.

When called during the check state, this module will be added to the update when an update is available. If no update is available it will create a new update. HMR will enter the ready state.

When called during the dispose or apply state, HMR will pick it up after getting out of those states.

Use Cases

Conditional Accepting

A module can accept a dependency, but can call invalidate when the change of the dependency is not handleable:

import { processX, processY } from "anotherDep";
import { x, y } from "./dep";

const oldY = y;

processX(x);

export default processY(y);

module.hot.accept("./dep", () => {
  if (y !== oldY) {
    // This can't be handled, bubble to parent
    module.hot.invalidate();
    return;
  }
  // This can be handled
  processX(x);
});

Conditional self accept

A module can self-accept itself, but can invalidate itself when the change is not handleable:

const VALUE = "constant";

export default VALUE;

if (
  module.hot.data &&
  module.hot.data.value &&
  module.hot.data.value !== VALUE
) {
  module.hot.invalidate();
} else {
  module.hot.dispose((data) => {
    data.value = VALUE;
  });
  module.hot.accept();
}

Triggering custom HMR updates

{/* eslint-disable no-eval */}

const moduleId = chooseAModule();
const code = __webpack_modules__[moduleId].toString();
__webpack_modules__[moduleId] = eval(`(${makeChanges(code)})`);
if (require.cache[moduleId]) {
  require.cache[moduleId].hot.invalidate();
  module.hot.apply();
}

T> When invalidate is called, the dispose handler will be eventually called and fill module.hot.data. If dispose handler is not registered, an empty object will be supplied to module.hot.data.

W> Do not get caught in an invalidate loop, by calling invalidate again and again. This will result in stack overflow and HMR entering the fail state.

removeDisposeHandler Copy Section

Remove the handler added via dispose or addDisposeHandler.

module.hot.removeDisposeHandler(callback);

// or
import.meta.webpackHot.removeDisposeHandler(callback);

Management API Copy Chapter

status Copy Section

Retrieve the current status of the hot module replacement process.

module.hot.status(); // Will return one of the following strings...

// or
import.meta.webpackHot.status();

check Copy Section

Test all loaded modules for updates and, if updates exist, apply them.

module.hot
  .check(autoApply)
  .then((outdatedModules) => {
    // outdated modules...
  })
  .catch((error) => {
    // catch errors
  });

// or
import.meta.webpackHot
  .check(autoApply)
  .then((outdatedModules) => {
    // outdated modules...
  })
  .catch((error) => {
    // catch errors
  });

The autoApply parameter can either be a boolean or options to pass to the apply method when called.

apply Copy Section

Continue the update process (as long as module.hot.status() === 'ready').

module.hot
  .apply(options)
  .then((outdatedModules) => {
    // outdated modules...
  })
  .catch((error) => {
    // catch errors
  });

// or
import.meta.webpackHot
  .apply(options)
  .then((outdatedModules) => {
    // outdated modules...
  })
  .catch((error) => {
    // catch errors
  });

The optional options object can include the following properties:

• ignoreUnaccepted (boolean): Ignore changes made to unaccepted modules.
• ignoreDeclined (boolean): Ignore changes made to declined modules.
• ignoreErrored (boolean): Ignore errors thrown in accept handlers, error handlers and while reevaluating module.
• onDeclined (function(info)): Notifier for declined modules
• onUnaccepted (function(info)): Notifier for unaccepted modules
• onAccepted (function(info)): Notifier for accepted modules
• onDisposed (function(info)): Notifier for disposed modules
• onErrored (function(info)): Notifier for errors

The info parameter will be an object containing some of the following values:

{
  type: 'self-declined' | 'declined' |
        'unaccepted' | 'accepted' |
        'disposed' | 'accept-errored' |
        'self-accept-errored' | 'self-accept-error-handler-errored',
  moduleId: 4, // The module in question.
  dependencyId: 3, // For errors: the module id owning the accept handler.
  chain: [1, 2, 3, 4], // For declined/accepted/unaccepted: the chain from where the update was propagated.
  parentId: 5, // For declined: the module id of the declining parent
  outdatedModules: [1, 2, 3, 4], // For accepted: the modules that are outdated and will be disposed
  outdatedDependencies: { // For accepted: The location of accept handlers that will handle the update
    5: [4]
  },
  error: new Error(...), // For errors: the thrown error
  originalError: new Error(...) // For self-accept-error-handler-errored:
                                // the error thrown by the module before the error handler tried to handle it.
}

addStatusHandler Copy Section

Register a function to listen for changes in status.

module.hot.addStatusHandler((status) => {
  // React to the current status...
});

// or
import.meta.webpackHot.addStatusHandler((status) => {
  // React to the current status...
});

Bear in mind that when the status handler returns a Promise, the HMR system will wait for the Promise to resolve before continuing.

removeStatusHandler Copy Section

Remove a registered status handler.

module.hot.removeStatusHandler(callback);

// or
import.meta.webpackHot.removeStatusHandler(callback);