rspack.HtmlRspackPlugin
is a high-performance HTML plugin implemented in Rust. You can use it to generate HTML files for Rspack projects.
Before using rspack.HtmlRspackPlugin
, please note that there are some differences between rspack.HtmlRspackPlugin
and the community html-webpack-plugin.
Because rspack.HtmlRspackPlugin
is implemented in Rust, its build performance is significantly better than html-webpack-plugin, especially in scenarios where many HTML files are being built.
The features of rspack.HtmlRspackPlugin
are a subset of html-webpack-plugin
. To ensure the performance of the plugin, we have not implemented all the features provided by html-webpack-plugin.
If its options do not meet your needs, you can also directly use the community html-webpack-plugin.
rspack.HtmlRspackPlugin
does not support the full ejs
syntax; it only supports a subset of the ejs
syntax. If you need full ejs
syntax support, you can use html-webpack-plugin
directly.
In order to align the default template syntax of html-webpack-plugin
, Rspack changed the default EJS escape and unescape to be the same as html-webpack-plugin
's default syntax.
Only the following basic interpolation expressions and some control statements are supported. Here, the interpolation expressions only support the most basic string types and do not support arbitrary JavaScript expressions. Other EJS syntaxes are currently not supported.
Escapes the content within the interpolation:
Does not escape the content within the interpolation:
Use the for in
statement to implement list traversal and the if
statement to implement conditional judgment:
The plugin will generate an HTML file for you that includes all your JS outputs in the head using <script>
tags.
Just add the plugin to your Rspack config like this:
This will generate a file dist/index.html
containing the following:
If you have multiple entry points in your Rspack config, they will all be included with <script>
tags in the generated HTML.
If you have some CSS assets in the build outputs, they will be included with <link>
tags in the HTML head.
You can pass some configuration options to rspack.HtmlRspackPlugin
. Allowed options are as follows:
{}
Name | Type | Default | Description |
---|---|---|---|
title | string|undefined | undefined | The title to use for the generated HTML document. |
filename | string|undefined | 'index.html' | The file to write the HTML to. Defaults to index.html . You can specify a subdirectory here too (eg: pages/index.html). |
template | string|undefined | undefined | The template file path |
templateContent | string|undefined|((params: Record<string, any>) => string | Promise<string>) | undefined | The template file content, priority is greater than template. When using a function, pass in the template parameters and use the returned string as the template content. |
templateParameters | Record<string, string>|(oldParams: params: Record<string, any>) => Record<string, any> | Promise<Record<string, any>> | {} | Allows to overwrite the parameters used in the template. When using a function, pass in the original template parameters and use the returned object as the final template parameters. |
inject | 'head' | 'body' | false | undefined | undefined | The script and link tag inject position in template . Use false to not inject. If not specified, it will be automatically determined based on scriptLoading . |
publicPath | string | '' | The publicPath used for script and link tags. |
scriptLoading | 'blocking'|'defer'|'module'|'systemjs-module'|undefined | '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. |
chunks | string[]|undefined | undefined | Allows you to add only some chunks. |
excludeChunks | string[]|undefined | undefined | Allows you to skip some chunks. |
sri | 'sha256'|'sha384'|'sha512'|undefined | undefined | The sri hash algorithm, disabled by default. |
minify | boolean | false | Controls whether to minify the output. |
favicon | string|undefined | undefined | Adds the given favicon path to the output HTML. |
meta | Record<string, string|Record<string, string>> | {} | Allows to inject meta-tags. |
hash | boolean | false | If true then append a unique rspack compilation hash to all included scripts and CSS files. This is useful for cache busting |
base | string|object|undefined | undefined | Inject a base tag |
If the default generated HTML doesn't meet your needs, you can use your own template.
The easiest way is to use the template option and pass a custom HTML file. The rspack.HtmlRspackPlugin
will automatically inject all the necessary JS, CSS and favicon files into the HTML.
Specify the HTML template file through template
:
Specify the HTML template content through templateContent
:
Use a function to generate the HTML template content:
templateContent
.js
or .cjs
in template
The HTML template rendering parameters can be extended through templateParameters
. The following variables are available by default:
htmlRspackPlugin
: Data of the plugin
htmlRspackPlugin.options
: Configuration object of the pluginhtmlRspackPlugin.tags
: Prepared tag information for injection in the template
htmlRspackPlugin.tags.headTags
: List of <base>
, <meta>
, <link>
, <script>
tags for injection in <head>
htmlRspackPlugin.tags.bodyTags
: List of <script>
tags for injection in <body>
htmlRspackPlugin.files
: Asset files generated in this compilation
htmlRspackPlugin.files.js
: List of paths of JS assets generated in this compilationhtmlRspackPlugin.files.css
: List of paths of CSS assets generated in this compilationhtmlRspackPlugin.files.favicon
: If favicon
is configured, here is the calculated final favicon asset pathhtmlRspackPlugin.files.publicPath
: The publicPath
of the asset filesrspackConfig
: Rspack configuration object used in this compilationcompilation
: Compilation object of this compilationIf htmlRspackPlugin.tags
is used to insert tags during template rendering, please configure inject
as false
, otherwise the tags will be injected twice.
There are some differences with HtmlWebpackPlugin:
!
to add loader to process the template filerspackConfig
object currently only supports mode
, output.publicPath
and output.crossOriginLoading
compilation
object is currently only supported when using the template functionhtmlRspackPlugin.tags.headTags
) or a single tag (such as htmlRspackPlugin.tags.headTags[0]
) in the template, the toHtml()
function is required to generate the HTML codeThe chunks that need to be injected can be specified through the following configuration:
Specific chunks can also be excluded through the following configuration:
If meta
is set, HtmlRspackPlugin will inject <meta>
tags.
Please check out this well-maintained list of almost all available meta tags.
Add key-value pairs through the following configuration to generate <meta>
tags:
If base
is set, HtmlRspackPlugin will inject the <base>
tag.
For more information about the
<base>
tag, please check the documentation
The <base>
tag can be generated through the following configuration:
If you have multiple entry points and want to generate an HTML file for each entry, you can register multiple rspack.HtmlRspackPlugin
:
filename
to specify the name for each HTML file.chunks
to specify the JS bundles to include in each HTML file.For example, the following configuration will generate foo.html and bar.html, where foo.html contains only the JS bundles generated by foo.js.
HtmlRspackPlugin provides some hooks that allow you to modify tags or generated HTML code. The hooks object can be obtained through HtmlRspackPlugin.getCompilationHooks
:
This hook will be called after collecting the assets from the compilation and generating the loading path, but before generating the tags.
The assets
can be modified here to add custom JS and CSS asset files.
AsyncSeriesWaterfallHook<[BeforeAssetTagGenerationData]>
Only assets.js
, assets.css
, and assets.favicon
can be modified. Modifications to other items will not take effect.
The following code adds an additional extra-script.js
and generates a <script defer src="extra-script.js"></script>
tag in the final html content.
This hook will be called after generating the asset tags based on the asset files, but before determining the insertion position of the tags.
The tags can be adjusted here.
Type: AsyncSeriesWaterfallHook<[AlterAssetTagsData]>
Parameters:
Only assetTags
can be modified. Modifications to other items will not take effect.
true
, a valueless attribute will be added, and <script defer specialattribute src="main.js"></script>
will be generated.string
, a valued attribute will be added, and <script defer specialattribute="some value" src="main.js"></script>
will be generated.false
, the attribute will be removed.The following code adds the specialAttribute
property to all script
type tags:
This hook will be called after generating the tag groups of head
and body
, but before the template is rendered by function or template engine.
The insertion position of the tags can be adjusted here.
AsyncSeriesWaterfallHook<[AlterAssetTagGroupsData]>
Only headTags
and bodyTags
can be modified. Modifications to other items will not take effect.
The following code moves the async
script
tags from body
to head
:
This hook will be called after the template rendering is completed, but before the tags are injected.
The HTML content and the tags to be injected can be modified here.
When using the function templateContent
or the template
ending with .js/.cjs
, and using this function to render the template, here html
is the result returned by the function.
In other scenarios, the HTML template will be compiled through a template engine inside, and here html
is the compiled result.
Type: AsyncSeriesWaterfallHook<[AfterTemplateExecutionData]>
Parameters:
:::warning Warning
Only html
, headTags
, and bodyTags
can be modified. Modifications to other items will not take effect.
:::
The following code adds Injected by plugin
at the end of the body. Then the tags will be injected after this text. Therefore, it will be <Injected by plugin<script defer src="main.js"></script></body>
in the final HTML content:
This hook will be called before generating the HTML asset file, and it is the final chance to modify the HTML content.
SyncHook<[BeforeEmitData]>
Only html
can be modified. Modifications to other items will not take effect.
The following code adds Injected by plugin
at the end of the body. It will be <script defer src="main.js"></script>Injected by plugin</body>
in the final HTML content:
This hook will be called after generating the HTML asset file and is only used for notification.
SyncHook<[AfterEmitData]>