Printable

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"
}

Options

Click on the name of each option in the configuration code below to jump to the detailed documentation. Also note that the items with arrows can be expanded to show more examples and, in some cases, more advanced configurations.

webpack.config.js

const path = require('path');

module.exports = {
  <mode "/configuration/mode">
    <default>
      mode: "production", // "production" | "development" | "none"
    </default>
    mode: "production", // enable many optimizations for production builds
    mode: "development", // enabled useful tools for development
    mode: "none", // no defaults
  </mode>
  // Chosen mode tells webpack to use its built-in optimizations accordingly.
  <entry "/configuration/entry-context/#entry">
    <default>
      entry: "./app/entry", // string | object | array
    </default>
    entry: ["./app/entry1", "./app/entry2"],
    entry: {
      a: "./app/entry-a",
      b: ["./app/entry-b1", "./app/entry-b2"]
    },
    entry: {
      a: {
        import: "./app/entry-a",
        library: { type: "commonjs-module" },
        dependOn: ["vendors"],
        filename: "entries/a.js",
        runtime: "dashboard",
        chunkLoading: "jsonp",
        wasmLoading: "fetch-streaming"
      },
      vendors: ["react", "react-dom"]
    }
  </entry>
  // defaults to ./src
  // Here the application starts executing
  // and webpack starts bundling
  <link "/configuration/output">
    <default>
      output: {
    </default>
  </link>
    // options related to how webpack emits results
    <path "/configuration/output/#outputpath">
      <default>
        path: path.resolve(__dirname, "dist"), // string (default)
      </default>
    </path>
    // the target directory for all output files
    // must be an absolute path (use the Node.js path module)
    <filename "/configuration/output/#outputfilename">
      <default>
        filename: "[name].js", // string (default)
      </default>
      filename: "[contenthash].js", // for long term caching
    </filename>
    // the filename template for entry chunks
    <publicPath "/configuration/output/#outputpublicpath">
      <default>
        publicPath: "/assets/", // string
      </default>
      publicPath: "auto", // determined automatically from script tag (default)
      publicPath: "", // relative to HTML file
      publicPath: "/", // relative to server root
      publicPath: "https://cdn.example.com/", // absolute URL
    </publicPath>
    // the url to the output directory resolved relative to the HTML page
    <library "/configuration/output/#outputlibrary">
      <default>
        library: { // There is also an old syntax for this available (click to show)
      </default>
      // Old syntax:
      library: "MyLibrary", // string,
      libraryTarget: "umd", // = library.type
      auxiliaryComment: "comment", // = library.auxiliaryComment
      libraryExport: "default", // = library.export
    </library>
      <libraryType "/configuration/output/#outputlibrarytype">
        <default>
          type: "umd", // universal module definition
        </default>
        type: "umd2", // universal module definition (but optional externals will use globals)
        type: "commonjs-module", // exported with module.exports
        type: "commonjs2", // old name for "commonjs-module"
        type: "commonjs", // exported as properties to exports
        type: "amd", // defined with AMD define() method
        type: "amd-require", // defined with AMD require() method (can't have exports)
        type: "system", // exported to System.js
        type: "this", // property set on this
        type: "var", // variable defined in root scope (default)
        type: "assign", // blind assignment
        type: "global", // property set to global object as specified in output.globalObject
        type: "window", // property set to window object
        type: "self", // property set to self object
        type: "jsonp", // jsonp wrapper
        type: "module", // EcmaScript Module (not implemented yet)
      </libraryType>
      // the type of the exported library
      <libraryName "/configuration/output/#outputlibraryname">
        <default>
          name: "MyLibrary", // string | string[]
        </default>
        name: ["MyCompany", "MyLibrary"], // Some types support creating nested objects
        name: undefined, // Some types support unnamed library (default)
      </libraryName>
      // the name of the exported library

      <advancedLibrary "#">
        <default>
          /* Advanced output.library configuration (click to show) */
        </default>
        export: "default", // string | string[]
        export: undefined, // expose the whole namespace object resp. module.exports value (default)
        export: "named", // expose named exports
        export: ["named", "property"], // expose nested properties
        // the export of the entry module that should be exposed
        auxiliaryComment: "comment",
        auxiliaryComment: { amd: "comment", commonjs: "comment", commonjs2: "comment", root: "comment" },
        // Add a comment in the UMD wrapper
        umdNamedDefine: false,
        // Use a named define() for the AMD part of the UMD wrapper
      </advancedLibrary>
    },
    uniqueName: "my-application", // (defaults to package.json "name")
    // unique name for this build to avoid conflicts with other builds in the same HTML
    name: "my-config",
    // name of the configuration, shown in output
    <advancedOutput "#">
      <default>
        /* Advanced output configuration (click to show) */
      </default>
      chunkFilename: "[name].js",
      chunkFilename: "[id].js",
      chunkFilename: "[contenthash].js", // for long term caching
      // the filename template for additional chunks
      assetModuleFilename: "[hash][ext][query]", // string
      // the filename template for asset modules
      webassemblyModuleFilename: "[hash].module.wasm", // string
      // the filename template for wasm modules
      sourceMapFilename: "[file].map", // string
      sourceMapFilename: "sourcemaps/[file].map", // string
      // the filename template of the source map location
      devtoolModuleFilenameTemplate: "webpack:///[resource-path]", // string
      // the name template for modules in a devtool
      devtoolFallbackModuleFilenameTemplate: "webpack:///[resource-path]?[hash]", // string
      // the name template for modules in a devtool (used for conflicts)
      crossOriginLoading: "use-credentials", // enum
      crossOriginLoading: "anonymous",
      crossOriginLoading: false,
      // specifies how cross origin request are issued by the runtime
      trustedTypes: false, // boolean (default) | string | object
      // Trusted Types support
      importFunctionName: "import", // string (default)
      // expression that is called when using import()
      // can be replaced to use polyfills
      importMetaName: "import.meta", // string (default)
      // expression that is used when using import.meta
      // can be replaced to use polyfills
    </advancedOutput>
    <expertOutput "#">
      <default>
        /* Expert output configuration 1 (on own risk) */
      </default>
      pathinfo: true, // boolean
      // include useful path info about modules, exports, requests, etc. into the generated code
      charset: true, // string
      // add charset attribute to injected script tags
      chunkLoadTimeout: 120000, // number (default)
      // timeout for loading chunks
      compareBeforeEmit: true, // boolean (default)
      // compare the generated asset with the asset on disk before writing to disk
      strictModuleExceptionHandling: true, // boolean
      // handle errors in module evaluation correctly, but for a performance cost
      devtoolNamespace: "MyLibrary", // string
      // prefix in the source names for devtools
      // defaults to output.uniqueName
      environment: {
        // Properties about the environment
        arrowFunction: true,
        bigIntLiteral: true,
        const: true,
        destructuring: true,
        dynamicImport: true,
        forOf: true,
        module: true
      },
      globalObject: "self", // string (default),
      // expression that points to the global object
      iife: true, // boolean (default)
      // wrap the bundle in a IIFE for isolation
      module: false, // boolean (default)
      // generate a module type javascript file instead of a classic script
      scriptType: "module"
      // adds a type attribute to injected script tags
    </expertOutput>
    <expertOutputB "#">
      <default>
        /* Expert output configuration 2 (on own risk) */
      </default>
      chunkLoading: "jsonp" // "jsonp" | "import-scripts" | "require" | "async-node" | false
      // method of loading chunks
      chunkLoadingGlobal: "myWebpackJsonp", // string
      // name of the global variable used to load chunks
      enabledChunkLoadingTypes: ["jsonp"], // string[]
      // the chunk loading methods that are available
      enabledLibraryTypes: ["var"], // string[]
      // the library types that are available
      enabledWasmLoadingTypes: ["var"], // string[]
      // the wasm loading methods that are available
      chunkFormat: "array-push",
      chunkFormat: "commonjs",
      chunkFormat: false,
      // the format of chunks
      hotUpdateMainFilename: "[fullhash].hot-update.json", // string
      // filename template for HMR manifest
      hotUpdateChunkFilename: "[id].[fullhash].hot-update.js", // string
      // filename template for HMR chunks
      hotUpdateGlobal: "hmrUpdateFunction", // string
      // the name of the global variable used to load hot update chunks
      sourcePrefix: "\t", // string
      // prefix module sources in bundle for better readability
      // but breaks multi-line template strings
      hashFunction: "md4", // string (default)
      // hash function used in general
      hashDigest: "hex", // string (default)
      // hash digest type used
      hashDigestLength: 20, // number (default)
      // length of hashes
      hashSalt: "salt", // string | Buffer
      // an additional hash salt to fix hash related issues or change the hash in general
    </expertOutputB>
  },
  module: {
    // configuration regarding modules
    rules: [
      // rules for modules (configure loaders, parser options, etc.)
      {
        // Conditions:
        test: /\.jsx?$/,
        include: [
          path.resolve(__dirname, "app")
        ],
        exclude: [
          path.resolve(__dirname, "app/demo-files")
        ],
        // these are matching conditions, each accepting a regular expression or string
        // test and include have the same behavior, both must be matched
        // exclude must not be matched (takes preferrence over test and include)
        // Best practices:
        // - Use RegExp only in test and for filename matching
        // - Use arrays of absolute paths in include and exclude to match the full path
        // - Try to avoid exclude and prefer include
        // Each condition can also receive an object with "and", "or" or "not" properties
        // which are an array of conditions.
        issuer: /\.css$/,
        issuer: path.resolve(__dirname, "app"),
        issuer: { and: [ /\.css$/, path.resolve(__dirname, "app") ] },
        issuer: { or: [ /\.css$/, path.resolve(__dirname, "app") ] },
        issuer: { not: [ /\.css$/ ] },
        issuer: [ /\.css$/, path.resolve(__dirname, "app") ], // like "or"
        // conditions for the issuer (the origin of the import)
        <advancedConditions "#">
          <default>
            /* Advanced conditions (click to show) */
          </default>
          resource: /\.css$/,
          // matches the resource of the module, behaves equal to "test" and "include"
          compiler: /html-webpack-plugin/,
          // matches the name of the child compilation
          dependency: "esm", // import-style dependencies
          dependency: "commonjs", // require-style dependencies
          dependency: "amd", // AMD-style dependency
          dependency: "wasm", // WebAssembly imports section
          dependency: "url", // new URL(), url() and similar
          dependency: "worker", // new Worker() and similar
          dependency: "loader", // this.loadModule in loaders
          // matches the type of dependency
          descriptionData: { type: "module" },
          // matches information from the package.json
          mimetype: "text/javascript",
          // matches the mimetype in DataUris
          realResource: /\.css$/,
          // matches the resource but ignores when resource was been renamed
          resourceFragment: "#blah",
          // matches the fragment part of the resource request
          resourceQuery: "?blah"
          // matches the query part of the resource request
        </advancedConditions>

        // Actions:
        loader: "babel-loader",
        // the loader which should be applied, it'll be resolved relative to the context
        options: {
          presets: ["es2015"]
        },
        // options for the loader
        use: [
          // apply multiple loaders and options instead
          "htmllint-loader",
          {
            loader: "html-loader",
            options: {
              // ...
            }
          }
        ],
        <moduleType "#">
          <default>
            type: "javascript/auto",
          </default>
          type: "javascript/auto", // JS with all features
          type: "javascript/esm", // JS enforced to strict ESM
          type: "javascript/dynamic", // JS enforced to non-ESM
          type: "json", // JSON data
          type: "webassembly/async", // WebAssembly as async module
          type: "webassembly/sync", // WebAssembly as sync module
        </moduleType>
        // specifies the module type
        <advancedActions "#">
          <default>
            /* Advanced actions (click to show) */
          </default>
          enforce: "pre",
          enforce: "post",
          // flags to apply these rules, even if they are overridden
          generator: { /* ... */ },
          // Options for the generator (depends on module type)
          parser: { /* ... */ },
          // Options for the parser (depends on module type)
          resolve: { /* ... */ },
          // Resolve options (same as "resolve" in configuration)
          sideEffects: false, // boolean
          // Overrides "sideEffects" from package.json
        </advancedActions>
      },
      {
        oneOf: [
          // ... (rules)
        ]
        // only use one of these nested rules
      },
      {
        // ... (conditions)
        rules: [
          // ... (rules)
        ]
        // use all of these nested rules (combine with conditions to be useful)
      },
    ],
    <advancedModule "#">
      <default>
        /* Advanced module configuration (click to show) */
      </default>
      noParse: [
        /special-library\.js$/
      ],
      // do not parse this module
      unknownContextRequest: ".",
      unknownContextRecursive: true,
      unknownContextRegExp: /^\.\/.*$/,
      unknownContextCritical: true,
      exprContextRequest: ".",
      exprContextRegExp: /^\.\/.*$/,
      exprContextRecursive: true,
      exprContextCritical: true,
      wrappedContextRegExp: /.*/,
      wrappedContextRecursive: true,
      wrappedContextCritical: false,
      // specifies default behavior for dynamic requests
    </advancedModule>
  },
  resolve: {
    // options for resolving module requests
    // (does not apply to resolving of loaders)
    <modules "/configuration/resolve/#resolvemodules">
      <default>
        modules: [
          "node_modules",
          path.resolve(__dirname, "app")
        ],
      </default>
      modules: [ "node_modules" ],
      // A filename (non-absolute) means this folder is looked up
      // in all parent directories
      modules: [ path.resolve(__dirname, "app") ],
      // An absolute path means exactly this folder
    </modules>
    // directories where to look for modules (in order)
    extensions: [".js", ".json", ".jsx", ".css"],
    // extensions that are used
    alias: {
      // a list of module name aliases
      // aliases are imported relative to the current context
      "module": "new-module",
      // alias "module" -> "new-module" and "module/path/file" -> "new-module/path/file"
      "only-module$": "new-module",
      // alias "only-module" -> "new-module", but not "only-module/path/file" -> "new-module/path/file"
      "module": path.resolve(__dirname, "app/third/module.js"),
      // alias "module" -> "./app/third/module.js" and "module/file" results in error
      "module": path.resolve(__dirname, "app/third"),
      // alias "module" -> "./app/third" and "module/file" -> "./app/third/file"
      [path.resolve(__dirname, "app/module.js")]: path.resolve(__dirname, "app/alternative-module.js"),
      // alias "./app/module.js" -> "./app/alternative-module.js"
    },
    <alias "/configuration/resolve/#resolvealias">
      <default>
        /* Alternative alias syntax (click to show) */
      </default>
      alias: [
        {
          name: "module",
          // the old request
          alias: "new-module",
          // the new request
          onlyModule: true
          // if true only "module" is aliased
          // if false "module/inner/path" is also aliased
        }
      ],
    </alias>
    <advancedResolve "/configuration/resolve/">
      <default>
        /* Advanced resolve configuration (click to show) */
      </default>
      conditionNames: ["myCompanyCondition", "..."],
      // conditions used for the "exports" and "imports" field in description file
      roots: [path.resolve(__dirname, "app/root")],
      // locations where to resolve server-relative requests (starting with "/")
      // This behavior is only applied when the request doesn't resolve as absolute path
      fallback: { "events": path.resolve(__dirname, "events.js") },
      // Similar to alias, but only applied when the normal resolving fails
      mainFields: ["main"],
      // properties that are read from description file
      // when a folder is requested
      restrictions: [ /\.js$/, path.resolve(__dirname, "app") ],
      // To successful resolve the result must match these criteria
      cache: true, // boolean
      // enable safe caching of resolving
      // this is safe as it tracks and validates all resolving dependencies
      unsafeCache: true,
      unsafeCache: {},
      // enables unsafe caching for resolved requests
      // this is unsafe as there is no validation
      // but performance improvement is really big
      plugins: [
        // ...
      ],
      // additional plugins applied to the resolver
    </advancedResolve>
    <expertResolve "/configuration/resolve/">
      <default>
        /* Expert resolve configuration (click to show) */
      </default>
      symlinks: true, // (default)
      // follow symlinks to new location
      descriptionFiles: ["package.json"], // (default)
      // files that are read for package description
      aliasFields: ["browser"],
      // properties that are read from description file
      // to alias requests in this package
      exportsFields: ["exports"], // (default)
      // fields in description file that are used for external module request
      importsFields: ["imports"], // (default)
      // fields in description file that are used for internal request
      mainFiles: ["index"],
      // files that are used when resolving in a directory and no mainField applies
      fullySpecified: true, // boolean
      // Input request is already full specified (it includes filename and extension)
      // Module requests are still resolved as usual
      preferRelative: true, // boolean
      // Try to resolve module requests also a relative request
      enforceExtension: false,
      // if true request must not include an extension
      // if false request may already include an extension
      cachePredicate: ({ path, request }) => true,
      // predicate function which selects requests for caching
      cacheWithContext: false, // (default)
      // include context information in cache key
      // This must be set to true when custom plugins resolve depending on
      // those information
      useSyncFileSystemCalls: false, // (default)
      // use sync fs calls instead of async fs calls
      byDependency: { commonjs: { extensions: [".js", "..."] } },
      // change resolving depending on issuer dependency
    </expertResolve>
  },
  performance: {
    <hints "/configuration/performance/#performancehints">
      <default>
        hints: "warning", // enum
      </default>
      hints: "error", // emit errors for perf hints
      hints: false, // turn off perf hints
    </hints>
    maxAssetSize: 200000, // int (in bytes),
    maxEntrypointSize: 400000, // int (in bytes)
    assetFilter: function(assetFilename) {
      // Function predicate that provides asset filenames
      return assetFilename.endsWith('.css') || assetFilename.endsWith('.js');
    }
  },
  <devtool "/configuration/devtool">
    <default>
      devtool: "source-map", // enum
    </default>
    devtool: "inline-source-map", // inlines SourceMap into original file
    devtool: "hidden-source-map", // SourceMap without reference in original file
    devtool: "eval-source-map", // inlines SourceMap per module
    devtool: "cheap-source-map", // cheap-variant of SourceMap without module mappings
    devtool: "cheap-module-source-map", // cheap-variant of SourceMap with module mappings
    devtool: "eval-cheap-module-source-map", // like above but per module
    devtool: "eval", // no SourceMap, but named modules. Fastest at the expense of detail.
    devtool: false, // no SourceMap
  </devtool>
  // enhance debugging by adding meta info for the browser devtools
  // source-map most detailed at the expense of build speed.
  context: __dirname, // string (absolute path!)
  // the home directory for webpack
  // the entry and module.rules.loader option
  //   is resolved relative to this directory
  <target "/configuration/target">
    <default>
      target: "web", // enum
    </default>
    target: "browserslist", // use browserslist
    target: "browserslist:modern", // use browserslist "modern" preset
    target: "browserslist:Chrome >= 43", // use browserslist query
    target: `browserslist:${path.resolve(__dirname, "browserslist.json")}`,
    target: `browserslist:${path.resolve(__dirname, "browserslist.json")}:modern`,
    target: "webworker", // WebWorker
    target: "node", // Node.js via require
    target: "node10.13", // Node.js via require
    target: "async-node10.13", // Node.js via fs and vm
    target: "nwjs0.43", // nw.js
    target: "electron11.0-main", // electron, main process
    target: "electron11-renderer", // electron, renderer process
    target: "electron-preload", // electron, preload script
    target: ["web", "es5"], // combining targets
    target: ["web", "es2020"],
    target: false, // custom target, via plugin
  </target>
  // the environment in which the bundle should run
  // changes chunk loading behavior, available external modules
  // and generated code style
  <externals "/configuration/externals">
    <default>
      externals: ["react", /^@angular/],
    </default>
    externals: "react", // string (exact match)
    externals: /^[a-z\-]+($|\/)/, // Regex
    externals: { // object
      angular: "this angular", // this["angular"]
      react: { // UMD
        commonjs: "react",
        commonjs2: "react",
        amd: "react",
        root: "React"
      }
    },
    externals: ({ context, request }, callback) => { /* ... */ callback(null, "commonjs " + request); }
  </externals>
  // Don't follow/bundle these modules, but request them at runtime from the environment
  <externalsType "/configuration/externals">
    <default>
      externalsType: "var", // (defaults to output.library.type)
    </default>
    externalsType: "this", // this["EXTERNAL"]
    externalsType: "window", // window["EXTERNAL"]
    externalsType: "self", // self["EXTERNAL"]
    externalsType: "global", // property from output.globalObject
    externalsType: "commonjs", // require("EXTERNAL")
    externalsType: "amd", // define(["EXTERNAL"], ...), only with AMD library
    externalsType: "umd", // only with UMD library
    externalsType: "system", // only with System.js library
    externalsType: "jsonp", // only with jsonp library
    externalsType: "import", // import("EXTERNAL")
    externalsType: "module", // import X from "EXTERNAL"
    externalsType: "var", // EXTERNAL (name is an expression)
    externalsType: "promise", // await EXTERNAL (name is an expression giving a Promise)
  </externalsType>
  // Type of externals, when not specified inline in externals
  <externalsPresets "#">
    <default>
      externalsPresets: { /* ... */ },
    </default>
    externalsPresets: {
      electron: true,
      electronMain: true,
      electronPreload: true,
      electronRenderer: true,
      node: true,
      nwjs: true,
      web: true,
      webAsync: true,
    }
  </externalsPresets>
  // presets of externals
  <ignoreWarnings "#">
    <default>
      ignoreWarnings: [/warning/],
    </default>
    ignoreWarnings: [
      /warning/,
      {
        file: /asset/,
        module: /module/,
        message: /warning/,
      },
      (warning, compilation) => true
    ],
  </ignoreWarnings>
  <stats "/configuration/stats">
    <default>
      stats: "errors-only",
    </default>
    stats: "verbose", // nearly all information
    stats: "detailed", // much information
    stats: "minimal", // summarized information
    stats: "errors-warnings", // only errors and warnings
    stats: "errors-only", // only errors
    stats: "summary", // only one line summary
    stats: "none", // none at all
  </stats>
  stats: {
    // lets you precisely control what bundle information gets displayed
    <preset "/configuration/stats/#stats-presets">
      <default>
        preset: "errors-only",
      </default>
      preset: "verbose", // nearly all information
      preset: "detailed", // much information
      preset: "minimal", // summarized information
      preset: "errors-warnings", // only errors and warnings
      preset: "errors-only", // only errors
      preset: "summary", // only one line summary
      preset: "none", // none at all
    </preset>
    // A stats preset

    <advancedGlobal "/configuration/stats/">
      <default>
        /* Advanced global settings (click to show) */
      </default>
      all: false,
      // switch all flags on or off
      colors: true,
      // switch colors on and off
      context: __dirname,
      // all paths will be relative to this directory
      ids: true,
      // include module and chunk ids in the output
    </advancedGlobal>

    env: true,
    // include value of --env in the output
    outputPath: true,
    // include absolute output path in the output
    publicPath: true,
    // include public path in the output

    assets: true,
    // show list of assets in output
    <advancedAssets "/configuration/stats/">
      <default>
        /* Advanced assets settings (click to show) */
      </default>
      assetsSort: "size",
      // sorting of assets
      assetsSpace: 50,
      // number of asset lines to display
      cachedAssets: false,
      // show assets that are caching in output
      excludeAssets: /\.png$/,
      // hide some assets
      groupAssetsByPath: true,
      // group assets by their path in the output directory
      groupAssetsByExtension: true,
      // group assets by their extension
      groupAssetsByEmitStatus: true,
      // group assets depending if they are cached, emitted or compared
      groupAssetsByChunk: true,
      // group assets by how they relate to chunks
      groupAssetsByInfo: true,
      // group assets by meta information like immutable, development, etc.
      relatedAssets: true,
      // show assets that are related to other assets, like SourceMaps, compressed version, etc.
      performance: true,
      // show performance hints next to assets and modules
    </advancedAssets>

    entrypoints: true,
    // show entrypoints list
    chunkGroups: true,
    // show named chunk group list
    <advancedChunkGroups "/configuration/stats/">
      <default>
        /* Advanced chunk group settings (click to show) */
      </default>
      chunkGroupAuxiliary: true,
      // show auxiliary assets for entrypoints/chunk groups
      chunkGroupChildren
      // show child chunk groups for entrypoints/chunk groups
      chunkGroupMaxAssets: 5,
      // collapse chunk group assets lists when this limit has been reached
    </advancedChunkGroups>

    chunks: true,
    // show list of chunks in output
    <advancedChunks "/configuration/stats/">
      <default>
        /* Advanced chunk group settings (click to show) */
      </default>
      chunksSort: "size",
      // sort chunks list
      chunkModules: true,
      // show modules contained in each chunk
      chunkOrigins: true,
      // show the origin of a chunk (why was this chunk created)
      chunkRelations: true,
      // show relations to other chunks (parents, children, siblings)
      dependentModules: true,
      // show modules that are dependencies of other modules in that chunk
    </advancedChunks>

    modules: true,
    // show list of modules in output
    <advancedModules "/configuration/stats/">
      <default>
        /* Advanced module settings (click to show) */
      </default>
      modulesSpace: 50,
      // number of modules lines to display
      nestedModules: true,
      // show nested modules (when concatenated)
      cachedModules: true,
      // show modules that were cached
      orphanModules: true,
      // show modules that are not referenced in optimized graph anymore
      excludeModules: /\.css$/,
      // hide some modules
      reasons: true,
      // show the reasons why modules are included
      source: true,
      // include the Source Code of modules (only in JSON)
    </advancedModules>
    <expertModules "/configuration/stats/">
      <default>
        /* Expert module settings (click to show) */
      </default>
      modulesSort: "size",
      // sort modules list
      groupModulesByPath: true,
      // group modules by their resource path
      groupModulesByExtension: true
      // group modules by their extension
      groupModulesByAttributes: true
      // group modules by attributes like if the have errors/warnings/assets
      // or are optional
      groupModulesByCacheStatus: true,
      // group modules depending if they are built, code was generated or if
      // they are cacheable in general
      depth: true,
      // show depth in the module graph of modules
      moduleAssets: true,
      // show assets emitted by modules in module list
      runtimeModules: true,
      // show runtime modules in the modules list
    </expertModules>

    <advancedStatsOptimization "/configuration/stats/">
      <default>
        /* Advanced optimization settings (click to show) */
      </default>
      providedExports: true,
      // show exports provided by modules
      usedExports: true,
      // show which exports are used by modules
      optimizationBailout: true,
      // show information why optimizations bailed out for modules
    </advancedStatsOptimization>

    children: true,
    // show stats for child compilations

    logging: true,
    // show logging in output
    loggingDebug: /webpack/,
    // show debug type logging for some loggers
    loggingTrace: true,
    // show stack traces for warnings and errors in logging output

    warnings: true,
    // show warnings

    errors: true,
    // show errors
    errorDetails: true,
    // show details for errors
    errorStack: true,
    // show internal stack trace for errors
    moduleTrace: true,
    // show module trace for errors
    // (why was causing module referenced)

    builtAt: true,
    // show timestamp in summary
    errorsCount: true,
    // show errors count in summary
    warningsCount: true,
    // show warnings count in summary
    timings: true,
    // show build timing in summary
    version: true,
    // show webpack version in summary
    hash: true,
    // show build hash in summary
  },
  devServer: {
    proxy: { // proxy URLs to backend development server
      '/api': 'http://localhost:3000'
    },
    static: path.join(__dirname, 'public'), // boolean | string | array | object, static file location
    compress: true, // enable gzip compression
    historyApiFallback: true, // true for index.html upon 404, object for multiple paths
    hot: true, // hot module replacement. Depends on HotModuleReplacementPlugin
    https: false, // true for self-signed, object for cert authority
    // ...
  },
  experiments: {
    asyncWebAssembly: true,
    // WebAssembly as async module (Proposal)
    syncWebAssembly: true,
    // WebAssembly as sync module (deprecated)
    outputModule: true,
    // Allow to output ESM
    topLevelAwait: true,
    // Allow to use await on module evaluation (Proposal)
  },
  plugins: [
    // ...
  ],
  // list of additional plugins
  optimization: {
    chunkIds: "size",
    // method of generating ids for chunks
    moduleIds: "size",
    // method of generating ids for modules
    mangleExports: "size",
    // rename export names to shorter names
    minimize: true,
    // minimize the output files
    minimizer: [new CssMinimizer(), "..."],
    // minimizers to use for the output files

    <advancedOptimization "#">
      <default>
        /* Advanced optimizations (click to show) */
      </default>
      concatenateModules: true,
      // concatenate multiple modules into a single one
      emitOnErrors: true,
      // emit output files even if there are build errors
      flagIncludedChunks: true,
      // avoid downloading a chunk if it's fully contained in
      // an already loaded chunk
      innerGraph: true,
      // determine references without modules between symbols
      mergeDuplicateChunks: true,
      // merge chunks if they are equal
      nodeEnv: "production",
      // value of process.env.NODE_ENV inside of modules
      portableRecords: true,
      // use relative paths in records
      providedExports: true,
      // determine which exports are exposed by modules
      usedExports: true,
      // determine which exports are used by modules and
      // remove the unused ones
      realContentHash: true,
      // calculate a contenthash for assets based on the content
      removeAvailableModules: true,
      // run extra pass to determine modules that are already in
      // parent chunks and remove them
      removeEmptyChunks: true,
      // remove chunks that are empty
      runtimeChunk: "single",
      // change placement of runtime code
      sideEffects: true,
      // skip modules that are side effect free when using reexports
    </advancedOptimization>

    splitChunks: {
      cacheGroups: {
        "my-name": {
          // define groups of modules with specific
          // caching behavior
          test: /\.sass$/,
          type: "css/mini-extract",

          <cacheGroupAdvancedSelectors "#">
            <default>
              /* Advanced selectors (click to show) */
            </default>
            chunks: "async",
            minChunks: 1,
            enforceSizeThreshold: 100000,
            minSize: 0,
            minRemainingSize: 0,
            usedExports: true,
            maxAsyncRequests: 30,
            maxInitialRequests: 30,
          </cacheGroupAdvancedSelectors>

          <cacheGroupAdvancedEffects "#">
            <default>
              /* Advanced effects (click to show) */
            </default>
            maxAsyncSize: 200000,
            maxInitialSize: 100000,
            maxSize: 200000,
            filename: "my-name-[contenthash].js",
            idHint: "my-name",
            name: false,
            hidePathInfo: true,
            automaticNameDelimiter: "-",
          </cacheGroupAdvancedEffects>
        }
      },

      <fallbackCacheGroup "#">
        <default>
          fallbackCacheGroup: { /* Advanced (click to show) */ }
        </default>
        fallbackCacheGroup: {
          automaticNameDelimiter: "-"
          minSize: 20000,
          maxAsyncSize: 200000,
          maxInitialSize: 100000,
          maxSize: 200000,
        },
      </fallbackCacheGroup>

      <advancedSelectors "#">
        <default>
          /* Advanced selectors (click to show) */
        </default>
        chunks: "all",
        // select which chunks should be optimized
        usedExports: true,
        // treat modules as equal only when used exports are equal
        minChunks: 1,
        // minimum number of chunks a module must be in
        enforceSizeThreshold: 100000,
        // ignore when following criteria when size of modules
        // is above this threshold
        minSize: 20000,
        // size of modules must be above this threshold
        minRemainingSize: 20000,
        // when modules are removed from a single chunk
        // the size of the modules that are remaining
        // must be above this threshold
        maxAsyncRequests: 30,
        maxInitialRequests: 30,
        // number of parallel requests for a single on demand loading
        // resp. entrypoint but be above this threshold
      </advancedSelectors>

      <advancedEffects "#">
        <default>
          /* Advanced effects (click to show) */
        </default>
        maxAsyncSize: 200000,
        maxInitialSize: 100000,
        maxSize: 200000,
        // when size of modules in the new chunk is above this
        // threshold, split it further
        filename: "[contenthash].js",
        // give the new chunk a different filename
        name: false, // false | string | (module, chunks, key) => string
        // give the new chunk a different name
        // when an existing name is used, chunks are merged
        // non-splitChunks chunks can only be selected, when they are
        // a parent or sibling chunk of all selected modules
        hidePathInfo: true,
        // hide path info when splitting via "maxSize"
        automaticNameDelimiter: "-",
        // use this separator to separate original name from path info
        // when splitting via "maxSize"
      </advancedEffects>

      <expert "#">
        <default>
          /* Expert settings (click to show) */
        </default>
        defaultSizeTypes: ["javascript", "..."]
        // when using numbers for sizes measure these size types
        // minSize: { javascript: 10000 } allows to be more specific
      </expert>
    }
  },
  <advanced "#">
    <default>
      /* Advanced configuration (click to show) */
    </default>
    loader: { /* ... */ },
    // add custom API or properties to loader context
    resolveLoader: { /* same as resolve */ }
    // separate resolve options for loaders
    node: {
      // Polyfills and mocks to run Node.js-
      // environment code in non-Node environments.
      global: true, // boolean
      // replace "global" with the output.globalObject
      __filename: "mock", // boolean | "mock" | "eval-only"
      __dirname: "mock", // boolean | "mock" | "eval-only"
      // true: includes the real path
      // "mock": includes a fake path
      // "eval-only": only defines it at compile-time
      // false: disables all handling
    },
    recordsPath: path.resolve(__dirname, "build/records.json"),
    recordsInputPath: path.resolve(__dirname, "build/records.json"),
    recordsOutputPath: path.resolve(__dirname, "build/records.json"),
    // store ids into a file to make the build even more deterministic
  </advanced>
  <advancedCaching "#">
    <default>
      /* Advanced caching configuration (click to show) */
    </default>
    cache: false, // boolean
    // disable/enable caching
    snapshot: {
      managedPaths: [ path.resolve(__dirname, "node_modules") ],
      // paths that are snapshot using only package.json name and version
      immutablePaths: [ path.resolve(__dirname, ".yarn/cache") ],
      // paths that doesn't need to be snapshot as they are immutable
      module: { timestamp: true, hash: true },
      resolve: { timestamp: true, hash: false },
      resolveBuildDependencies: { timestamp: true, hash: false },
      buildDependencies: { timestamp: true, hash: true },
      // snapshot method for different operations
    },
    watch: true, // boolean
    // enables watching
    watchOptions: {
      aggregateTimeout: 1000, // in ms
      // aggregates multiple changes to a single rebuild
      poll: true,
      poll: 500, // interval in ms
      // enables polling mode for watching
      // must be used on filesystems that doesn't notify on change
      // i. e. nfs shares
    },
  </advancedCaching>
  <advancedBuild "#">
    <default>
      /* Advanced build configuration (click to show) */
    </default>
    infrastructureLogging: {
      level: "none",
      level: "error",
      level: "warn",
      level: "info", // (default)
      level: "log",
      level: "verbose",
      debug: true,
      debug: /webpack/,
      debug: [ "MyPlugin", /webpack/ ]
    },
    parallelism: 1, // number
    // limit the number of parallel processed modules
    profile: true, // boolean
    // capture timing information
    bail: true, //boolean
    // fail out on the first error instead of tolerating it.
    dependencies: ["name"],
    // When using an array of configs this can be used to reference other
    // configs and let this config run after the other config at initial build
  </advancedBuild>
}

