Skip to main content

Options for JS

Option: js

type JsOptions = {
  filename?: FilenameTemplate;
  chunkFilename?: FilenameTemplate;
  outputPath?: string;
  inline?: 'auto' | boolean | JsInlineOptions;
};

Default:

{
  filename: '[name].js',
  chunkFilename: '[id].js',
  outputPath: null,
  inline: false,
}

JsOptions Object properties:

  • filename: Specifies the output filename template for JavaScript files.
    For details, see the filename option.
  • chunkFilename: Defines the filename template for non-initial chunks.
  • outputPath: Sets the output directory for JavaScript files. Refer to the outputPath option.
  • inline: Controls JavaScript inlining behavior in HTML.
    Valid values:
    • false: Outputs JavaScript to external files (default).
    • true: Inlines JavaScript via <script> tags.
    • 'auto': Inlines in development mode; outputs files in production.
    • JsInlineOptions: Advanced Inline Configuration

Advanced Inline Configuration​

Type:

type JsInlineOptions = {
  enabled?: 'auto' | boolean;
  chunk?: RegExp | Array<RegExp>;
  source?: RegExp | Array<RegExp>;
  attributeFilter?: (props: {
    attribute: string;
    value: string;
    attributes: { [attributeName: string]: string; };
  }) => boolean | void;
};

JsInlineOptions Object Properties:

  • enabled: Overrides the base inlining behavior. Default: true.
  • chunk: Inlines chunks matching specified regular expression(s).
  • source: Inlines all chunks from source files matching regular expression(s).
  • attributeFilter: Filters attributes for inlined <script> tags.
    Returns:
    • true to retain an attribute.
    • false or undefined to remove it.

Examples​

Attribute Filtering​

To preserve specific attributes during inlining:

Source HTML:

<script id="js-main" src="./main.js" defer></script>

Configuration:

new HtmlBundlerPlugin({
  js: {
    inline: {
      attributeFilter: ({ attribute }) => attribute === 'id',
    },
  },
});

Output HTML:

<script id="js-main">
  // Inlined JavaScript
</script>

Filename template​

new HtmlBundlerPlugin({
  js: {
    filename: "js/[name].[contenthash:8].js",
  },
});

Inline runtime chunks​

Configuration part:

new HtmlBundlerPlugin({
  js: {
    filename: "js/[name].[contenthash:8].js",
    inline: {
      chunk: [/runtime.+[.]js/],
    },
  },
});

Output Behavior:

- `js/app.xxxxxxxx.js`  -> Saved as file.
- `runtime.xxxxxxxx.js` -> Inlined into HTML.
warning

Inlining Webpack’s runtime chunks disables the publicPath: "auto" option. Webpack’s runtime determines the public path using currentScript.src, but inlining removes the src attribute. This causes automatic resolution to fail, and the browser may show: "Automatic publicPath is not supported in this browser".

Possible solutions:

  1. Use an absolute or relative path in output.publicPath.
  2. Set __webpack_public_path__ manually at runtime in your entry point. See Webpack’s guide on setting publicPath on the fly for details.

Chunk Splitting​

Make sure the test field matches only script modules — such as .js, .ts, .mjs, etc — to avoid invalid outputs.

splitChunks: {
  cacheGroups: {
    app: {
      chunks: "all",
      test: /\.[cm]?[tj]s$/i, // Ensure only script files are matched for proper chunk splitting
    },
  },
}

Use a function to target scripts more precisely and to debug which modules are picked.

splitChunks: {
  cacheGroups: {
    app: {
      chunks: "all",
      test: (module) => {
        const match = module.type?.includes("javascript");
        // Match debugging: JavaScript modules in glorious disarray
        if (match) {
          console.log("[app]", module.resource);
        }

        return match && "resource" in module && /\.[cm]?[tj]s$/i.test(module.resource);
      },
    },
  },
}
warning

Omitting the test regex in splitChunks may cause Webpack to generate invalid files. Always restrict splitting to JavaScript/TypeScript files.