rspack

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt. # HtmlRspackPlugin Rspack only `rspack.HtmlRspackPlugin` generates HTML files for Rspack builds and injects the JavaScript and CSS files required by their entry points. It can also set the document title, add a favicon, and generate `` and `` tags. - [Examples](#examples): Explore common use cases. - [Options](#options): Review types, defaults, and examples. - [Template syntax](#template-syntax): See supported interpolation and control statements. - [Hooks](#hooks): Modify asset URLs, tags, and HTML. For help choosing between the built-in plugin and the JavaScript `html-rspack-plugin`, see the [HTML guide](/guide/languages/html.md#choose-a-plugin). ## Examples ### Default output By default, the plugin emits `index.html` with the assets required by every entry point. ```js title="rspack.config.mjs" import { rspack } from '@rspack/core'; export default { entry: './src/index.js', plugins: [new rspack.HtmlRspackPlugin()], }; ``` With the built-in template, the generated `dist/index.html` is equivalent to: ```html rspack ``` By default, the plugin injects scripts with `defer` into ``. If an entry also produces CSS, the corresponding `` tags are inserted into ``. With multiple entry points, the HTML includes assets from all of them. ### Generate multiple HTML files To generate a separate HTML file for each entry point, register multiple `rspack.HtmlRspackPlugin` instances: - Use `filename` to name each HTML file. - Use `chunks` to select the entry-point assets included in each HTML file. The following configuration emits `foo.html` and `bar.html`. Each file contains the assets required by its matching entry point, including runtime and shared assets. ```js title="rspack.config.mjs" export default { entry: { foo: './foo.js', bar: './bar.js', }, plugins: [ new rspack.HtmlRspackPlugin({ filename: 'foo.html', chunks: ['foo'], }), new rspack.HtmlRspackPlugin({ filename: 'bar.html', chunks: ['bar'], }), ], }; ``` ### Module scripts When [`output.module`](/config/output.md#outputmodule) is enabled and `scriptLoading` is not set, the plugin emits ` ``` ### Production minification In production mode (`mode: 'production'`), the plugin minifies the generated HTML when `minify` is not set. In other modes, HTML is minified only when `minify` is enabled explicitly. ```js title="rspack.config.mjs" export default { mode: 'production', plugins: [new rspack.HtmlRspackPlugin()], }; ``` ### Use a template file If `src/index.ejs` exists in the Rspack [`context`](/config/context.md), the plugin uses it as the template automatically. Otherwise, it uses the built-in template. To customize the HTML structure, you can also use `template` to specify an HTML file. The plugin injects the required JavaScript, CSS, and favicon tags into it. ```html title="index.html" <%= htmlRspackPlugin.options.title %> ``` ```js title="rspack.config.mjs" export default { plugins: [ new rspack.HtmlRspackPlugin({ title: 'My HTML Template', template: 'index.html', }), ], }; ``` ### Use template string You can also provide the HTML template directly through `templateContent`: ```js title="rspack.config.mjs" export default { plugins: [ new rspack.HtmlRspackPlugin({ title: 'My HTML Template', templateContent: ` <%= htmlRspackPlugin.options.title %> `, }), ], }; ``` ### Use template function For dynamically generated template content, use a function in either of these forms: - Pass the function directly to `templateContent`: ```js title="rspack.config.mjs" export default { plugins: [ new rspack.HtmlRspackPlugin({ title: 'My HTML Template', templateContent: ({ htmlRspackPlugin }) => ` ${htmlRspackPlugin.options.title} `, }), ], }; ``` - Specify a `.js` or `.cjs` file in `template`: ```js title="template.js" module.exports = ({ htmlRspackPlugin }) => ` ${htmlRspackPlugin.options.title} `; ``` ```js title="rspack.config.mjs" export default { plugins: [ new rspack.HtmlRspackPlugin({ title: 'My HTML Template', template: 'template.js', }), ], }; ``` ### Template parameters Use `templateParameters` to customize the values passed when rendering an HTML template. Templates receive the following serializable parameters by default: - `htmlRspackPlugin`: Data exposed by the plugin - `htmlRspackPlugin.options`: Normalized plugin options - `htmlRspackPlugin.tags`: Generated tags prepared for insertion - `htmlRspackPlugin.tags.headTags`: List of ``, ``, ``, `<link>`, and `<script>` tags for injection in `<head>` - `htmlRspackPlugin.tags.bodyTags`: List of `<script>` tags for injection in `<body>` - `htmlRspackPlugin.files`: Asset URLs selected for the current HTML file - `htmlRspackPlugin.files.js`: Selected JavaScript asset URLs - `htmlRspackPlugin.files.css`: Selected CSS asset URLs - `htmlRspackPlugin.files.favicon`: Generated favicon URL when `favicon` is configured - `htmlRspackPlugin.files.publicPath`: Effective public path used for asset URLs - `rspackConfig`: Selected Rspack settings - `rspackConfig.mode`: Current build mode - `rspackConfig.output.publicPath`: Effective public path for the current HTML file, including a [`publicPath`](#publicpath) override - `rspackConfig.output.crossOriginLoading`: Configured cross-origin loading value When a JavaScript function renders the template, it can also access the Rspack `compilation` object. That object is not passed when `templateParameters` is `false` or a function. In a built-in template, use EJS-style interpolation to read these parameters: ```js title="rspack.config.mjs" export default { mode: 'development', plugins: [ new rspack.HtmlRspackPlugin({ title: 'My application', templateContent: ` <!doctype html> <html> <head></head> <body> <h1><%- htmlRspackPlugin.options.title %></h1> <p>Mode: <%- rspackConfig.mode %></p> </body> </html> `, }), ], }; ``` In a JavaScript template function, the parameters are passed as an ordinary JavaScript object: ```js title="rspack.config.mjs" export default { plugins: [ new rspack.HtmlRspackPlugin({ templateContent: ({ htmlRspackPlugin }) => ` <!doctype html> <html> <head></head> <body> <p>Scripts: ${htmlRspackPlugin.files.js.join(', ')}</p> </body> </html> `, }), ], }; ``` In templates rendered by the built-in engine, call `toHtml()` to convert a tag or tag list to HTML. In JavaScript template functions, tags and tag lists provide `toString()` and can be interpolated directly. :::warning If the template inserts `htmlRspackPlugin.tags` manually, set `inject` to `false`; otherwise, the plugin inserts those tags twice. ::: :::info Differences Compared with HtmlWebpackPlugin: - Template paths do not support loader syntax such as `loader!./template.html` - The `compilation` object is only available when [using a template function](#use-template-function), with the `templateParameters` restrictions described above ::: ## Options Pass the following options to `new rspack.HtmlRspackPlugin()`. All examples reuse the `rspack` import from the first example. ### title - **Type:** `string` - **Default:** `undefined` Sets the `<title>` of the generated HTML. When automatic injection is enabled, the plugin replaces an existing `<title>` in the template or adds one to `<head>`. When omitted, a custom template keeps its own title. The built-in template uses `rspack`. Setting [`inject`](#inject) to `false` prevents `title` from being applied automatically, but the value remains available as `htmlRspackPlugin.options.title`. ```js new rspack.HtmlRspackPlugin({ title: 'My application', }); ``` Generated HTML fragment: ```html <title>My application ``` ### filename - **Type:** ```ts type HtmlFilenameFunction = (entry: string) => string; type HtmlFilename = string | HtmlFilenameFunction; ``` - **Default:** `'index.html'` Sets the HTML asset path and filename relative to [`output.path`](/config/output.md#outputpath). When omitted, the plugin emits `index.html` in the output directory. - **String:** Emits the HTML at the specified path. The value can include a subdirectory and filename placeholders such as `[name]` and `[contenthash]`. A `[name]` placeholder emits one HTML file for each statically configured entry. ```js new rspack.HtmlRspackPlugin({ filename: 'pages/index.html', }); ``` - **Function:** Calls the function once for each statically configured entry, passing its name as the argument. The return value becomes the corresponding HTML filename. ```js export default { entry: { app: './src/app.js', admin: './src/admin.js', }, plugins: [ new rspack.HtmlRspackPlugin({ filename: (entry) => `pages/${entry}.html`, }), ], }; ``` The `[name]` and function forms do not support a function-valued Rspack [`entry`](/config/entry.md). They only control HTML filenames; every generated file still receives the same entry assets selected by [`chunks`](#chunks) and [`excludeChunks`](#excludechunks). Register separate plugin instances when each page needs a different asset set. ### template - **Type:** `string` - **Default:** `undefined` Sets the template file. Relative paths are resolved from the Rspack [`context`](/config/context.md). [`templateContent`](#templatecontent) takes precedence when both options are set. When omitted, the plugin looks for `src/index.ejs` in `context` and falls back to its built-in HTML document if the file does not exist. - **HTML file:** Reads the file as text, renders it with the built-in [template syntax](#template-syntax), and injects the generated tags. ```html title="index.html" <%= htmlRspackPlugin.options.title %> ``` ```js new rspack.HtmlRspackPlugin({ title: 'My application', template: './index.html', }); ``` - **JavaScript module:** A path ending in `.js` or `.cjs` is loaded as a CommonJS module. Its exported function receives the template parameters and returns the HTML string, either directly or through a promise. ```js title="template.cjs" module.exports = ({ htmlRspackPlugin }) => ` ${htmlRspackPlugin.options.title} `; ``` ```js new rspack.HtmlRspackPlugin({ title: 'My application', template: './template.cjs', }); ``` ### templateContent - **Type:** ```ts type TemplateRenderFunction = ( params: Record, ) => string | Promise; type TemplateContent = string | TemplateRenderFunction; ``` - **Default:** `undefined` Provides the template directly without reading a file. When set, it takes precedence over [`template`](#template) and the default template lookup. - **String:** Renders the string with the built-in [template syntax](#template-syntax), then injects the generated tags. ```js new rspack.HtmlRspackPlugin({ templateContent: ` My application `, }); ``` - **Function:** Calls the function with the final template parameters. The returned string becomes the HTML template result and is not processed as EJS. The function can be asynchronous. ```js new rspack.HtmlRspackPlugin({ title: 'My application', templateContent: ({ htmlRspackPlugin }) => ` ${htmlRspackPlugin.options.title} `, }); ``` When omitted, the plugin first uses [`template`](#template) if it is set. Otherwise, it looks for `src/index.ejs` and then falls back to the built-in document. ### templateParameters - **Type:** ```ts type TemplateParamFunction = ( params: Record, ) => Record | Promise>; type TemplateParameters = Record | boolean | TemplateParamFunction; ``` - **Default:** `undefined` Controls the parameters passed to an HTML template or template function. The built-in values are described in [Template parameters](#template-parameters). - **Object:** Merges the object's string properties into the built-in parameters. Properties with the same name replace the built-in value. ```js new rspack.HtmlRspackPlugin({ templateContent: '

