Configuration

Out of the box, webpack won't require you to use a configuration file. However, it will assume the entry point of your project is src/index.js and will output the result in dist/main.js minified and optimized for production.

Usually, your projects will need to extend this functionality, for this you can create a webpack.config.js file in the root folder and webpack will automatically use it.

All the available configuration options are specified below.

Use a different configuration file

If for some reason you want to use a different configuration file depending on certain situations, you can change this via command line by using the --config flag.

package.json

"scripts": {
  "build": "webpack --config prod.config.js"
}

Set up a new webpack project

Webpack has a huge set of options which might be overwhelming to you, please take advantage of webpack-cli starting from version v6.0.0 new tool create-webpack-app which could rapidly generate webpack application with specific configuration files for your project requirements, it will ask you a couple of questions before creating a configuration file.

npx create-webpack-app [command] [options]

npx might prompt you to install create-webpack-app if it is not yet installed in the project or globally. You might also get additional packages installed to your project depending on the choices you've made during the new webpack application generation.

$ npx create-webpack-app init

Need to install the following packages:
create-webpack-app@2.0.0
Ok to proceed? (y)

? Which of the following JS solutions do you want to use? Typescript
? Do you want to use webpack-dev-server? Yes
? Do you want to simplify the creation of HTML files for your bundle? Yes
? Do you want to add PWA support? No
? Which of the following CSS solutions do you want to use? CSS only
? Will you be using PostCSS in your project? Yes
? Do you want to extract CSS for every file? Only for Production
? Which package manager do you want to use? npm
[create-webpack] ℹ️ Initializing a new Webpack project
...
...
...
[create-webpack] ✅ Project dependencies installed successfully!
[create-webpack] ✅ Project has been initialised with webpack!

Configuration Languages

Webpack accepts configuration files written in multiple programming and data languages, so you can author your config in whichever format suits your project — JavaScript, TypeScript, CoffeeScript, or a plain data file like JSON5, YAML or TOML.

defineConfig

defineConfig is a helper exported from webpack that gives editors type-checking and autocomplete for your configuration without any extra type annotations. It is an identity function (a no-op at runtime that simply returns the config you pass in), so it works in plain JavaScript configs too.

webpack.config.js

const { defineConfig } = require("webpack");

module.exports = defineConfig({
  mode: "none",
});

It accepts every shape webpack-cli can load: a single configuration object, an array of configurations (multi-compiler), a function returning either of those, an array of such functions, or a Promise resolving to any of them.

const { defineConfig } = require("webpack");

module.exports = defineConfig((env, argv) => ({
  mode: argv.mode ?? "development",
  // ...
}));

TypeScript

To write the webpack configuration in TypeScript, you would first install the necessary dependencies, i.e., TypeScript and the relevant type definitions from the DefinitelyTyped project:

npm install --save-dev typescript ts-node @types/node
# and, if using webpack-dev-server < v4.7.0
npm install --save-dev @types/webpack-dev-server

and then proceed to write your configuration:

webpack.config.ts

import path from "node:path";
import { fileURLToPath } from "node:url";

import webpack from "webpack";
// in case you run into any typescript error when configuring `devServer`
import "webpack-dev-server";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const config: webpack.Configuration = {
  mode: "production",
  entry: "./foo.js",
  output: {
    path: path.resolve(__dirname, "dist"),
    filename: "foo.bundle.js",
  },
};

export default config;

tsconfig.json

{
  "compilerOptions": {
    "module": "esnext",
    "moduleResolution": "bundler",

    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "resolveJsonModule": true,
    "isolatedModules": true,

    // Allows you to write `import ... from './file.ts';`
    "rewriteRelativeImportExtensions": true
  }
}

The above sample assumes version >= 2.7 or newer of TypeScript is used with the new esModuleInterop and allowSyntheticDefaultImports compiler options in your tsconfig.json file.

We support configuration in both CommonJS and ESM format.

Starting with v22.18.0 Node.js supports built-in type stripping, so the additional settings described below are only required for older versions.

To enable the transformation of non erasable TypeScript syntax, which requires JavaScript code generation, such as enum declarations, parameter properties use the flag --experimental-transform-types.

If you are using an older version of Node.js that does not support the typescript format, or want to set module in compilerOptions in tsconfig.json to commonjs there are three solutions to this issue:

• Modify tsconfig.json.
• Modify tsconfig.json and add settings for ts-node.
• Install tsconfig-paths.

The first option is to open your tsconfig.json file and look for compilerOptions. Set target to "ES5" and module to "CommonJS" (or completely remove the module option).

The second option is to add settings for ts-node:

You can keep "module": "ESNext" for tsc, and if you use webpack, or another build tool, set an override for ts-node. ts-node config

{
  "compilerOptions": {
    "module": "ESNext"
  },
  "ts-node": {
    "compilerOptions": {
      "module": "CommonJS"
    }
  }
}

The third option is to install the tsconfig-paths package:

npm install --save-dev tsconfig-paths

And create a separate TypeScript configuration specifically for your webpack configs:

tsconfig-for-webpack-config.json

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es5",
    "esModuleInterop": true
  }
}

Then set the environment variable process.env.TS_NODE_PROJECT provided by tsconfig-paths like so:

package.json

{
  "scripts": {
    "build": "cross-env TS_NODE_PROJECT=\"tsconfig-for-webpack-config.json\" webpack"
  }
}

CoffeeScript

Similarly, to use CoffeeScript, you would first install the necessary dependencies:

npm install --save-dev coffeescript

and then proceed to write your configuration:

webpack.config.coffee

import path from 'node:path'
import { fileURLToPath } from 'node:url'
import webpack from 'webpack'

__filename = fileURLToPath(import.meta.url)
__dirname = path.dirname(__filename)

config =
  mode: 'production'
  entry: './src/index.html'
  experiments:
    html: true
  output:
    path: path.resolve(__dirname, 'dist')
    filename: 'my-first-webpack.bundle.js'
  module:
    rules: [
      {
        test: /\.(js|jsx)$/
        use: 'babel-loader'
      }
    ]
  plugins: [
    new webpack.ProgressPlugin()
  ]

export default config

Babel and JSX

In the example below JSX (React JavaScript Markup) and Babel are used, to create a JSON configuration that webpack can understand.

Courtesy of Jason Miller

First, install the necessary dependencies:

npm install --save-dev babel-register jsxobj babel-preset-es2015

.babelrc

{
  "presets": ["es2015"]
}

webpack.config.babel.js

import jsxobj from "jsxobj";

// example of an imported plugin
const CustomPlugin = (config) => ({
  ...config,
  name: "custom-plugin",
});

export default (
  <webpack target="web" watch mode="production">
    <entry path="src/index.js" />
    <resolve>
      <alias
        {...{
          react: "preact-compat",
          "react-dom": "preact-compat",
        }}
      />
    </resolve>
    <plugins>
      <CustomPlugin foo="bar" />
    </plugins>
  </webpack>
);

Data formats (JSON5, YAML and TOML)

When your configuration is purely static data — no functions, no process.env reads, no computed values — you can write it as a data file instead of JavaScript. webpack-cli parses the following extensions directly:

The parser is not bundled with webpack-cli — install the one your format needs as a dev dependency. If it is missing, webpack-cli stops and tells you exactly which package to install.

npm install --save-dev json5
# or
npm install --save-dev js-yaml
# or
npm install --save-dev toml

Point --config at the file, or name it so it is picked up as a default config (e.g. webpack.config.json5):

npx webpack --config webpack.config.toml

webpack.config.json5

{
  // JSON5 allows comments, unquoted keys and trailing commas
  mode: "production",
  entry: "./src/index.js",
  output: {
    filename: "bundle.js",
  },
}

webpack.config.yaml

mode: production
entry: ./src/index.js
output:
  filename: bundle.js

webpack.config.toml

mode = "production"
entry = "./src/index.js"

[output]
filename = "bundle.js"

Configuration Types

Besides exporting a single configuration object, there are a few more ways that cover other needs as well.

Exporting a Function

Eventually you will find the need to disambiguate in your webpack.config.js between development and production builds. There are multiple ways to do that. One option is to export a function from your webpack configuration instead of exporting an object. The function will be invoked with two arguments:

• An environment as the first parameter. See the environment options CLI documentation for syntax examples.
• An options map (argv) as the second parameter. This describes the options passed to webpack, with keys such as output-path and mode.