Use webpack-cli's init command to rapidly generate webpack configuration files for your project requirements, it will ask you a couple of questions before creating a configuration file.

npx webpack-cli init

npx might prompt you to install @webpack-cli/init 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 configuration generation.

npx webpack-cli init

ℹ INFO For more information and a detailed description of each question, have a look at https://github.com/webpack/webpack-cli/blob/master/INIT.md
ℹ INFO Alternatively, run `webpack(-cli) --help` for usage info.

? Will your application have multiple bundles? No
? Which module will be the first to enter the application? [default: ./src/index]
? Which folder will your generated bundles be in? [default: dist]:
? Will you be using ES2015? Yes
? Will you use one of the below CSS solutions? No

+ babel-plugin-syntax-dynamic-import@6.18.0
+ uglifyjs-webpack-plugin@2.0.1
+ webpack-cli@3.2.3
+ @babel/core@7.2.2
+ babel-loader@8.0.4
+ @babel/preset-env@7.1.0
+ webpack@4.29.3
added 124 packages from 39 contributors, updated 4 packages and audited 25221 packages in 7.463s
found 0 vulnerabilities


Congratulations! Your new webpack configuration file has been created!

Configuration Languages

Webpack accepts configuration files written in multiple programming and data languages. The list of supported file extensions can be found in the node-interpret package. Using node-interpret, webpack can handle many different types of configuration files.

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 @types/webpack
# 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 * as path from 'path';
import * as webpack from 'webpack';
// in case you run into any typescript error when configuring `devServer`
import 'webpack-dev-server';

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