<%= environment %>

', templateParameters: { environment: 'production', }, }); ``` - **Boolean:** `true` preserves the built-in parameters and is equivalent to omitting the option. `false` passes an empty object to the template. ```js new rspack.HtmlRspackPlugin({ templateContent: () => '

Static page

', templateParameters: false, }); ``` - **Function:** Calls the function with the serializable built-in parameters and uses its returned object as the complete final parameter object. Return the original properties when the template still needs them. The function can be asynchronous. ```js new rspack.HtmlRspackPlugin({ templateContent: ({ buildName }) => `

${buildName}

`, templateParameters: (params) => ({ ...params, buildName: 'documentation', }), }); ``` The `compilation` parameter is available only to a JavaScript template function when `templateParameters` is omitted, `true`, or an object. It is not passed to string templates, a `templateParameters` function, or a template function when `templateParameters` is `false`. ### inject - **Type:** `boolean | 'head' | 'body'` - **Default:** `true` Controls automatic insertion of the tags generated by the plugin. When injection is enabled, stylesheets, the title, ``, ``, and favicon tags are inserted into ``. The `'head'` and `'body'` values change only the placement of ` ``` - **`'defer'`:** Adds the boolean `defer` attribute. With the default `inject`, scripts are inserted into ``. ```js new rspack.HtmlRspackPlugin({ scriptLoading: 'defer', }); ``` Generated HTML fragment: ```html ``` - **`'module'`:** Adds `type="module"`. Module scripts are deferred by browsers, and the default `inject` inserts them into ``. ```js new rspack.HtmlRspackPlugin({ scriptLoading: 'module', }); ``` Generated HTML fragment: ```html ``` - **`'systemjs-module'`:** Adds `type="systemjs-module"`. The default `inject` inserts these scripts into ``. ```js new rspack.HtmlRspackPlugin({ scriptLoading: 'systemjs-module', }); ``` Generated HTML fragment: ```html ``` ### chunks - **Type:** `string[]` - **Default:** `undefined` Selects entry points whose JavaScript and CSS files are included in the HTML. Each value is compared with an entry point name using exact string equality; it does not match an arbitrary chunk ID, asset filename, or module path. Unknown names are ignored. When omitted, every entry point is selected before [`excludeChunks`](#excludechunks) is applied. Selecting an entry point also includes the runtime and shared files required by that entry. With the default [`chunksSortMode: 'auto'`](#chunkssortmode), `chunks` first limits the entry points and `excludeChunks` then removes matches. With `'manual'`, a provided `chunks` array instead becomes the final ordered entry list. If `chunks` is omitted, `excludeChunks` still filters the compilation's entry point order. ```js export default { entry: { app: './src/app.js', admin: './src/admin.js', }, plugins: [ new rspack.HtmlRspackPlugin({ chunks: ['app'], }), ], }; ``` ### excludeChunks - **Type:** `string[]` - **Default:** `undefined` Excludes entry points from the generated HTML. Each value is compared with an entry point name using exact string equality; it does not match asset filenames, module paths, or non-entry chunks. Unknown names have no effect. In the default [`chunksSortMode: 'auto'`](#chunkssortmode), exclusions are applied after [`chunks`](#chunks), so an entry present in both arrays is excluded. With `'manual'`, a provided `chunks` array is the final ordered list and `excludeChunks` is not applied; when `chunks` is omitted, exclusions still apply to the compilation's entry point order. If `excludeChunks` is omitted, no selected entry point is excluded. ```js export default { entry: { app: './src/app.js', admin: './src/admin.js', }, plugins: [ new rspack.HtmlRspackPlugin({ excludeChunks: ['admin'], }), ], }; ``` ### chunksSortMode - **Type:** `'auto' | 'manual'` - **Default:** `'auto'` Controls the order in which selected entry points contribute their files to the generated tags. - **`'auto'`:** Uses the compilation's entry point order after applying `chunks` and `excludeChunks`. ```js new rspack.HtmlRspackPlugin({ chunksSortMode: 'auto', }); ``` - **`'manual'`:** Uses the order of [`chunks`](#chunks), ignoring unknown entry names. When `chunks` is omitted, it uses the compilation's entry point order after applying [`excludeChunks`](#excludechunks). When `chunks` is present, `excludeChunks` is not applied. ```js new rspack.HtmlRspackPlugin({ chunks: ['admin', 'app'], chunksSortMode: 'manual', }); ``` ### minify - **Type:** `boolean` - **Default:** `true` in production mode, otherwise `false` Controls whether the generated HTML is minified after template rendering and tag injection. An explicit value overrides the mode-dependent default. ```js new rspack.HtmlRspackPlugin({ minify: false, }); ``` ### favicon - **Type:** `string` - **Default:** `undefined` Sets the path of a favicon file. Relative paths are resolved from the Rspack [`context`](/config/context.md). The plugin emits the file at the output root using its basename and generates a `` tag whose URL follows [`publicPath`](#publicpath). When omitted, no favicon asset or tag is generated. With [`inject: false`](#inject), the asset is still emitted and exposed as `htmlRspackPlugin.files.favicon`, but the `` tag is not inserted automatically. ```js new rspack.HtmlRspackPlugin({ favicon: './src/favicon.ico', }); ``` Generated HTML fragment: ```html ``` ### meta - **Type:** ```ts type HtmlMeta = Record>; ``` - **Default:** `{}` Creates additional `` tags in ``. Each top-level key becomes the default `name` attribute. The built-in template's `` is independent of this option. When the object is empty or the option is omitted, no additional meta tags are generated. [`inject: false`](#inject) prevents them from being inserted automatically. - **String value:** Uses the top-level key as `name` and the string as `content`. ```js new rspack.HtmlRspackPlugin({ meta: { viewport: 'width=device-width,initial-scale=1', }, }); ``` Generated HTML fragment: ```html ``` - **Object value:** Adds every property as an attribute. A `name` property overrides the name derived from the top-level key. ```js new rspack.HtmlRspackPlugin({ meta: { viewport: { name: 'viewport', content: 'width=device-width,initial-scale=1', 'data-origin': 'rspack', }, }, }); ``` Generated HTML fragment: ```html ``` ### hash - **Type:** `boolean` - **Default:** `undefined` If `true`, appends the Rspack compilation hash as a query string to generated JavaScript, CSS, and favicon URLs. This changes references in the HTML, not the emitted asset filenames. When omitted or `false`, the plugin leaves those URLs unchanged. ```js new rspack.HtmlRspackPlugin({ hash: true, }); ``` ## Template syntax The built-in template engine supports EJS-style interpolation and basic control flow, but it does not execute arbitrary JavaScript. The following examples show the commonly used forms. #### Escaped output `<%-` Escapes the content within the interpolation: ```html title="ejs"

