html-rspack-plugin

An Rspack plugin for generating HTML files.

Notice

This plugin is forked from jantimon/html-webpack-plugin, it is designed for Rspack and provides better performance than html-webpack-plugin.

The function of this plugin is basically the same as html-webpack-plugin.

> Big thanks to html-webpack-plugin creators and contributors for their great work. ❤️

Diff

Differences with html-webpack-plugin:

• Designed for Rspack
  • Import type from @rspack/core
• Less dependencies
  • Removed html-minifier-terser and allows to use any HTML minimizer
  • Removed lodash dependency with a forked minimal version
  • Removed pretty-error dependency
  • Removed webpack peer dependency
• Performance improvements for Rspack:
  • Removed support for HTML5 Application caches (it has been deprecated)
  • Reuse compilation.entrypoints

Install

# npm
npm add -D html-rspack-plugin

# yarn
yarn add -D html-rspack-plugin

# pnpm
pnpm add -D html-rspack-plugin

Usage

The plugin will generate an HTML5 file for you that includes all your Rspack bundles in the head using script tags. Just add the plugin to your Rspack config as follows:

rspack.config.js

const HtmlRspackPlugin = require('html-rspack-plugin');

module.exports = {
  entry: 'index.js',
  output: {
    path: __dirname + '/dist',
    filename: 'index_bundle.js',
  },
  plugins: [new HtmlRspackPlugin()],
};

This will generate a file dist/index.html containing the following

  
    
    <title>Rspack App</title>
    
  
  

If you have multiple Rspack entry points, they will all be included with script tags in the generated HTML.

If you have any CSS assets in Rspack's output (for example, CSS extracted with the CssExtractRspackPlugin) then these will be included with `` tags in the HTML head.

If you have plugins that make use of it, html-rspack-plugin should be ordered first before any of the integrated Plugins.

Options

You can pass a hash of configuration options to html-rspack-plugin. Allowed values are as follows:

Here's an example Rspack config illustrating how to use these options

rspack.config.js

{
  entry: 'index.js',
  output: {
    path: __dirname + '/dist',
    filename: 'index_bundle.js'
  },
  plugins: [
    new HtmlRspackPlugin({
      title: 'My App',
      filename: 'assets/admin.html'
    })
  ]
}

Generating Multiple HTML Files

To generate more than one HTML file, declare the plugin more than once in your plugins array

rspack.config.js

{
  entry: 'index.js',
  output: {
    path: __dirname + '/dist',
    filename: 'index_bundle.js'
  },
  plugins: [
    new HtmlRspackPlugin(), // Generates default index.html
    new HtmlRspackPlugin({  // Also generate a test.html
      filename: 'test.html',
      template: 'src/assets/test.html'
    })
  ]
}

Writing Your Own Templates

If the default generated HTML doesn't meet your needs you can supply your own template. The easiest way is to use the template option and pass a custom HTML file. The html-rspack-plugin will automatically inject all necessary CSS, JS and favicon files into the markup.

Details of other template loaders are documented here.

plugins: [
  new HtmlRspackPlugin({
    title: 'Custom template',
    // Load a custom template (lodash by default)
    template: 'index.html',
  }),
];

index.html

  
    
    <title>&lt;%= HtmlRspackPlugin.options.title %&gt;</title>
  
  

If you already have a template loader, you can use it to parse the template. Please note that this will also happen if you specify the html-loader and use .html file as template.

rspack.config.js

module: {
  loaders: [
    { test: /\.hbs$/, loader: "handlebars-loader" }
  ]
},
plugins: [
  new HtmlRspackPlugin({
    title: 'Custom template using Handlebars',
    template: 'index.hbs'
  })
]

You can use the lodash.template syntax out of the box. If the inject feature doesn't fit your needs and you want full control over the asset placement, you can write your own template.

The following variables are available in the template by default (you can extend them using the templateParameters option):

• HtmlRspackPlugin: data specific to this plugin

  • HtmlRspackPlugin.options: the options hash that was passed to the plugin. In addition to the options actually used by this plugin, you can use this hash to pass arbitrary data through to your template.

  • HtmlRspackPlugin.tags: the prepared headTags and bodyTags Array to render the , , `