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

``bash


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

`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

`html









`

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:

| Name | Type | Default | Description |
| :-: | :-: | :-: | :-- |
| title | {String} | Rspack App | The title to use for the generated HTML document |
| filename | {String\|Function} | 'index.html' | The file to write the HTML to. Defaults to index.html. You can specify a subdirectory here too (eg: assets/admin.html). The [name] placeholder will be replaced with the entry name. Can also be a function e.g. (entryName) => entryName + '.html'. |
| template | {String} | | Rspack relative or absolute path to the template. By default it will use src/index.ejs if it exists. Please see the docs for details |
| templateContent | {string\|Function\|false} | false | Can be used instead of template to provide an inline template - please read the Writing Your Own Templates section |
| templateParameters | {Boolean\|Object\|Function} | false | Allows to overwrite the parameters used in the template - see example |
| inject | {Boolean\|String} | true | true \|\| 'head' \|\| 'body' \|\| false Inject all assets into the given template or templateContent. When passing 'body' all javascript resources will be placed at the bottom of the body element. 'head' will place the scripts in the head element. Passing true will add it to the head/body depending on the scriptLoading option. Passing false will disable automatic injections. - see the inject:false example |
| publicPath | {String\|'auto'} | 'auto' | The publicPath used for script and link tags |
| scriptLoading | {'blocking'\|'defer'\|'module'\|'systemjs-module'} | 'defer' | Modern browsers support non blocking javascript loading ('defer') to improve the page startup performance. Setting to 'module' adds attribute type="module". This also implies "defer", since modules are automatically deferred. |
| favicon | {String} | | Adds the given favicon path to the output HTML |
| meta | {Object} | {} | Allows to inject meta-tags. E.g. meta: {viewport: 'width=device-width, initial-scale=1, shrink-to-fit=no'} |
| base | {Object\|String\|false} | false | Inject a base tag. E.g. base: "https://example.com/path/page.html |
| minify | (html: string) => string \| Promise | | A function to minify HTML, see minification below for more details. |
| hash | {Boolean} | false | If true then append a unique Rspack compilation hash to all included scripts and CSS files (i.e. main.js?hash=compilation_hash). This is useful for cache busting |
| cache | {Boolean} | true | Emit the file only if it was changed |
| showErrors | {Boolean} | true | Errors details will be written into the HTML page |
| chunks | {?} | ? | Allows you to add only some chunks (e.g only the unit-test chunk) |
| chunksSortMode | {String\|Function} | auto | Allows to control how chunks should be sorted before they are included to the HTML. Allowed values are 'none' \| 'auto' \| 'manual' \| {Function} |
| excludeChunks | {Array.} | | Allows you to skip some chunks (e.g don't add the unit-test chunk) |
| xhtml | {Boolean} | false | If true render the link tags as self-closing (XHTML compliant) |

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

rspack.config.js

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

$3

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

rspack.config.js

`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'
})
]
}
`

$3

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.

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

index.html

`html








`

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

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