Hello, <%- name %>.

Hello, <%- 'the Most Honorable ' + name %>.

``` ```json title="locals" { "name": "Rspack" } ``` ```html title="html"

Hello, Rspack<y>.

Hello, the Most Honorable Rspack<y>.

``` #### Unescaped output `<%=` Does not escape the content within the interpolation: ```html title="ejs"

Hello, <%- myHtml %>.

Hello, <%= myHtml %>.

Hello, <%- myMaliciousHtml %>.

Hello, <%= myMaliciousHtml %>.

``` ```json title="locals" { "myHtml": "Rspack", "myMaliciousHtml": "

" } ``` ```html title="html"

Hello, <strong>Rspack</strong>.

Hello, Rspack.

Hello, </p><script>document.write()</script><p>.

Hello,

``` #### Control statements The following example combines `for in` iteration with an `if` condition: ```txt title="ejs" <% for tag in htmlRspackPlugin.tags.headTags { %> <% if tag.tagName=="script" { %> <%= toHtml(tag) %> <% } %> <% } %> ``` ## Hooks HtmlRspackPlugin exposes hooks for modifying generated tags and HTML. Call `rspack.HtmlRspackPlugin.getCompilationHooks` to access them: Hook data exposes the original constructor options as `data.plugin.options`. Additional custom fields are preserved there for hook consumers but do not affect HTML generation by themselves. ```js title="rspack.config.mjs" const HtmlModifyPlugin = { apply(compiler) { compiler.hooks.compilation.tap('HtmlModifyPlugin', (compilation) => { const hooks = rspack.HtmlRspackPlugin.getCompilationHooks(compilation); // hooks.beforeAssetTagGeneration.tapPromise() // hooks.alterAssetTags.tapPromise() // hooks.alterAssetTagGroups.tapPromise() // hooks.afterTemplateExecution.tapPromise() // hooks.beforeEmit.tapPromise() // hooks.afterEmit.tapPromise() }); }, }; export default { plugins: [new rspack.HtmlRspackPlugin(), HtmlModifyPlugin], }; ``` ### beforeAssetTagGeneration This hook runs after the plugin collects asset URLs from the compilation and before it creates tags. Modify `assets.js`, `assets.css`, or `assets.favicon` to add or replace URLs used to create tags. Values added by the hook are used as-is: the hook does not prepend `publicPath` or emit the referenced files. - **Type:** `AsyncSeriesWaterfallHook<[BeforeAssetTagGenerationData]>` - **Parameters:** ```ts type BeforeAssetTagGenerationData = { assets: { publicPath: string; js: Array; css: Array; favicon?: string; jsIntegrity?: Array; cssIntegrity?: Array; }; outputName: string; plugin: { options: HtmlRspackPluginOptions; }; }; ``` :::warning Only changes to `assets.js`, `assets.css`, and `assets.favicon` affect the tags generated automatically by the plugin. Other fields do not affect automatic tag generation, but templates can still read them through `htmlRspackPlugin.files`. ::: The following code adds the URL `extra-script.js`, which produces a `` tag in the final HTML. ```js title="rspack.config.mjs" const AddScriptPlugin = { apply(compiler) { compiler.hooks.compilation.tap('AddScriptPlugin', (compilation) => { const hooks = rspack.HtmlRspackPlugin.getCompilationHooks(compilation); hooks.beforeAssetTagGeneration.tapPromise( 'AddScriptPlugin', async (data) => { data.assets.js.push('extra-script.js'); }, ); }); }, }; export default { plugins: [new rspack.HtmlRspackPlugin(), AddScriptPlugin], }; ``` ### alterAssetTags This hook runs after asset tags are created and before they are assigned to `` or ``. Modify `assetTags` to add, remove, or update tags. - **Type:** `AsyncSeriesWaterfallHook<[AlterAssetTagsData]>` - **Parameters:** ```ts type HtmlTag = { tagName: string; attributes: Record; voidTag: boolean; innerHTML?: string; asset?: string; }; type AlterAssetTagsData = { assetTags: { scripts: Array; styles: Array; meta: Array; }; publicPath: string; outputName: string; plugin: { options: HtmlRspackPluginOptions; }; }; ``` :::warning Only changes to `assetTags` affect the generated HTML. Changes to other fields are ignored by this plugin. ::: Attribute names are normalized to lowercase. Attribute values are handled as follows: - **`true`:** Adds a valueless attribute, for example ``. - **String:** Adds an attribute with that value, for example ``. - **`false`, `undefined`, or `null`:** Removes the attribute. The following code adds the `specialAttribute` attribute to every ``: ```js title="rspack.config.mjs" const InjectContentPlugin = { apply(compiler) { compiler.hooks.compilation.tap('InjectContentPlugin', (compilation) => { const hooks = rspack.HtmlRspackPlugin.getCompilationHooks(compilation); hooks.afterTemplateExecution.tapPromise( 'InjectContentPlugin', async (data) => { data.html = data.html.replace('', 'Injected by plugin'); }, ); }); }, }; export default { plugins: [ new rspack.HtmlRspackPlugin({ inject: 'body', }), InjectContentPlugin, ], }; ``` ### beforeEmit This hook runs immediately before the HTML asset is emitted and is the final chance to modify its content. - **Type:** `AsyncSeriesWaterfallHook<[BeforeEmitData]>` - **Parameters:** ```ts type BeforeEmitData = { html: string; outputName: string; plugin: { options: HtmlRspackPluginOptions; }; }; ``` :::warning Only changes to `html` affect the emitted asset. Changes to other fields are ignored by this plugin. ::: The following code adds `Injected by plugin` at the end of ``. The final sequence is `Injected by plugin`: ```js title="rspack.config.mjs" const InjectContentPlugin = { apply(compiler) { compiler.hooks.compilation.tap('InjectContentPlugin', (compilation) => { const hooks = rspack.HtmlRspackPlugin.getCompilationHooks(compilation); hooks.beforeEmit.tapPromise('InjectContentPlugin', async (data) => { data.html = data.html.replace('', 'Injected by plugin'); }); }); }, }; export default { plugins: [ new rspack.HtmlRspackPlugin({ inject: 'body', }), InjectContentPlugin, ], }; ``` ### afterEmit This hook runs after the HTML asset is emitted and is intended for notification only. - **Type:** `AsyncSeriesWaterfallHook<[AfterEmitData]>` - **Parameters:** ```ts type AfterEmitData = { outputName: string; plugin: { options: HtmlRspackPluginOptions; }; }; ```