export default config;

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.

Note that you'll also need to check your tsconfig.json file. If the module in compilerOptions in tsconfig.json is commonjs, the setting is complete, else webpack will fail with an error. This occurs because ts-node does not support any module syntax other than 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

HtmlWebpackPlugin = require('html-webpack-plugin')
webpack = require('webpack')
path = require('path')

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

module.exports = 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>
);

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.

-module.exports = {
+module.exports = function(env, argv) {
+  return {
+    mode: env.production ? 'production' : 'development',
+    devtool: env.production ? 'source-map' : 'eval',
     plugins: [
       new TerserPlugin({
         terserOptions: {
+          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.

module.exports = () => {
  return 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:

module.exports = [
  {
    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

module.exports = [
  {
    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

module.exports = [
  {
    //config-1
  },
  {
    //config-2
  },
];
module.exports.parallelism = 1;

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.

const path = require('path');

module.exports = {
  //...
  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 }} (function() => string | [string] | object = { <key> string | [string] } | object = { import string | [string], dependOn string | [string], filename string })

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.

module.exports = {
  //...
  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:

module.exports = {
  //...
  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
    },
  },
};

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

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:

module.exports = {
  //...
  entry: {
    app: './app.js',
    home: { import: './contact.js', filename: 'pages/[name][ext]' },
    about: { import: './about.js', filename: 'pages/[name][ext]' },
  },
};

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:

module.exports = {
  //...
  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:

module.exports = {
  //...
  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:

module.exports = {
  //...
  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.

module.exports = {
  //...
  entry: () => './demo',
};

or

module.exports = {
  //...
  entry: () => new Promise((resolve) => resolve(['./demo', './demo2'])),
};

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

module.exports = {
  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.

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:

module.exports = {
  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
module.exports = {
  mode: 'development',
};

Mode: production

// webpack.production.config.js
module.exports = {
  mode: 'production',
};

Mode: none

// webpack.custom.config.js
module.exports = {
  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:

var config = {
  entry: './app.js',
  //...
};

module.exports = (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]'

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

module.exports = {
  //...
  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

module.exports = {
  //...
  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, function (__WEBPACK_EXTERNAL_MODULE_1__) {
  // ...
});

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

webpack.config.js

module.exports = {
  //...
  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

module.exports = {
  //...
  output: {
    //...
    chunkFilename: '[id].js',
  },
};

Usage as a function:

webpack.config.js

module.exports = {
  //...
  output: {
    chunkFilename: (pathData) => {
      return 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

module.exports = {
  //...
  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

module.exports = {
  //...
  output: {
    //...
    chunkLoadTimeout: 30000,
  },
};

output.chunkLoadingGlobal

string = 'webpackChunkwebpack'

The global variable is used by webpack for loading chunks.

webpack.config.js

module.exports = {
  //...
  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

module.exports = {
  //...
  output: {
    //...
    chunkLoading: 'async-node',
  },
};

output.clean

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

module.exports = {
  //...
  output: {
    clean: true, // Clean the output directory before emit.
  },
};

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

module.exports = {
  //...
  output: {
    clean: {
      keep: /ignored\/dir\//, // Keep these assets under 'ignored/dir'.
    },
  },
};

// or

module.exports = {
  //...
  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.

module.exports = {
  //...
  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.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

module.exports = {
  //...
  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:

module.exports = {
  //...
  output: {
    devtoolModuleFilenameTemplate: (info) => {
      return `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.

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

module.exports = {
  //...
  output: {
    //...
    enabledChunkLoadingTypes: ['jsonp', 'require'],
  },
};

output.enabledLibraryTypes

[string]

List of library types enabled for use by entry points.

module.exports = {
  //...
  output: {
    enabledLibraryTypes: ['module'],
  },
};

output.enabledWasmLoadingTypes

[string]

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

module.exports = {
  //...
  output: {
    enabledWasmLoadingTypes: ['fetch'],
  },
};

output.environment

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

module.exports = {
  output: {
    environment: {
      // The environment supports arrow functions ('() => { ... }').
      arrowFunction: true,
      // The environment supports BigInt as literal (123n).
      bigIntLiteral: false,
      // The environment supports const and let for variable declarations.
      const: true,
      // The environment supports destructuring ('{ a, b } = obj').
      destructuring: true,
      // The environment supports an async import() function to import EcmaScript modules.
      dynamicImport: false,
      // The environment supports 'for of' iteration ('for (const x of array) { ... }').
      forOf: true,
      // The environment supports ECMAScript Module syntax to import ECMAScript modules (import ... from '...').
      module: false,
      // The environment supports optional chaining ('obj?.a' or 'obj?.()').
      optionalChaining: true,
      // The environment supports template literals.
      templateLiteral: true,
    },
  },
};

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

module.exports = {
  //...
  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

module.exports = {
  //...
  output: {
    filename: '[name].bundle.js',
  },
};

Using internal chunk id:

webpack.config.js

module.exports = {
  //...
  output: {
    filename: '[id].bundle.js',
  },
};

Using hashes generated from the generated content:

webpack.config.js

module.exports = {
  //...
  output: {
    filename: '[contenthash].bundle.js',
  },
};

Combining multiple substitutions:

webpack.config.js

module.exports = {
  //...
  output: {
    filename: '[name].[contenthash].bundle.js',
  },
};

Using the function to return the filename:

webpack.config.js

module.exports = {
  //...
  output: {
    filename: (pathData) => {
      return 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.

Note this option does not affect output files for on-demand-loaded chunks. It only affects output files that are initially loaded. For on-demand-loaded chunk files, the output.chunkFilename option is used. Files created by loaders also aren't affected. In this case, you would have to try the specific loader's available options.

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:

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.

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 = 'window'

When targeting a library, especially when libraryTarget 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.

For example:

webpack.config.js

module.exports = {
  // ...
  output: {
    library: 'myLib',
    libraryTarget: '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.

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.

module.exports = {
  //...
  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

module.exports = {
  //...
  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.iife

boolean = true

Tells webpack to add IIFE wrapper around emitted code.

module.exports = {
  //...
  output: {
    iife: 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

module.exports = {
  //...
  output: {
    importFunctionName: '__import__',
  },
};

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

module.exports = {
  // …
  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.

   module.exports = {
     // …
     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:

   module.exports = {
     // …
     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:

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

   module.exports = {
     // …
     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.name

module.exports = {
  // …
  output: {
    library: {
      name: 'MyLibrary',
    },
  },
};

Specify a name for the library.

• Type:

  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', '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'

module.exports = {
  // …
  output: {
    library: {
      name: 'MyLibrary',
      type: 'var',
    },
  },
};

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

var MyLibrary = _entry_return_;

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

type: 'assign'

module.exports = {
  // …
  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'

module.exports = {
  // …
  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'

module.exports = {
  // …
  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'

module.exports = {
  // …
  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.

window['MyLibrary'] = _entry_return_;

window.MyLibrary.doSomething();

type: 'global'

module.exports = {
  // …
  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.

global['MyLibrary'] = _entry_return_;

global.MyLibrary.doSomething();

type: 'commonjs'

module.exports = {
  // …
  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'

module.exports = {
  // …
  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: 'commonjs2'

module.exports = {
  // …
  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:

module.exports = _entry_return_;

require('MyLibrary').doSomething();

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

type: 'commonjs-static'

module.exports = {
  // …
  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...

module.exports = {
  //...
  output: {
    library: {
      name: 'MyLibrary',
      type: 'amd',
    },
  },
};

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

define('MyLibrary', [], function () {
  return _entry_return_;
});

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

require(['MyLibrary'], function (MyLibrary) {
  // Do something with the library...
});

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

define(function () {
  return _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'

module.exports = {
  //...
  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:

module.exports = {
  //...
  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();
})(global, function () {
  return _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:

module.exports = {
  //...
  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 {
    var a = factory();
    for (var i in a) (typeof exports === 'object' ? exports : root)[i] = a[i];
  }
})(global, function () {
  return _entry_return_;
});

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

module.exports = {
  //...
  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.

module.exports = {
  //...
  output: {
    library: {
      type: 'system',
    },
  },
};

Output:

System.register([], function (__WEBPACK_DYNAMIC_EXPORT__, __system_context__) {
  return {
    execute: function () {
      // ...
    },
  };
});

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',
  [],
  function (__WEBPACK_DYNAMIC_EXPORT__, __system_context__) {
    return {
      execute: function () {
        // ...
      },
    };
  }
);

Other Types

type: 'jsonp'

module.exports = {
  // …
  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'.

module.exports = {
  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
var 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:

module.exports = {
  output: {
    library: {
      name: 'MyLibrary',
      type: 'var',
      export: ['default', 'subModule'],
    },
  },
};

And here's the library code:

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

module.exports = {
  // …
  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();
})(self, function () {
  return __entry_return_;
});

For fine-grained control, pass an object:

module.exports = {
  // …
  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.

module.exports = {
  //...
  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`
var MyDefaultModule = _entry_return_.default;

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

var MyModule = _entry_return_.MyModule;

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

var MySubModule = _entry_return_.MyModule.MySubModule;

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:

var 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 (var 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.

window['MyLibrary'] = _entry_return_;

window.MyLibrary.doSomething();

libraryTarget: 'global'

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

global['MyLibrary'] = _entry_return_;

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

module.exports = _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...

module.exports = {
  //...
  output: {
    library: 'MyLibrary',
    libraryTarget: 'amd',
  },
};

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

define('MyLibrary', [], function () {
  return _entry_return_;
});

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

require(['MyLibrary'], function (MyLibrary) {
  // Do something with the library...
});

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

define([], function () {
  return _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:

module.exports = {
  //...
  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 self !== 'undefined' ? self : this, function () {
  return _entry_return_;
});