Guide
Config
Plugin
API
Community
Guide
Config
Plugin
API
Community

tools.htmlPlugin

  • Type: boolean | Object | Function
  • Default:
const defaultHtmlPluginOptions = {
  inject, // corresponding to the html.inject config
  favicon, // corresponding to html.favicon config
  filename, // generated based on output.distPath and entryName
  template, // defaults to the built-in HTML template path
  templateParameters, // corresponding to the html.templateParameters config
  chunks: [entryName],
  minify: {
    // generated based on output.minify
    removeComments: false,
    useShortDoctype: true,
    keepClosingSlash: true,
    collapseWhitespace: true,
    removeRedundantAttributes: true,
    removeScriptTypeAttributes: true,
    removeStyleLinkTypeAttributes: true,
    removeEmptyAttributes: true,
    minifyJS,
    minifyCSS: true,
    minifyURLs: true,
  },
};

The configs of html-rspack-plugin can be modified through tools.htmlPlugin.

TIP

Rsbuild internally implements HTML-related features based on html-rspack-plugin. It is a fork of html-webpack-plugin, with the same features and options.

Object Type

When tools.htmlPlugin is Object type, the value will be merged with the default config via Object.assign.

export default {
  tools: {
    htmlPlugin: {
      scriptLoading: 'blocking',
    },
  },
};

Function Type

When tools.htmlPlugin is a Function:

  • The first parameter is the default config, which can be modified directly.
  • The second parameter is also an object, containing the entry name and the entry value.
  • The Function can return a new object as the final config.
export default {
  tools: {
    htmlPlugin(config, { entryName, entryValue }) {
      if (entryName === 'main') {
        config.scriptLoading = 'blocking';
      }
    },
  },
};

Disable HTML

Setting tools.htmlPlugin to false can disable the built-in html-rspack-plugin in Rsbuild, and no HTML files will be generated.

export default {
  tools: {
    htmlPlugin: false,
  },
};

Example

Modify HTML File Name

The filename option can be used to modify the file name of the HTML output.

For example, during production builds, a hash can be added to the file name:

export default {
  tools: {
    htmlPlugin(config, { entryName }) {
      if (process.env.NODE_ENV === 'production') {
        config.filename = `${entryName}.[contenthash:8].html`;
      }
    },
  },
};

Disable JS/CSS minify

By default, Rsbuild will compresses JavaScript/CSS code inside HTML during the production build to improve the page performance. This ability is often helpful when using custom templates or inserting custom scripts.

However, when output.inlineScripts or output.inlineStyles is turned on, inline JavaScript/CSS code will be repeatedly compressed, which will have a certain impact on build performance. You can modify the default minify behavior by modifying the tools.htmlPlugin.minify configuration.

export default {
  tools: {
    htmlPlugin: (config) => {
      if (typeof config.minify === 'object') {
        config.minify.minifyJS = false;
        config.minify.minifyCSS = false;
      }
    },
  },
};