-export default {
+export default function(env, argv) {
+  return {
+    mode: env.production ? 'production' : 'development',
+    devtool: env.production ? 'source-map' : 'eval',
     plugins: [
       new MinimizerPlugin({
         minimizerOptions: {
+          compress: argv.mode === 'production' // only if `--mode production` was passed
         }
       })
     ]
+  };
};

Exporting a Promise

Webpack will run the function exported by the configuration file and wait for a Promise to be returned. Handy when you need to asynchronously load configuration variables.

export default () =>
  new Promise((resolve, reject) => {
    setTimeout(() => {
      resolve({
        entry: "./app.js",
        /* ... */
      });
    }, 5000);
  });

Exporting multiple configurations

Instead of exporting a single configuration object/function, you may export multiple configurations (multiple functions are supported since webpack 3.1.0). When running webpack, all configurations are built. For instance, this is useful for bundling a library for multiple targets such as AMD and CommonJS:

export default [
  {
    output: {
      filename: "./dist-amd.js",
      libraryTarget: "amd",
    },
    name: "amd",
    entry: "./app.js",
    mode: "production",
  },
  {
    output: {
      filename: "./dist-commonjs.js",
      libraryTarget: "commonjs",
    },
    name: "commonjs",
    entry: "./app.js",
    mode: "production",
  },
];

dependencies

In case you have a configuration that depends on the output of another configuration, you can specify a list of dependencies using the dependencies array.

webpack.config.js

export default [
  {
    name: "client",
    target: "web",
    // …
  },
  {
    name: "server",
    target: "node",
    dependencies: ["client"],
  },
];

parallelism

In case you export multiple configurations, you can use the parallelism option on the configuration array to specify the maximum number of compilers that will compile in parallel.

• Type: number
• Available: 5.22.0+

webpack.config.js

const config = [
  {
    // config-1
  },
  {
    // config-2
  },
];

config.parallelism = 1;

export default config;

Entry and Context

The entry object is where webpack looks to start building the bundle. The context is an absolute string to the directory that contains the entry files.

context

string

The base directory, an absolute path, for resolving entry points and loaders from the configuration.

import path from "node:path";
import { fileURLToPath } from "node:url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

export default {
  // ...
  context: path.resolve(__dirname, "app"),
};

By default, the current working directory of Node.js is used, but it's recommended to pass a value in your configuration. This makes your configuration independent from CWD (current working directory).

entry

string [string] object = { <key> string | [string] | object = { import string | [string], dependOn string | [string], filename string, layer string, runtime string | false }} (function() => string | [string] | object = { <key> string | [string] } | object = { import string | [string], dependOn string | [string], filename string, layer string, runtime string | false })

The point or points where to start the application bundling process. If an array is passed then all items will be processed.

A dynamically loaded module is not an entry point.

A rule to consider: one entry point per HTML page. SPA: one entry point, MPA: multiple entry points.

export default {
  // ...
  entry: {
    home: "./home.js",
    about: "./about.js",
    contact: "./contact.js",
  },
};

Naming

If a string or array of strings is passed, the chunk is named main. If an object is passed, each key is the name of a chunk, and the value describes the entry point for the chunk.

Entry descriptor

If an object is passed the value might be a string, array of strings, or a descriptor:

export default {
  // ...
  entry: {
    home: "./home.js",
    shared: ["react", "react-dom", "redux", "react-redux"],
    catalog: {
      import: "./catalog.js",
      filename: "pages/catalog.js",
      dependOn: "shared",
      chunkLoading: false, // Disable chunks that are loaded on demand and put everything in the main chunk.
    },
    personal: {
      import: "./personal.js",
      filename: "pages/personal.js",
      dependOn: "shared",
      chunkLoading: "jsonp",
      asyncChunks: true, // Create async chunks that are loaded on demand.
      layer: "name of layer", // set the layer for an entry point
      worker: true, // mark as a worker entry, available since webpack 5.108.0
    },
  },
};

Descriptor syntax might be used to pass additional options to an entry point.

The html option 5.108.0+ generates an HTML file for this entrypoint with its JS and CSS output chunks injected. It accepts the same values as output.html and, since webpack 5.110.0, an object that overrides it option by option for this entry, so a single entry can opt out of page generation or change just its title:

export default {
  entry: {
    app: "./src/app.js",
    admin: { import: "./src/admin.js", html: { title: "Admin" } },
    worker: { import: "./src/worker.js", html: false },
  },
  output: { html: true },
  experiments: { html: true },
};

Output filename

By default, the output filename for the entry chunk is extracted from output.filename but you can specify a custom output filename for a specific entry:

export default {
  // ...
  entry: {
    app: "./app.js",
    home: { import: "./contact.js", filename: "pages/[name].js" },
    about: { import: "./about.js", filename: "pages/[name].js" },
  },
};

Descriptor syntax was used here to pass filename-option to the specific entry points.

Dependencies

By default, every entry chunk stores all the modules that it uses. With dependOn option you can share the modules from one entry chunk to another:

export default {
  // ...
  entry: {
    app: { import: "./app.js", dependOn: "react-vendors" },
    "react-vendors": ["react", "react-dom", "prop-types"],
  },
};

The app chunk will not contain the modules that react-vendors have.

dependOn option can also accept an array of strings:

export default {
  // ...
  entry: {
    moment: { import: "moment-mini", runtime: "runtime" },
    reactvendors: { import: ["react", "react-dom"], runtime: "runtime" },
    testapp: {
      import: "./wwwroot/component/TestApp.tsx",
      dependOn: ["reactvendors", "moment"],
    },
  },
};

Also, you can specify multiple files per entry using an array:

export default {
  // ...
  entry: {
    app: { import: ["./app.js", "./app2.js"], dependOn: "react-vendors" },
    "react-vendors": ["react", "react-dom", "prop-types"],
  },
};

Dynamic entry

If a function is passed then it will be invoked on every make event.

Note that the make event triggers when webpack starts and for every invalidation when watching for file changes.

export default {
  // ...
  entry: () => "./demo",
};

or

export default {
  // ...
  entry: () =>
    new Promise((resolve) => {
      resolve(["./demo", "./demo2"]);
    }),
};

Multiple Entry Points in Different Folders

In some scenarios, you might want to organize your entry points into different folders for better structure and maintainability. Here's how you can define multiple entry points located in different folders:

export default {
  entry: {
    "/scriptFolder/one/app": "./src/one/app.js",
    "/scriptFolder/two/main": "./src/two/main.js",
  },
};

For example: you can use dynamic entries to get the actual entries from an external source (remote server, file system content or database):

webpack.config.js

export default {
  entry() {
    return fetchPathsFromSomeExternalSource(); // returns a promise that will be resolved with something like ['src/main-layout.js', 'src/admin-layout.js']
  },
};

When combining with the output.library option: If an array is passed only the last item is exported.

Runtime chunk

It allows setting the runtime chunk for an entry point and setting it to false to avoid a new runtime chunk since webpack v5.43.0.

optimization.runtimeChunk allows setting it globally for unspecified entry points.

export default {
  // ...
  entry: {
    home: {
      import: "./home.js",
      runtime: "home-runtime",
    },
    about: {
      import: "./about.js",
      runtime: false,
    },
  },
};

Mode

Providing the mode configuration option tells webpack to use its built-in optimizations accordingly.

string = 'production': 'none' | 'development' | 'production'

Usage

Provide the mode option in the config:

export default {
  mode: "development",
};

or pass it as a CLI argument:

webpack --mode=development

The following string values are supported:

If not set, webpack sets production as the default value for mode.

Mode: development

// webpack.development.config.js
export default {
  mode: "development",
};

Mode: production

// webpack.production.config.js
export default {
  mode: "production",
};

Mode: none

// webpack.custom.config.js
export default {
  mode: "none",
};

If you want to change the behavior according to the mode variable inside the webpack.config.js, you have to export a function instead of an object:

const config = {
  entry: "./app.js",
  // ...
};

export default (env, argv) => {
  if (argv.mode === "development") {
    config.devtool = "source-map";
  }

  if (argv.mode === "production") {
    // ...
  }

  return config;
};

Output

The top-level output key contains a set of options instructing webpack on how and where it should output your bundles, assets, and anything else you bundle or load with webpack.

output.assetModuleFilename

string = '[hash][ext][query]' function (pathData, assetInfo) => string

The same as output.filename but for Asset Modules.

[name], [file], [query], [fragment], [base], and [path] are set to an empty string for the assets built from data URI replacements.

output.asyncChunks

boolean = true

Create async chunks that are loaded on demand.

webpack.config.js

export default {
  // ...
  output: {
    // ...
    asyncChunks: true,
  },
};

output.auxiliaryComment

string object

When used in tandem with output.library and output.libraryTarget, this option allows users to insert comments within the export wrapper. To insert the same comment for each libraryTarget type, set auxiliaryComment to a string:

webpack.config.js

export default {
  // ...
  output: {
    library: "someLibName",
    libraryTarget: "umd",
    filename: "someLibName.js",
    auxiliaryComment: "Test Comment",
  },
};

which will yield the following:

someLibName.js

(function webpackUniversalModuleDefinition(root, factory) {
  // Test Comment
  if (typeof exports === "object" && typeof module === "object") {
    module.exports = factory(require("lodash"));
  }
  // Test Comment
  else if (typeof define === "function" && define.amd) {
    define(["lodash"], factory);
  }
  // Test Comment
  else if (typeof exports === "object") {
    exports.someLibName = factory(require("lodash"));
  }
  // Test Comment
  else {
    root.someLibName = factory(root._);
  }
})(this, (__WEBPACK_EXTERNAL_MODULE_1__) => {
  // ...
});

For fine-grained control over each libraryTarget comment, pass an object:

webpack.config.js

export default {
  // ...
  output: {
    // ...
    auxiliaryComment: {
      root: "Root Comment",
      commonjs: "CommonJS Comment",
      commonjs2: "CommonJS2 Comment",
      amd: "AMD Comment",
    },
  },
};

output.charset

boolean = true

Tells webpack to add charset="utf-8" to the HTML <script> tag.

output.chunkFilename

string = '[id].js' function (pathData, assetInfo) => string

This option determines the name of non-initial chunk files. See output.filename option for details on the possible values.

Note that these filenames need to be generated at runtime to send the requests for chunks. Because of this, placeholders like [name] and [chunkhash] need to add a mapping from chunk id to placeholder value to the output bundle with the webpack runtime. This increases the size and may invalidate the bundle when placeholder value for any chunk changes.

By default [id].js is used or a value inferred from output.filename ([name] is replaced with [id] or [id]. is prepended).

webpack.config.js

export default {
  // ...
  output: {
    // ...
    chunkFilename: "[id].js",
  },
};

Usage as a function:

webpack.config.js

export default {
  // ...
  output: {
    chunkFilename: (pathData) =>
      pathData.chunk.name === "main" ? "[name].js" : "[name]/[name].js",
  },
};

output.chunkFormat

false string: 'array-push' | 'commonjs' | 'module' | <any string>

The format of chunks (formats included by default are 'array-push' (web/WebWorker), 'commonjs' (node.js), 'module' (ESM), but others might be added by plugins).

webpack.config.js

export default {
  // ...
  output: {
    // ...
    chunkFormat: "commonjs",
  },
};

output.chunkLoadTimeout

number = 120000

The Number of milliseconds before chunk request expires. This option is supported since webpack 2.6.0.

webpack.config.js

export default {
  // ...
  output: {
    // ...
    chunkLoadTimeout: 30000,
  },
};

output.chunkLoadingGlobal

string = 'webpackChunkwebpack'

The global variable is used by webpack for loading chunks.

webpack.config.js

export default {
  // ...
  output: {
    // ...
    chunkLoadingGlobal: "myCustomFunc",
  },
};

output.chunkLoading

false string: 'jsonp' | 'import-scripts' | 'require' | 'async-node' | 'import' | <any string>

The method to load chunks (methods included by default are 'jsonp' (web), 'import' (ESM), 'importScripts' (WebWorker), 'require' (sync node.js), 'async-node' (async node.js), but others might be added by plugins).

webpack.config.js

export default {
  // ...
  output: {
    // ...
    chunkLoading: "async-node",
  },
};

output.clean

boolean { dry?: boolean, keep?: RegExp | string | ((filename: string) => boolean) }

export default {
  // ...
  output: {
    clean: true, // Clean the output directory before emit.
  },
};

export default {
  // ...
  output: {
    clean: {
      dry: true, // Log the assets that should be removed instead of deleting them.
    },
  },
};

export default {
  // ...
  output: {
    clean: {
      keep: /ignored\/dir\//, // Keep these assets under 'ignored/dir'.
    },
  },
};

export default {
  // ...
  output: {
    clean: {
      keep(asset) {
        return asset.includes("ignored/dir");
      },
    },
  },
};

You can also use it with hook:

webpack.CleanPlugin.getCompilationHooks(compilation).keep.tap(
  "Test",
  (asset) => {
    if (/ignored\/dir\//.test(asset)) return true;
  },
);

output.compareBeforeEmit

boolean = true

Tells webpack to check if to be emitted file already exists and has the same content before writing to the output file system.

export default {
  // ...
  output: {
    compareBeforeEmit: false,
  },
};

output.crossOriginLoading

boolean = false string: 'anonymous' | 'use-credentials'

Tells webpack to enable cross-origin loading of chunks. Only takes effect when the target is set to 'web', which uses JSONP for loading on-demand chunks, by adding script tags.

• 'anonymous' - Enable cross-origin loading without credentials
• 'use-credentials' - Enable cross-origin loading with credentials

output.cssChunkFilename

string function (pathData, assetInfo) => string

This option determines the name of non-initial CSS output files on disk. See output.filename option for details on the possible values.

You must not specify an absolute path here. However, feel free to include folders separated by '/'. This specified path combines with the output.path value to pinpoint the location on the disk.

output.cssFilename

string function (pathData, assetInfo) => string

This option determines the name of CSS output files on disk. See output.filename option for details on the possible values.

You must not specify an absolute path here. However, feel free to include folders separated by '/'. This specified path combines with the output.path value to pinpoint the location on the disk.

output.devtoolFallbackModuleFilenameTemplate

string function (info)

A fallback is used when the template string or function above yields duplicates.

See output.devtoolModuleFilenameTemplate.

output.devtoolModuleFilenameTemplate

string = 'webpack://[namespace]/[resource-path]?[loaders]' function (info) => string

This option is only used when devtool uses an option that requires module names.

Customize the names used in each source map's sources array. This can be done by passing a template string or function. For example, when using devtool: 'eval'.

webpack.config.js

export default {
  // ...
  output: {
    devtoolModuleFilenameTemplate:
      "webpack://[namespace]/[resource-path]?[loaders]",
  },
};

The following substitutions are available in template strings (via webpack's internal ModuleFilenameHelpers):

When using a function, the same options are available camel-cased via the info parameter:

export default {
  // ...
  output: {
    devtoolModuleFilenameTemplate: (info) =>
      `webpack:///${info.resourcePath}?${info.loaders}`,
  },
};

If multiple modules would result in the same name, output.devtoolFallbackModuleFilenameTemplate is used instead for these modules.

output.devtoolNamespace

string

This option determines the module's namespace used with the output.devtoolModuleFilenameTemplate. When not specified, it will default to the value of: output.uniqueName. It's used to prevent source file path collisions in sourcemaps when loading multiple libraries built with webpack.

For example, if you have 2 libraries, with namespaces library1 and library2, which both have a file ./src/index.js (with potentially different contents), they will expose these files as webpack://library1/./src/index.js and webpack://library2/./src/index.js.

You can use template strings like [name] to dynamically generate namespaces based on the build context, providing additional flexibility.

webpack.config.js

export default {
  // ...
  output: {
    filename: "[name]-bundle.js",
    library: "library-[name]",
    libraryTarget: "commonjs",
    devtoolNamespace: "library-[name]", // Sets a unique namespace for each library
  },
};

output.enabledChunkLoadingTypes

[string: 'jsonp' | 'import-scripts' | 'require' | 'async-node' | <any string>]

List of chunk loading types enabled for use by entry points. Will be automatically filled by webpack. Only needed when using a function as entry option and returning chunkLoading option from there.

webpack.config.js

export default {
  // ...
  output: {
    // ...
    enabledChunkLoadingTypes: ["jsonp", "require"],
  },
};

output.enabledLibraryTypes

[string]

List of library types enabled for use by entry points.

export default {
  // ...
  output: {
    enabledLibraryTypes: ["module"],
  },
};

output.enabledWasmLoadingTypes

[string]

List of wasm loading types enabled for use by entry points.

export default {
  // ...
  output: {
    enabledWasmLoadingTypes: ["fetch"],
  },
};

output.environment

Tell webpack what kind of ES-features may be used in the generated runtime-code.

export default {
  output: {
    environment: {
      // The environment supports arrow functions ('() => { ... }').
      arrowFunction: true,
      // The environment supports async function and await ('async function () { await ... }').
      asyncFunction: true,
      // The environment supports BigInt as literal (123n).
      bigIntLiteral: false,
      // The environment supports const for variable declarations.
      const: true,
      // The environment supports let for variable declarations.
      let: true,
      // The environment supports logical assignment operators ('a ||= b', 'a &&= b', 'a ??= b').
      logicalAssignment: true,
      // The environment supports destructuring ('{ a, b } = obj').
      destructuring: true,
      // The environment supports 'document' variable.
      document: true,
      // The environment supports 'Object.hasOwn'.
      hasOwn: true,
      // The environment supports an async import() function to import EcmaScript modules.
      dynamicImport: false,
      // The environment supports an async import() when creating a worker, only for web targets at the moment.
      dynamicImportInWorker: false,
      // The environment supports 'for of' iteration ('for (const x of array) { ... }').
      forOf: true,
      // The environment supports 'globalThis'.
      globalThis: true,
      // The environment supports ECMAScript Module syntax to import ECMAScript modules (import ... from '...').
      module: false,
      // The environment supports object method shorthand ('{ module() {} }').
      methodShorthand: true,
      // The environment supports `process.getBuiltinModule()` to synchronously load Node.js core modules.
      nodeBuiltinModuleGetter: false,
      // Determines if the node: prefix is generated for core module imports in environments that support it.
      // This is only applicable to Webpack runtime code.
      nodePrefixForCoreModules: false,
      // The environment supports optional chaining ('obj?.a' or 'obj?.()').
      optionalChaining: true,
      // The environment supports spread and rest in array/object literals and calls ('{ ...obj }', 'fn(...args)').
      spread: true,
      // The environment supports 'Symbol' (and well-known symbols like 'Symbol.toStringTag').
      symbol: true,
      // The environment supports template literals.
      templateLiteral: true,
      // The environment supports `import.meta.dirname` and `import.meta.filename`.
      importMetaDirnameAndFilename: false,
      // The environment supports deferred module evaluation ('import defer * as ns from "..."', 'import.defer("...")'). Since webpack 5.110.0.
      deferImport: false,
      // The environment supports source phase imports ('import source m from "..."', 'import.source("...")'). Since webpack 5.110.0.
      sourceImport: false,
    },
  },
};

These capability flags are normally inferred from your target; you only set them manually to override that detection. When a flag is enabled, webpack emits the corresponding modern syntax in its generated runtime code and otherwise falls back to the equivalent legacy output.

output.filename

string function (pathData, assetInfo) => string

This option determines the name of each output bundle. The bundle is written to the directory specified by the output.path option.

For a single entry point, this can be a static name.

webpack.config.js

export default {
  // ...
  output: {
    filename: "bundle.js",
  },
};

However, when creating multiple bundles via more than one entry point, code splitting, or various plugins, you should use one of the following substitutions to give each bundle a unique name...

Using entry name:

webpack.config.js

export default {
  // ...
  output: {
    filename: "[name].bundle.js",
  },
};

Using internal chunk id:

webpack.config.js

export default {
  // ...
  output: {
    filename: "[id].bundle.js",
  },
};

Using hashes generated from the generated content:

webpack.config.js

export default {
  // ...
  output: {
    filename: "[contenthash].bundle.js",
  },
};

Combining multiple substitutions:

webpack.config.js

export default {
  // ...
  output: {
    filename: "[name].[contenthash].bundle.js",
  },
};

Using the function to return the filename:

webpack.config.js

export default {
  // ...
  output: {
    filename: (pathData) =>
      pathData.chunk.name === "main" ? "[name].js" : "[name]/[name].js",
  },
};

Make sure to read the Caching guide for details. There are more steps involved than only setting this option.

Note this option is called filename but you are still allowed to use something like 'js/[name]/bundle.js' to create a folder structure.

Template strings

The following substitutions are available in template strings (via webpack's internal TemplatedPathPlugin):

Substitutions available on Compilation-level:

Substitutions available on Chunk-level:

Substitutions available on Module-level:

Substitutions available on File-level:

Substitutions available on URL-level:

[containedfile] and [containedpath] 5.110.0+ are [file] and [path] rewritten so the result always stays under output.path: a leading absolute root and every ../ segment become _/. A module resolved outside the context, a linked package or a file above the project root, has a [path] starting with .., and using it in a filename template writes the asset outside the output directory. The contained placeholders keep the same directory structure inside it instead:

// a module at ../shared/logo.png, with context at ./src
export default {
  // ...
  output: {
    assetModuleFilename: "[containedpath][name][ext]", // _/shared/logo.png
    // "[path][name][ext]" would emit ../shared/logo.png, outside output.path
  },
};

With experiments.futureDefaults enabled, [path] and [file] already behave this way for asset and HTML modules, so the contained placeholders are what those templates resolve to anyway. This will become the default in webpack 6.

The length of hashes ([hash], [contenthash] or [chunkhash]) can be specified using [hash:16] (defaults to 20). Alternatively, specify output.hashDigestLength to configure the length globally.

Since webpack 5.108.0, the hash digest encoding can also be set inline as [<hash>:<digest>:<length>], for example [contenthash:base64:8]. The digest defaults to output.hashDigest (hex), and the same form works in CSS module localIdentName placeholders.

It is possible to filter out placeholder replacement when you want to use one of the placeholders in the actual file name. For example, to output a file [name].js, you have to escape the [name] placeholder by adding backslashes between the brackets. So that [\name\] generates [name] instead of getting replaced with the name of the asset.

Example: [\id\] generates [id] instead of getting replaced with the id.

If using a function for this option, the function will be passed an object containing data for the substitutions in the table above. Substitutions will be applied to the returned string too. The passed object will have this type: (properties available depending on context)

type PathData = {
  hash: string;
  hashWithLength: (number) => string;
  chunk: Chunk | ChunkPathData;
  module: Module | ModulePathData;
  contentHashType: string;
  contentHash: string;
  contentHashWithLength: (number) => string;
  filename: string;
  url: string;
  runtime: string | SortableSet<string>;
  chunkGraph: ChunkGraph;
};
type ChunkPathData = {
  id: string | number;
  name: string;
  hash: string;
  hashWithLength: (number) => string;
  contentHash: Record<string, string>;
  contentHashWithLength: Record<string, (number) => string>;
};
type ModulePathData = {
  id: string | number;
  hash: string;
  hashWithLength: (number) => string;
};

output.globalObject

string = 'self'

When targeting a library, especially when library.type is 'umd', this option indicates what global object will be used to mount the library. To make UMD build available on both browsers and Node.js, set output.globalObject option to 'this'. Defaults to self for Web-like targets.

The return value of your entry point will be assigned to the global object using the value of output.library.name. Depending on the value of the type option, the global object could change respectively, e.g., self, global, or globalThis.

For example:

webpack.config.js

export default {
  // ...
  output: {
    library: {
      name: "myLib",
      type: "umd",
    },
    filename: "myLib.js",
    globalObject: "this",
  },
};

output.hashDigest

string = 'hex'

The encoding to use when generating the hash. All encodings from Node.JS' hash.digest are supported. Using 'base64' for filenames might be problematic since it has the character / in its alphabet. Likewise 'latin1' could contain any character.

In addition to the standard Node.js encodings, webpack also supports the following custom digest algorithms for generating shorter or URL-safe hash values:

• 'base64url' - URL-safe base64 encoding (RFC 4648), recommended for filenames
• 'base62' - Base62 encoding (0-9, A-Z, a-z)
• 'base58' - Base58 encoding (Bitcoin alphabet)
• 'base52' - Base52 encoding (A-Z, a-z)
• 'base49' - Base49 encoding
• 'base36' - Base36 encoding (0-9, A-Z)
• 'base32' - Base32 encoding (RFC 4648)
• 'base25' - Base25 encoding

These custom encodings are particularly useful for generating shorter hash values in filenames while maintaining URL safety.

webpack.config.js

export default {
  output: {
    hashDigest: "base64url", // URL-safe encoding for filenames
  },
};

output.hashDigestLength

number = 20

The prefix length of the hash digest to use.

output.hashFunction

string = 'md4' function

The hashing algorithm to use. All functions from Node.JS' crypto.createHash are supported. Since 4.0.0-alpha2, the hashFunction can now be a constructor to a custom hash function. You can provide a non-crypto hash function for performance reasons.

export default {
  // ...
  output: {
    hashFunction: require("metrohash").MetroHash64,
  },
};

Make sure that the hashing function will have an update and digest methods available.

output.hashSalt

An optional salt to update the hash via Node.JS' hash.update.

output.hotUpdateChunkFilename

string = '[id].[fullhash].hot-update.js'

Customize the filenames of hot update chunks. See output.filename option for details on the possible values.

The only placeholders allowed here are [id] and [fullhash], the default being:

webpack.config.js

export default {
  // ...
  output: {
    hotUpdateChunkFilename: "[id].[fullhash].hot-update.js",
  },
};

output.hotUpdateGlobal

string

Only used when target is set to 'web', which uses JSONP for loading hot updates.

A JSONP function is used to asynchronously load hot-update chunks.

For details see output.chunkLoadingGlobal.

output.hotUpdateMainFilename

string = '[runtime].[fullhash].hot-update.json' function

Customize the main hot update filename. [fullhash] and [runtime] are available as placeholder.

output.html

boolean = false object

Generate an HTML file for each non-HTML entrypoint, injecting that entrypoint's initial JS and CSS output chunks (including chunks shared through dependOn). This is the part of html-webpack-plugin that scaffolds a document around your bundles, built into webpack core. It relies on the experimental HTML support, so enable experiments.html.

// webpack.config.js
export default {
  experiments: { html: true },
  entry: {
    main: "./src/main.js",
  },
  output: {
    html: true,
  },
};

Set it to an object for the options below. It can be overridden per entry through the entry descriptor html option.

output.html.scriptLoading

'auto' | 'defer' | 'blocking'

Configure how the injected <script> tags load:

• 'auto' (default): emit a module script (type="module") for ES module output and a deferred script otherwise.
• 'defer': force a deferred <script defer>.
• 'blocking': emit a plain blocking <script>.

// webpack.config.js
export default {
  experiments: { html: true },
  output: {
    html: {
      scriptLoading: "defer",
    },
  },
};

output.html.title

string

Sets the <title> of the generated HTML page. Skipped if the HTML already contains a <title> element.

// webpack.config.js
export default {
  experiments: { html: true },
  output: {
    html: {
      title: "My App",
    },
  },
};

output.html.meta

object

Inject <meta> tags into the page <head>. Each key is the name attribute (or 'charset' for a charset declaration) and the value is the content string. Keys beginning with og: use the property attribute instead of name. A tag is skipped if the HTML already contains a meta with the same name.

// webpack.config.js
export default {
  experiments: { html: true },
  output: {
    html: {
      meta: {
        viewport: "width=device-width, initial-scale=1",
        "og:title": "My App",
      },
    },
  },
};

output.html.base

string object

Inject a <base> element into the page <head>. A string sets href; an object sets href and optionally target. Skipped if the HTML already contains a <base> element.

// webpack.config.js
export default {
  experiments: { html: true },
  output: {
    html: {
      base: { href: "https://example.com/", target: "_blank" },
    },
  },
};

output.html.inject

'body' | 'head' | false

Where to place injected chunk <script> tags (and <link rel="modulepreload"> clones):

• 'body' (default; 'head' with output.module): keep them next to the entry tag, at the end of <body> on generated pages.
• 'head': move them into <head>.
• false: suppress sibling-chunk injection; entry tags and resource hints remain.

Stylesheet <link> tags for CSS chunks are not affected: they always land in <head> when the page has one, ahead of the first blocking script, or after defer / module script tags when there is none (the order html-webpack-plugin emits).

// webpack.config.js
export default {
  experiments: { html: true },
  output: {
    html: {
      inject: "head",
    },
  },
};

output.html.inline

boolean 'script' | 'style' RegExp[]

Inline the content of matching chunks directly into the HTML instead of emitting a separate <script> / <link> tag:

• true: inline every chunk.
• 'script': inline only JavaScript chunks.
• 'style': inline only CSS chunks.
• An array of RegExp patterns: inline the chunks whose name matches.

// webpack.config.js
export default {
  experiments: { html: true },
  output: {
    html: {
      inline: [/^runtime/, /critical/],
    },
  },
};

Individual references inside an authored HTML page can also opt in or out with the webpackInline magic comment, e.g. <!-- webpackInline: true --><script src="./critical.js"></script>. The HTML page's [contenthash] accounts for the inlined chunk content.

output.html.favicon

boolean = false string object function

Favicon(s) for webpack-generated HTML pages (authored pages are left untouched). Every icon is emitted as a hashed asset through the regular asset pipeline:

• false (default): inject nothing.
• true: inject the webpack logo.
• string: path to an icon file, linked as <link rel="icon">.
• object: maps each <link rel> to an icon. Each icon is a path string, an object with the icon href plus extra link attributes (sizes, media, color, type, crossorigin), or an array of these for multiple icons under the same rel (e.g. several sizes, or light/dark media variants).
• function: receives the page name and returns any of the above.

// webpack.config.js
export default {
  experiments: { html: true },
  output: {
    html: {
      favicon: {
        icon: [
          { href: "./favicon.svg", type: "image/svg+xml" },
          { href: "./favicon-32.png", sizes: "32x32" },
        ],
        "apple-touch-icon": "./apple-touch-icon.png",
      },
    },
  },
};

output.html.integrity

boolean string[] function

Add Subresource Integrity (SRI) integrity attributes to injected <script> / <link> tags. true uses ['sha384']; an array sets the hash algorithms (passed to Node.js crypto.createHash, e.g. ['sha256', 'sha384']); a function receives each referenced asset ({ chunk, filename }) and returns the algorithms to use, or false to skip that asset.

// webpack.config.js
export default {
  experiments: { html: true },
  output: {
    html: {
      integrity: true,
    },
  },
};

output.html.csp

boolean = false object

Inject a <meta http-equiv="Content-Security-Policy"> into every webpack-emitted HTML page. true uses a strict baseline (script-src 'self', style-src 'self', object-src 'none', base-uri 'self') and appends a sha256 hash of every inline <script> / <style> to script-src / style-src. Skipped when the page already declares a CSP.

An object customizes it:

• policy (object): CSP directives merged over the baseline. Each key is a directive (e.g. 'script-src'); the value is a source string or a list. Inline hashes and any nonce are still appended to script-src / style-src.
• hashFunction ('sha256' | 'sha384' | 'sha512'): hash algorithm used for inline <script> / <style> sources.
• nonce (string): placeholder nonce added to injected <script> / <style> tags and as a 'nonce-…' source; rewrite it per request server-side.

// webpack.config.js
export default {
  experiments: { html: true },
  output: {
    html: {
      csp: {
        policy: {
          "img-src": ["'self'", "data:"],
          "connect-src": "https://api.example.com",
        },
      },
    },
  },
};

output.html.manifest

false string object function

Web app manifest for webpack-generated HTML pages (authored pages are left untouched):

• false (default): inject nothing.
• string: path to an existing .webmanifest file to link.
• object: the manifest contents; it is serialized, emitted as a hashed .webmanifest and linked with <link rel="manifest">. Its icons / screenshots src paths resolve like any request and are emitted as hashed assets.
• function: receives the page name and returns any of the above.

// webpack.config.js
export default {
  experiments: { html: true },
  output: {
    html: {
      manifest: {
        name: "My App",
        short_name: "App",
        icons: [{ src: "./icon-512.png", sizes: "512x512" }],
      },
    },
  },
};

output.htmlFilename

string = output.filename with '.js' replaced by '.html' function (pathData, assetInfo) => string

The filename template for HTML files emitted by extracted HTML modules (initial chunks). It works like output.filename and supports the same template strings. When unset, it is derived from output.filename by swapping the .js extension for .html (falling back to [name].html when output.filename is a function), mirroring how cssFilename derives from filename.

// webpack.config.js
export default {
  experiments: { html: true },
  output: {
    htmlFilename: "[name].html",
  },
};

output.htmlChunkFilename

string = output.chunkFilename with '.js' replaced by '.html' function (pathData, assetInfo) => string

The filename template for HTML files emitted by extracted HTML modules for non-initial (on-demand) chunks. It defaults from output.chunkFilename the same way htmlFilename defaults from filename.

// webpack.config.js
export default {
  experiments: { html: true },
  output: {
    htmlChunkFilename: "[name].chunk.html",
  },
};

output.iife

boolean = true

Tells webpack to add IIFE wrapper around emitted code.

export default {
  // ...
  output: {
    iife: true,
  },
};

output.ignoreBrowserWarnings

boolean = false

Hide warnings from the browser console in production. This option does not affect the terminal/console output.

webpack.config.js

export default {
  // ...
  output: {
    ignoreBrowserWarnings: true,
  },
};

output.importFunctionName

string = 'import'

The name of the native import() function. Can be used for polyfilling, e.g. with dynamic-import-polyfill.

webpack.config.js

export default {
  // ...
  output: {
    importFunctionName: "__import__",
  },
};

output.importMetaName

string

The name of the native import.meta object (can be exchanged for a polyfill).

webpack.config.js

export default {
  // ...
  output: {
    importMetaName: "pseudoImport.meta",
  },
};

output.library

Output a library exposing the exports of your entry point.

• Type: string | string[] | object

Let's take a look at an example.

webpack.config.js

export default {
  // …
  entry: "./src/index.js",
  output: {
    library: "MyLibrary",
  },
};

Say you have exported a function in your src/index.js entry:

export function hello(name) {
  console.log(`hello ${name}`);
}

Now the variable MyLibrary will be bound with the exports of your entry file, and here's how to consume the webpack bundled library:

<script src="https://example.org/path/to/my-library.js"></script>
<script>
  MyLibrary.hello("webpack");
</script>

In the above example, we're passing a single entry file to entry, however, webpack can accept many kinds of entry point, e.g., an array, or an object.

1. If you provide an array as the entry point, only the last one in the array will be exposed.

   Copy

   export default {
     // …
     entry: ["./src/a.js", "./src/b.js"], // only exports in b.js will be exposed
     output: {
       library: "MyLibrary",
     },
   };

2. If an object is provided as the entry point, all entries can be exposed using the array syntax of library:

   Copy

   export default {
     // …
     entry: {
       a: "./src/a.js",
       b: "./src/b.js",
     },
     output: {
       filename: "[name].js",
       library: ["MyLibrary", "[name]"], // name is a placeholder here
     },
   };

   Assuming that both a.js and b.js export a function hello, here's how to consume the libraries:

   Copy

   <script src="https://example.org/path/to/a.js"></script>
   <script src="https://example.org/path/to/b.js"></script>
   <script>
     MyLibrary.a.hello("webpack");
     MyLibrary.b.hello("webpack");
   </script>

   See this example for more.

   Note that the above configuration won't work as expected if you're going to configure library options per entry point. Here is how to do it under each of your entries:

   Copy

   export default {
     // …
     entry: {
       main: {
         import: "./src/index.js",
         library: {
           // all options under `output.library` can be used here
           name: "MyLibrary",
           type: "umd",
           umdNamedDefine: true,
         },
       },
       another: {
         import: "./src/another.js",
         library: {
           name: "AnotherLibrary",
           type: "commonjs2",
         },
       },
     },
   };

output.library.amdContainer

Use a container(defined in global space) for calling define/require functions in an AMD module.

export default {
  // …
  output: {
    library: {
      amdContainer: 'window["clientContainer"]',
      type: "amd", // or 'amd-require'
    },
  },
};

Which will result in the following bundle:

globalThis.clientContainer.define(/* define args */); // or 'amd-require' window['clientContainer'].require(/*require args*/);

output.library.umdAmdContainer

string

Add a branch to the UMD wrapper for an AMD-style loader that exposes define on a container object rather than as a global, given as a dot-separated path. The branch is emitted right after the standard define.amd one, so a plain AMD loader still wins and the container is only used where it is the loader present:

export default {
  // ...
  output: {
    library: {
      name: "MyLibrary",
      type: "umd",
      umdAmdContainer: "myContainer.amdLoader",
    },
  },
};

The value must be a dot-separated identifier path (myContainer.amdLoader), not an arbitrary expression.

output.library.name

export default {
  // …
  output: {
    library: {
      name: "MyLibrary",
    },
  },
};

Specify a name for the library.

• Type:

  Copy

  string | string[] | {amd?: string, commonjs?: string, root?: string | string[]}

output.library.type

Configure how the library will be exposed.

• Type: string

  Types included by default are 'var', 'module', 'modern-module', 'assign', 'assign-properties', 'this', 'window', 'self', 'global', 'commonjs', 'commonjs2', 'commonjs-module', 'commonjs-static', 'amd', 'amd-require', 'umd', 'umd2', 'jsonp' and 'system', but others might be added by plugins.

For the following examples, we'll use _entry_return_ to indicate the values returned by the entry point.

Expose a Variable

These options assign the return value of the entry point (e.g. whatever the entry point exported) to the name provided by output.library.name at whatever scope the bundle was included at.

type: 'var'

export default {
  // …
  output: {
    library: {
      name: "MyLibrary",
      type: "var",
    },
  },
};

When your library is loaded, the return value of your entry point will be assigned to a variable:

const MyLibrary = _entry_return_;

// In a separate script with `MyLibrary` loaded…
MyLibrary.doSomething();

type: 'assign'

export default {
  // …
  output: {
    library: {
      name: "MyLibrary",
      type: "assign",
    },
  },
};

This will generate an implied global which has the potential to reassign an existing value (use with caution):

MyLibrary = _entry_return_;

Be aware that if MyLibrary isn't defined earlier your library will be set in global scope.

type: 'assign-properties'

export default {
  // …
  output: {
    library: {
      name: "MyLibrary",
      type: "assign-properties",
    },
  },
};

Similar to type: 'assign' but a safer option as it will reuse MyLibrary if it already exists:

// only create MyLibrary if it doesn't exist
MyLibrary = typeof MyLibrary === "undefined" ? {} : MyLibrary;
// then copy the return value to MyLibrary
// similarly to what Object.assign does

// for instance, you export a `hello` function in your entry as follow
export function hello(name) {
  console.log(`Hello ${name}`);
}

// In another script with MyLibrary loaded
// you can run `hello` function like so
MyLibrary.hello("World");

Expose Via Object Assignment

These options assign the return value of the entry point (e.g. whatever the entry point exported) to a specific object under the name defined by output.library.name.

type: 'this'

export default {
  // …
  output: {
    library: {
      name: "MyLibrary",
      type: "this",
    },
  },
};

The return value of your entry point will be assigned to this under the property named by output.library.name. The meaning of this is up to you:

this.MyLibrary = _entry_return_;

// In a separate script...
this.MyLibrary.doSomething();
MyLibrary.doSomething(); // if `this` is window

type: 'window'

export default {
  // …
  output: {
    library: {
      name: "MyLibrary",
      type: "window",
    },
  },
};

The return value of your entry point will be assigned to the window object using the output.library.name value.

globalThis.MyLibrary = _entry_return_;

globalThis.MyLibrary.doSomething();

type: 'global'

export default {
  // …
  output: {
    library: {
      name: "MyLibrary",
      type: "global",
    },
  },
};

The return value of your entry point will be assigned to the global object using the output.library.name value. Depending on the target value, the global object could change respectively, e.g., self, global or globalThis.

globalThis.MyLibrary = _entry_return_;

globalThis.MyLibrary.doSomething();

type: 'commonjs'

export default {
  // …
  output: {
    library: {
      name: "MyLibrary",
      type: "commonjs",
    },
  },
};

The return value of your entry point will be assigned to the exports object using the output.library.name value. As the name implies, this is used in CommonJS environments.

exports.MyLibrary = _entry_return_;

require("MyLibrary").doSomething();

Module Definition Systems

These options will result in a bundle that comes with a complete header to ensure compatibility with various module systems. The output.library.name option will take on a different meaning under the following output.library.type options.

type: 'module'

export default {
  // …
  experiments: {
    outputModule: true,
  },
  output: {
    library: {
      // do not specify a `name` here
      type: "module",
    },
  },
};

Output ES Module.

However this feature is still experimental and not fully supported yet, so make sure to enable experiments.outputModule beforehand. In addition, you can track the development progress in this thread.

type: 'modern-module'

export default {
  // …
  experiments: {
    outputModule: true,
  },
  output: {
    library: {
      // do not specify a `name` here
      type: "modern-module",
    },
  },
};

This configuration generates tree-shakable output for ES Modules.

However this feature is still experimental and not fully supported yet, so make sure to enable experiments.outputModule beforehand.

type: 'commonjs2'

export default {
  // …
  output: {
    library: {
      // note there's no `name` here
      type: "commonjs2",
    },
  },
};

The return value of your entry point will be assigned to the module.exports. As the name implies, this is used in Node.js (CommonJS) environments:

export default _entry_return_;

require("MyLibrary").doSomething();

If we specify output.library.name with type: commonjs2, the return value of your entry point will be assigned to the module.exports.[output.library.name].

type: 'commonjs-module'

commonjs-module is equivalent to commonjs2. We may remove commonjs-module in future versions.

type: 'commonjs-static'

export default {
  // …
  output: {
    library: {
      // note there's no `name` here
      type: "commonjs-static",
    },
  },
};

Individual exports will be set as properties on module.exports. The "static" in the name refers to the output being statically analysable, and thus named exports are importable into ESM via Node.js:

Input:

export function doSomething() {}

Output:

function doSomething() {}

// …

exports.doSomething = __webpack_exports__.doSomething;

Consumption (CommonJS):

const { doSomething } = require("./output.cjs"); // doSomething => [Function: doSomething]

Consumption (ESM):

import { doSomething } from "./output.cjs"; // doSomething => [Function: doSomething]

type: 'amd'

This will expose your library as an AMD module.

AMD modules require that the entry chunk (e.g. the first script loaded by the <script> tag) be defined with specific properties, such as to define and require which is typically provided by RequireJS or any compatible loaders (such as almond). Otherwise, loading the resulting AMD bundle directly will result in an error like define is not defined.

With the following configuration...

export default {
  // ...
  output: {
    library: {
      name: "MyLibrary",
      type: "amd",
    },
  },
};

The generated output will be defined with the name "MyLibrary", i.e.:

define("MyLibrary", [], () => _entry_return_);

The bundle can be included as part of a script tag, and the bundle can be invoked like so:

require(["MyLibrary"], (MyLibrary) => {
  // Do something with the library...
});

If output.library.name is undefined, the following is generated instead.

define(() => _entry_return_);

This bundle will not work as expected, or not work at all (in the case of the almond loader) if loaded directly with a <script> tag. It will only work through a RequireJS compatible asynchronous module loader through the actual path to that file, so in this case, the output.path and output.filename may become important for this particular setup if these are exposed directly on the server.

type: 'amd-require'

export default {
  // ...
  output: {
    library: {
      name: "MyLibrary",
      type: "amd-require",
    },
  },
};

This packages your output with an immediately executed AMD require(dependencies, factory) wrapper.

The 'amd-require' type allows for the use of AMD dependencies without needing a separate later invocation. As with the 'amd' type, this depends on the appropriate require function being available in the environment in which the webpack output is loaded.

With this type, the library name can't be used.

type: 'umd'

This exposes your library under all the module definitions, allowing it to work with CommonJS, AMD, and as global variable. Take a look at the UMD Repository to learn more.

In this case, you need the library.name property to name your module:

export default {
  // ...
  output: {
    library: {
      name: "MyLibrary",
      type: "umd",
    },
  },
};

And finally the output is:

(function webpackUniversalModuleDefinition(root, factory) {
  if (typeof exports === "object" && typeof module === "object") {
    module.exports = factory();
  } else if (typeof define === "function" && define.amd) {
    define([], factory);
  } else if (typeof exports === "object") {
    exports.MyLibrary = factory();
  } else {
    root.MyLibrary = factory();
  }
})(globalThis, () => _entry_return_);

Note that omitting library.name will result in the assignment of all properties returned by the entry point be assigned directly to the root object, as documented under the object assignment section. Example:

export default {
  // ...
  output: {
    type: "umd",
  },
};

The output will be:

(function webpackUniversalModuleDefinition(root, factory) {
  if (typeof exports === "object" && typeof module === "object") {
    module.exports = factory();
  } else if (typeof define === "function" && define.amd) {
    define([], factory);
  } else {
    const a = factory();
    for (const i in a) (typeof exports === "object" ? exports : root)[i] = a[i];
  }
})(globalThis, () => _entry_return_);

You may specify an object for library.name for differing names per targets:

export default {
  // ...
  output: {
    library: {
      name: {
        root: "MyLibrary",
        amd: "my-library",
        commonjs: "my-common-library",
      },
      type: "umd",
    },
  },
};

type: 'system'

This will expose your library as a System.register module. This feature was first released in webpack 4.30.0.

System modules require that a global variable System is present in the browser when the webpack bundle is executed. Compiling to System.register format allows you to System.import('/bundle.js') without additional configuration and has your webpack bundle loaded into the System module registry.

export default {
  // ...
  output: {
    library: {
      type: "system",
    },
  },
};

Output:

System.register([], (__WEBPACK_DYNAMIC_EXPORT__, __system_context__) => ({
  execute() {
    // ...
  },
}));

By adding output.library.name to configuration in addition to having output.library.type set to system, the output bundle will have the library name as an argument to System.register:

System.register(
  "MyLibrary",
  [],
  (__WEBPACK_DYNAMIC_EXPORT__, __system_context__) => ({
    execute() {
      // ...
    },
  }),
);

Other Types

type: 'jsonp'

export default {
  // …
  output: {
    library: {
      name: "MyLibrary",
      type: "jsonp",
    },
  },
};

This will wrap the return value of your entry point into a jsonp wrapper.

MyLibrary(_entry_return_);

The dependencies for your library will be defined by the externals config.

output.library.export

Specify which export should be exposed as a library.

• Type: string | string[]

It is undefined by default, which will export the whole (namespace) object. The examples below demonstrate the effect of this configuration when using output.library.type: 'var'.

export default {
  output: {
    library: {
      name: "MyLibrary",
      type: "var",
      export: "default",
    },
  },
};

The default export of your entry point will be assigned to the library name:

// if your entry has a default export
const MyLibrary = _entry_return_.default;

You can pass an array to output.library.export as well, it will be interpreted as a path to a module to be assigned to the library name:

export default {
  output: {
    library: {
      name: "MyLibrary",
      type: "var",
      export: ["default", "subModule"],
    },
  },
};

And here's the library code:

const MyLibrary = _entry_return_.default.subModule;

output.library.auxiliaryComment

Add a comment in the UMD wrapper.

• Type: string | { amd?: string, commonjs?: string, commonjs2?: string, root?: string }

To insert the same comment for each umd type, set auxiliaryComment to a string:

export default {
  // …
  mode: "development",
  output: {
    library: {
      name: "MyLibrary",
      type: "umd",
      auxiliaryComment: "Test Comment",
    },
  },
};

which will yield the following:

(function webpackUniversalModuleDefinition(root, factory) {
  // Test Comment
  if (typeof exports === "object" && typeof module === "object") {
    module.exports = factory();
  }
  // Test Comment
  else if (typeof define === "function" && define.amd) {
    define([], factory);
  }
  // Test Comment
  else if (typeof exports === "object") {
    exports.MyLibrary = factory();
  }
  // Test Comment
  else {
    root.MyLibrary = factory();
  }
})(globalThis, () => _entry_return_);

For fine-grained control, pass an object:

export default {
  // …
  mode: "development",
  output: {
    library: {
      name: "MyLibrary",
      type: "umd",
      auxiliaryComment: {
        root: "Root Comment",
        commonjs: "CommonJS Comment",
        commonjs2: "CommonJS2 Comment",
        amd: "AMD Comment",
      },
    },
  },
};

output.library.umdNamedDefine

boolean

When using output.library.type: "umd", setting output.library.umdNamedDefine to true will name the AMD module of the UMD build. Otherwise, an anonymous define is used.

export default {
  // ...
  output: {
    library: {
      name: "MyLibrary",
      type: "umd",
      umdNamedDefine: true,
    },
  },
};

The AMD module will be:

define("MyLibrary", [], factory);

output.libraryExport

string [string]

Configure which module or modules will be exposed via the libraryTarget. It is undefined by default, same behaviour will be applied if you set libraryTarget to an empty string e.g. '' it will export the whole (namespace) object. The examples below demonstrate the effect of this configuration when using libraryTarget: 'var'.

The following configurations are supported:

libraryExport: 'default' - The default export of your entry point will be assigned to the library target:

// if your entry has a default export of `MyDefaultModule`
const MyDefaultModule = _entry_return_.default;

libraryExport: 'MyModule' - The specified module will be assigned to the library target:

const { MyModule } = _entry_return_;

libraryExport: ['MyModule', 'MySubModule'] - The array is interpreted as a path to a module to be assigned to the library target:

const { MySubModule } = _entry_return_.MyModule;

With the libraryExport configurations specified above, the resulting libraries could be utilized as such:

MyDefaultModule.doSomething();
MyModule.doSomething();
MySubModule.doSomething();

output.libraryTarget

string = 'var'

Configure how the library will be exposed. Any one of the following options can be used. Please note that this option works in conjunction with the value assigned to output.library. For the following examples, it is assumed that the value of output.library is configured as MyLibrary.

Expose a Variable

These options assign the return value of the entry point (e.g. whatever the entry point exported) to the name provided by output.library at whatever scope the bundle was included at.

libraryTarget: 'var'

When your library is loaded, the return value of your entry point will be assigned to a variable:

const MyLibrary = _entry_return_;

// In a separate script...
MyLibrary.doSomething();

libraryTarget: 'assign'

This will generate an implied global which has the potential to reassign an existing value (use with caution):

MyLibrary = _entry_return_;

Be aware that if MyLibrary isn't defined earlier your library will be set in the global scope.

libraryTarget: 'assign-properties'

Copy the return value to a target object if it exists, otherwise create the target object first:

// create the target object if it doesn't exist
MyLibrary = typeof MyLibrary === "undefined" ? {} : MyLibrary;
// then copy the return value to MyLibrary
// similarly to what Object.assign does

// for instance, you export a `hello` function in your entry as follow
export function hello(name) {
  console.log(`Hello ${name}`);
}

// In another script running MyLibrary
// you can run `hello` function like so
MyLibrary.hello("World");

Expose Via Object Assignment

These options assign the return value of the entry point (e.g. whatever the entry point exported) to a specific object under the name defined by output.library.

If output.library is not assigned a non-empty string, the default behavior is that all properties returned by the entry point will be assigned to the object as defined for the particular output.libraryTarget, via the following code fragment:

(function (e, a) {
  for (const i in a) {
    e[i] = a[i];
  }
})(output.libraryTarget, _entry_return_);

libraryTarget: 'this'

The return value of your entry point will be assigned to this under the property named by output.library. The meaning of this is up to you:

this.MyLibrary = _entry_return_;

// In a separate script...
this.MyLibrary.doSomething();
MyLibrary.doSomething(); // if this is window

libraryTarget: 'window'

The return value of your entry point will be assigned to the window object using the output.library value.

globalThis.MyLibrary = _entry_return_;

globalThis.MyLibrary.doSomething();

libraryTarget: 'global'

The return value of your entry point will be assigned to the global object using the output.library value.

globalThis.MyLibrary = _entry_return_;

globalThis.MyLibrary.doSomething();

libraryTarget: 'commonjs'

The return value of your entry point will be assigned to the exports object using the output.library value. As the name implies, this is used in CommonJS environments.

exports.MyLibrary = _entry_return_;

require("MyLibrary").doSomething();

Module Definition Systems

These options will result in a bundle that comes with a complete header to ensure compatibility with various module systems. The output.library option will take on a different meaning under the following output.libraryTarget options.

libraryTarget: 'module'

Output ES Module. Make sure to enable experiments.outputModule beforehand.

Note that this feature is not fully supported yet, please track the progress in this thread.

libraryTarget: 'commonjs2'

The return value of your entry point will be assigned to the module.exports. As the name implies, this is used in CommonJS environments:

export default _entry_return_;

require("MyLibrary").doSomething();

Note that output.library can't be used with this particular output.libraryTarget, for further details, please read this issue.

libraryTarget: 'amd'

This will expose your library as an AMD module.

AMD modules require that the entry chunk (e.g. the first script loaded by the <script> tag) be defined with specific properties, such as to define and require which is typically provided by RequireJS or any compatible loaders (such as almond). Otherwise, loading the resulting AMD bundle directly will result in an error like define is not defined.

With the following configuration...

export default {
  // ...
  output: {
    library: "MyLibrary",
    libraryTarget: "amd",
  },
};

The generated output will be defined with the name "MyLibrary", i.e.

define("MyLibrary", [], () => _entry_return_);

The bundle can be included as part of a script tag, and the bundle can be invoked like so:

require(["MyLibrary"], (MyLibrary) => {
  // Do something with the library...
});

If output.library is undefined, the following is generated instead.

define([], () => _entry_return_);

This bundle will not work as expected, or not work at all (in the case of the almond loader) if loaded directly with a <script> tag. It will only work through a RequireJS compatible asynchronous module loader through the actual path to that file, so in this case, the output.path and output.filename may become important for this particular setup if these are exposed directly on the server.

libraryTarget: 'amd-require'

This packages your output with an immediately executed AMD require(dependencies, factory) wrapper.

The 'amd-require' target allows for the use of AMD dependencies without needing a separate later invocation. As with the 'amd' target, this depends on the appropriate require function being available in the environment in which the webpack output is loaded.

With this target, the library name is ignored.

libraryTarget: 'umd'

This exposes your library under all the module definitions, allowing it to work with CommonJS, AMD and as a global variable. Take a look at the UMD Repository to learn more.

In this case, you need the library property to name your module:

export default {
  // ...
  output: {
    library: "MyLibrary",
    libraryTarget: "umd",
  },
};

And finally the output is:

(function webpackUniversalModuleDefinition(root, factory) {
  if (typeof exports === "object" && typeof module === "object") {
    module.exports = factory();
  } else if (typeof define === "function" && define.amd) {
    define([], factory);
  } else if (typeof exports === "object") {
    exports.MyLibrary = factory();
  } else {
    root.MyLibrary = factory();
  }
})(
  typeof globalThis.self !== "undefined" ? globalThis : this,
  () => _entry_return_,
);

Note that omitting the library will result in the assignment of all properties returned by the entry point be assigned directly to the root object, as documented under the object assignment section. Example:

export default {
  // ...
  output: {
    libraryTarget: "umd",
  },
};

The output will be:

(function webpackUniversalModuleDefinition(root, factory) {
  if (typeof exports === "object" && typeof module === "object") {
    module.exports = factory();
  } else if (typeof define === "function" && define.amd) {
    define([], factory);
  } else {
    const a = factory();
    for (const i in a) (typeof exports === "object" ? exports : root)[i] = a[i];
  }
})(
  typeof globalThis.self !== "undefined" ? globalThis : this,
  () => _entry_return_,
);

Since webpack 3.1.0, you may specify an object for library for differing names per targets:

export default {
  // ...
  output: {
    library: {
      root: "MyLibrary",
      amd: "my-library",
      commonjs: "my-common-library",
    },
    libraryTarget: "umd",
  },
};

libraryTarget: 'system'

This will expose your library as a System.register module. This feature was first released in webpack 4.30.0.

System modules require that a global variable System is present in the browser when the webpack bundle is executed. Compiling to System.register format allows you to System.import('/bundle.js') without additional configuration and has your webpack bundle loaded into the System module registry.

export default {
  // ...
  output: {
    libraryTarget: "system",
  },
};

Output:

System.register([], (_export) => ({
  setters: [],
  execute() {
    // ...
  },
}));

By adding output.library to configuration in addition to having output.libraryTarget set to system, the output bundle will have the library name as an argument to System.register:

System.register("my-library", [], (_export) => ({
  setters: [],
  execute() {
    // ...
  },
}));

You can access SystemJS context via __system_context__:

// Log the URL of the current SystemJS module
console.log(__system_context__.meta.url);

// Import a SystemJS module, with the current SystemJS module's url as the parentUrl
__system_context__.import("./other-file.js").then((m) => {
  console.log(m);
});

Other Targets

libraryTarget: 'jsonp'

This will wrap the return value of your entry point into a jsonp wrapper.

MyLibrary(_entry_return_);

The dependencies for your library will be defined by the externals config.

output.module

boolean = false

Output JavaScript files as module type. Disabled by default as it's an experimental feature.

When enabled, webpack will set output.iife to false, output.scriptType to 'module' and minimizerOptions.module to true internally.

If you're using webpack to compile a library to be consumed by others, make sure to set output.libraryTarget to 'module' when output.module is true.

export default {
  // ...
  experiments: {
    outputModule: true,
  },
  output: {
    module: true,
  },
};

output.path

string = path.join(process.cwd(), 'dist')

The output directory as an absolute path.

webpack.config.js

import path from "node:path";
import { fileURLToPath } from "node:url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

export default {
  // ...
  output: {
    path: path.resolve(__dirname, "dist/assets"),
  },
};

Note that [fullhash] in this parameter will be replaced with a hash of the compilation. See the Caching guide for details.

output.pathinfo

boolean string: 'verbose'

Tells webpack to include comments in bundles with information about the contained modules. 'verbose' shows more information like exports, runtime requirements and bailouts.

The default value of output.pathinfo depends on the mode:

webpack.config.js

export default {
  // ...
  output: {
    pathinfo: true,
  },
};

output.publicPath

• Type:

  • function

  • string

    output.publicPath defaults to 'auto' with web and web-worker targets, see this guide for its use cases.

This is an important option when using on-demand-loading or loading external resources like images, files, etc. If an incorrect value is specified you'll receive 404 errors while loading these resources.

This option specifies the public URL of the output directory when referenced in a browser. A relative URL is resolved relative to the HTML page (or <base> tag). Server-relative URLs, protocol-relative URLs or absolute URLs are also possible and sometimes required, i. e. when hosting assets on a CDN.

The value of the option is prefixed to every URL created by the runtime or loaders. Because of this the value of this option ends with / in most cases.

A rule to consider: The URL of your output.path from the view of the HTML page.

webpack.config.js

import path from "node:path";
import { fileURLToPath } from "node:url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

export default {
  // ...
  output: {
    path: path.resolve(__dirname, "public/assets"),
    publicPath: "https://cdn.example.com/assets/",
  },
};

For this configuration:

webpack.config.js

export default {
  // ...
  output: {
    publicPath: "/assets/",
    chunkFilename: "[id].chunk.js",
  },
};

A request to a chunk will look like /assets/4.chunk.js.

A loader outputting HTML might emit something like this:

<link href="/assets/spinner.gif" />

or when loading an image in CSS:

background-image: url(/assets/spinner.gif);

The webpack-dev-server also takes a hint from publicPath, using it to determine where to serve the output files from.

Note that [fullhash] in this parameter will be replaced with a hash of the compilation. See the Caching guide for details.

Examples (one of the below):

export default {
  // ...
  output: {
    // It automatically determines the public path from either `import.meta.url`, `document.currentScript`, `<script />` or `self.location`.
    publicPath: "auto",
  },
};

export default {
  // ...
  output: {
    // CDN (always HTTPS)
    publicPath: "https://cdn.example.com/assets/",
  },
};

export default {
  // ...
  output: {
    // CDN (same protocol)
    publicPath: "//cdn.example.com/assets/",
  },
};

export default {
  // ...
  output: {
    // server-relative
    publicPath: "/assets/", // server-relative
  },
};

export default {
  // ...
  output: {
    // relative to HTML page
    publicPath: "assets/",
  },
};

export default {
  // ...
  output: {
    // relative to HTML page
    publicPath: "../assets/",
  },
};

export default {
  // ...
  output: {
    // relative to HTML page (same directory)
    publicPath: "",
  },
};

In cases where the publicPath of output files can't be known at compile time, it can be left blank and set dynamically at runtime in the entry file using the free variable __webpack_public_path__.

__webpack_public_path__ = myRuntimePublicPath;

// rest of your application entry

See this discussion for more information on __webpack_public_path__.

output.resourceHints

boolean 'prefetch' | 'preload' | 'none' HtmlResourceHint[] function object

Controls resource-hint emission (<link rel="prefetch"> / <link rel="preload"> / <link rel="modulepreload"> / <link rel="preconnect">) for extracted HTML entries and URL-referenced assets. Hints are emitted into the extracted HTML <head> for HTML entries and via a chunk-startup JS runtime otherwise, and stats.entrypoints[name].resourceHints exposes the resolved list.

The option accepts the initial dependency-graph shorthand directly (equivalent to { initial: <value> }):

// webpack.config.js
export default {
  // ...
  output: {
    resourceHints: true, // same as { initial: true }
  },
};

Or the object form with the properties documented below:

// webpack.config.js
export default {
  // ...
  output: {
    resourceHints: {
      initial: true,
      preconnect: true,
      manifest: "resource-hints.json",
      urlHints: [{ test: /\.woff2$/, preload: true, as: "font" }],
    },
  },
};

output.resourceHints.initial

boolean 'prefetch' | 'preload' | 'none' HtmlResourceHint[] function