Skip to content

Commit 3873ca5

Browse files
chenjiahanchenjiahan
authored
docs: add modifyHTML hook (#5151)
1 parent 3bd565b commit 3873ca5

File tree

5 files changed

+162
-26
lines changed

5 files changed

+162
-26
lines changed

‎packages/core/src/types/plugin.ts

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -510,10 +510,10 @@ export type RsbuildPluginAPI = Readonly<{
510510
*/
511511
modifyEnvironmentConfig: PluginHook<ModifyEnvironmentConfigFn>;
512512
/**
513-
* Modify the final HTML content. The hook receives a context object that
514-
* contains the HTML content, and you can return a new HTML string to
515-
* replace the original one.
516-
* This hook is triggered after the `modifyHTMLTags` hook.
513+
* Modify the final HTML content. The hook receives a HTML string
514+
* and a context object, and you can return a new HTML string to
515+
* replace the original one. This hook is triggered after the
516+
* `modifyHTMLTags` hook.
517517
*/
518518
modifyHTML: PluginHook<ModifyHTMLFn>;
519519
/**

‎website/docs/en/guide/migration/vite.mdx

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -257,16 +257,17 @@ for (const path of context.keys()) {
257257

258258
Rsbuild's plugin API covers most of the Vite and Rollup plugin hooks, for example:
259259

260-
| Vite plugin hooks | Rsbuild plugin API |
261-
| ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
262-
| `resolveId` | [resolve](/plugins/dev/core#apiresolve) |
263-
| `transform` | [transform](/plugins/dev/core#apitransform) |
264-
| `config` | [modifyRsbuildConfig](/plugins/dev/hooks#modifyrsbuildconfig) |
265-
| `configResolved` | [getNormalizedConfig](/plugins/dev/core#apigetnormalizedconfig) |
266-
| `configureServer` | [onBeforeStartDevServer](/plugins/dev/hooks#onbeforestartdevserver) |
267-
| `buildStart` | [onBeforeBuild](/plugins/dev/hooks#onbeforebuild), [onBeforeStartDevServer](/plugins/dev/hooks#onbeforestartdevserver) |
268-
| `buildEnd` | [onAfterBuild](/plugins/dev/hooks#onafterbuild), [onCloseDevServer](/plugins/dev/hooks#onclosedevserver) |
269-
| `closeBundle` | [onCloseBuild](/plugins/dev/hooks#onclosebuild), [onCloseDevServer](/plugins/dev/hooks#onclosedevserver) |
260+
| Vite plugin hooks | Rsbuild plugin API |
261+
| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
262+
| `resolveId` | [resolve](/plugins/dev/core#apiresolve) |
263+
| `transform` | [transform](/plugins/dev/core#apitransform) |
264+
| `config` | [modifyRsbuildConfig](/plugins/dev/hooks#modifyrsbuildconfig) |
265+
| `configResolved` | [getNormalizedConfig](/plugins/dev/core#apigetnormalizedconfig) |
266+
| `configureServer` | [onBeforeStartDevServer](/plugins/dev/hooks#onbeforestartdevserver) |
267+
| `buildStart` | [onBeforeBuild](/plugins/dev/hooks#onbeforebuild), [onBeforeStartDevServer](/plugins/dev/hooks#onbeforestartdevserver) |
268+
| `buildEnd` | [onAfterBuild](/plugins/dev/hooks#onafterbuild), [onCloseDevServer](/plugins/dev/hooks#onclosedevserver) |
269+
| `closeBundle` | [onCloseBuild](/plugins/dev/hooks#onclosebuild), [onCloseDevServer](/plugins/dev/hooks#onclosedevserver) |
270+
| `transformIndexHtml` | [modifyHTML](/plugins/dev/hooks#modifyhtml) |
270271

271272
See [Plugin system](/plugins/dev/index) for more details.
272273

‎website/docs/en/plugins/dev/hooks.mdx

Lines changed: 68 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ This chapter introduces the plugin hooks available for Rsbuild plugins.
1111
- [modifyRspackConfig](#modifyrspackconfig): Modify the configuration passed to Rspack.
1212
- [modifyBundlerChain](#modifybundlerchain): Modify the configuration of Rspack through the chain API.
1313
- [modifyHTMLTags](#modifyhtmltags): Modify the tags that are injected into the HTML.
14+
- [modifyHTML](#modifyhtml): Modify the final HTML content.
1415
- [onBeforeCreateCompiler](#onbeforecreatecompiler): Called before creating a compiler instance.
1516
- [onAfterCreateCompiler](#onaftercreatecompiler): Called after creating a compiler instance and before building.
1617
- [onBeforeEnvironmentCompile](#onbeforeenvironmentcompile): Called before the compilation of a single environment.
@@ -63,6 +64,7 @@ When the `rsbuild dev` command or `rsbuild.startDevServer()` method is executed,
6364
- [onBeforeEnvironmentCompile](#onbeforeenvironmentcompile)
6465
- [onAfterStartDevServer](#onafterstartdevserver)
6566
- [modifyHTMLTags](#modifyhtmltags)
67+
- [modifyHTML](#modifyhtml)
6668
- [onAfterEnvironmentCompile](#onafterenvironmentcompile)
6769
- [onDevCompileDone](#ondevcompiledone)
6870
- [onCloseDevServer](#onclosedevserver)
@@ -72,6 +74,7 @@ When rebuilding, the following hooks will be triggered again:
7274

7375
- [onBeforeEnvironmentCompile](#onbeforeenvironmentcompile)
7476
- [modifyHTMLTags](#modifyhtmltags)
77+
- [modifyHTML](#modifyhtml)
7578
- [onAfterEnvironmentCompile](#onafterenvironmentcompile)
7679
- [onDevCompileDone](#ondevcompiledone)
7780

@@ -88,6 +91,7 @@ When the `rsbuild build` command or `rsbuild.build()` method is executed, Rsbuil
8891
- [onBeforeBuild](#onbeforebuild)
8992
- [onBeforeEnvironmentCompile](#onbeforeenvironmentcompile)
9093
- [modifyHTMLTags](#modifyhtmltags)
94+
- [modifyHTML](#modifyhtml)
9195
- [onAfterEnvironmentCompile](#onafterenvironmentcompile)
9296
- [onAfterBuild](#onafterbuild)
9397
- [onCloseBuild](#onclosebuild)
@@ -98,6 +102,7 @@ When rebuilding, the following hooks will be triggered again:
98102
- [onBeforeBuild](#onbeforebuild)
99103
- [onBeforeEnvironmentCompile](#onbeforeenvironmentcompile)
100104
- [modifyHTMLTags](#modifyhtmltags)
105+
- [modifyHTML](#modifyhtml)
101106
- [onAfterEnvironmentCompile](#onafterenvironmentcompile)
102107
- [onAfterBuild](#onafterbuild)
103108

@@ -142,6 +147,7 @@ Correspondingly, there are some plugin hooks that are related to the current env
142147
- [modifyBundlerChain](#modifybundlerchain)
143148
- [modifyRspackConfig](#modifyrspackconfig)
144149
- [modifyHTMLTags](#modifyhtmltags)
150+
- [modifyHTML](#modifyhtml)
145151
- [onBeforeEnvironmentCompile](#onbeforeenvironmentcompile)
146152
- [onAfterEnvironmentCompile](#onafterenvironmentcompile)
147153

@@ -441,9 +447,70 @@ const myPlugin = () => ({
441447

442448
The second parameter `utils` of the callback function is an object, which contains some utility functions and properties, see [tools.bundlerChain - Utils](/config/tools/bundler-chain#utils) for more details.
443449

450+
### modifyHTML
451+
452+
Modify the final HTML content. The hook receives a HTML string and a context object, and you can return a new HTML string to replace the original one.
453+
454+
This hook is triggered after the `modifyHTMLTags` hook.
455+
456+
- **Type:**
457+
458+
```ts
459+
type Context = {
460+
/**
461+
* The Compiler object of Rspack.
462+
*/
463+
compiler: Rspack.Compiler;
464+
/**
465+
* The Compilation object of Rspack.
466+
*/
467+
compilation: Rspack.Compilation;
468+
/**
469+
* The name of the HTML file, relative to the dist directory.
470+
* @example 'index.html'
471+
*/
472+
filename: string;
473+
/**
474+
* The environment context for current build.
475+
*/
476+
environment: EnvironmentContext;
477+
};
478+
479+
function ModifyHTML(
480+
callback: (html: string, context: Context) => MaybePromise<string>,
481+
): void;
482+
```
483+
484+
- **Example:**
485+
486+
```ts
487+
const myPlugin = () => ({
488+
setup(api) {
489+
api.modifyHTML((html) => {
490+
return html.replace('foo', 'bar');
491+
});
492+
},
493+
});
494+
```
495+
496+
Modify HTML content based on `filename`:
497+
498+
```ts
499+
const myPlugin = () => ({
500+
setup(api) {
501+
api.modifyHTML((html, { filename }) => {
502+
if (filename === 'foo.html') {
503+
return html.replace('foo', 'bar');
504+
}
505+
return html;
506+
});
507+
},
508+
});
509+
```
510+
444511
### modifyHTMLTags
445512

446-
Modify the tags that are injected into the HTML.
513+
Modify the tags that are injected into the HTML. This hook is triggered before the [modifyHTML](#modifyhtml) hook.
447514

448515
- **Type:**
449516

‎website/docs/zh/guide/migration/vite.mdx

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -257,16 +257,17 @@ for (const path of context.keys()) {
257257

258258
Rsbuild 的插件 API 覆盖了大部分的 Vite 和 Rollup 插件 hooks，例如：
259259

260-
| Vite 插件 hooks | Rsbuild 插件 API |
261-
| ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
262-
| `resolveId` | [resolve](/plugins/dev/core#apiresolve) |
263-
| `transform` | [transform](/plugins/dev/core#apitransform) |
264-
| `config` | [modifyRsbuildConfig](/plugins/dev/hooks#modifyrsbuildconfig) |
265-
| `configResolved` | [getNormalizedConfig](/plugins/dev/core#apigetnormalizedconfig) |
266-
| `configureServer` | [onBeforeStartDevServer](/plugins/dev/hooks#onbeforestartdevserver) |
267-
| `buildStart` | [onBeforeBuild](/plugins/dev/hooks#onbeforebuild), [onBeforeStartDevServer](/plugins/dev/hooks#onbeforestartdevserver) |
268-
| `buildEnd` | [onAfterBuild](/plugins/dev/hooks#onafterbuild), [onCloseDevServer](/plugins/dev/hooks#onclosedevserver) |
269-
| `closeBundle` | [onCloseBuild](/plugins/dev/hooks#onclosebuild), [onCloseDevServer](/plugins/dev/hooks#onclosedevserver) |
260+
| Vite 插件 hooks | Rsbuild 插件 API |
261+
| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
262+
| `resolveId` | [resolve](/plugins/dev/core#apiresolve) |
263+
| `transform` | [transform](/plugins/dev/core#apitransform) |
264+
| `config` | [modifyRsbuildConfig](/plugins/dev/hooks#modifyrsbuildconfig) |
265+
| `configResolved` | [getNormalizedConfig](/plugins/dev/core#apigetnormalizedconfig) |
266+
| `configureServer` | [onBeforeStartDevServer](/plugins/dev/hooks#onbeforestartdevserver) |
267+
| `buildStart` | [onBeforeBuild](/plugins/dev/hooks#onbeforebuild), [onBeforeStartDevServer](/plugins/dev/hooks#onbeforestartdevserver) |
268+
| `buildEnd` | [onAfterBuild](/plugins/dev/hooks#onafterbuild), [onCloseDevServer](/plugins/dev/hooks#onclosedevserver) |
269+
| `closeBundle` | [onCloseBuild](/plugins/dev/hooks#onclosebuild), [onCloseDevServer](/plugins/dev/hooks#onclosedevserver) |
270+
| `transformIndexHtml` | [modifyHTML](/plugins/dev/hooks#modifyhtml) |
270271

271272
请参考 [插件系统](/plugins/dev/index) 文档来了解更多。
272273

‎website/docs/zh/plugins/dev/hooks.mdx

Lines changed: 68 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
- [modifyRspackConfig](#modifyrspackconfig)：修改传递给 Rspack 的配置。
1212
- [modifyBundlerChain](#modifybundlerchain)：通过 chain API 修改 Rspack 的配置。
1313
- [modifyHTMLTags](#modifyhtmltags)：修改注入到 HTML 中的标签。
14+
- [modifyHTML](#modifyhtml)：修改最终的 HTML 内容。
1415
- [onBeforeCreateCompiler](#onbeforecreatecompiler)：在创建 compiler 实例前调用。
1516
- [onAfterCreateCompiler](#onaftercreatecompiler)：在创建 compiler 实例后、执行构建前调用。
1617
- [onBeforeEnvironmentCompile](#onbeforeenvironmentcompile): 在每次执行单个 environment 的构建前调用。
@@ -63,6 +64,7 @@
6364
- [onBeforeEnvironmentCompile](#onbeforeenvironmentcompile)
6465
- [onAfterStartDevServer](#onafterstartdevserver)
6566
- [modifyHTMLTags](#modifyhtmltags)
67+
- [modifyHTML](#modifyhtml)
6668
- [onAfterEnvironmentCompile](#onafterenvironmentcompile)
6769
- [onDevCompileDone](#ondevcompiledone)
6870
- [onCloseDevServer](#onclosedevserver)
@@ -72,6 +74,7 @@
7274

7375
- [onBeforeEnvironmentCompile](#onbeforeenvironmentcompile)
7476
- [modifyHTMLTags](#modifyhtmltags)
77+
- [modifyHTML](#modifyhtml)
7578
- [onAfterEnvironmentCompile](#onafterenvironmentcompile)
7679
- [onDevCompileDone](#ondevcompiledone)
7780

@@ -88,6 +91,7 @@
8891
- [onBeforeBuild](#onbeforebuild)
8992
- [onBeforeEnvironmentCompile](#onbeforeenvironmentcompile)
9093
- [modifyHTMLTags](#modifyhtmltags)
94+
- [modifyHTML](#modifyhtml)
9195
- [onAfterEnvironmentCompile](#onafterenvironmentcompile)
9296
- [onAfterBuild](#onafterbuild)
9397
- [onCloseBuild](#onclosebuild)
@@ -98,6 +102,7 @@
98102
- [onBeforeBuild](#onbeforebuild)
99103
- [onBeforeEnvironmentCompile](#onbeforeenvironmentcompile)
100104
- [modifyHTMLTags](#modifyhtmltags)
105+
- [modifyHTML](#modifyhtml)
101106
- [onAfterEnvironmentCompile](#onafterenvironmentcompile)
102107
- [onAfterBuild](#onafterbuild)
103108

@@ -142,6 +147,7 @@
142147
- [modifyBundlerChain](#modifybundlerchain)
143148
- [modifyRspackConfig](#modifyrspackconfig)
144149
- [modifyHTMLTags](#modifyhtmltags)
150+
- [modifyHTML](#modifyhtml)
145151
- [onBeforeEnvironmentCompile](#onbeforeenvironmentcompile)
146152
- [onAfterEnvironmentCompile](#onafterenvironmentcompile)
147153

@@ -437,9 +443,70 @@ const myPlugin = () => ({
437443

438444
回调函数的第二个参数 `utils` 是一个对象，包含了一些工具函数和属性，详见 [tools.bundlerChain - 工具对象](/config/tools/bundler-chain#工具对象)。
439445

446+
### modifyHTML
447+
448+
修改最终的 HTML 内容。该钩子接收一个 HTML 字符串和上下文对象，你可以返回一个新的 HTML 字符串来替换原始内容。
449+
450+
这个钩子在 [modifyHTMLTags](#modifyhtmltags) 钩子之后触发。
451+
452+
- **类型：**
453+
454+
```ts
455+
type Context = {
456+
/**
457+
* Rspack 的 Compiler 对象
458+
*/
459+
compiler: Rspack.Compiler;
460+
/**
461+
* Rspack 的 Compilation 对象
462+
*/
463+
compilation: Rspack.Compilation;
464+
/**
465+
* HTML 文件的名称，相对于 dist 目录
466+
* @example 'index.html'
467+
*/
468+
filename: string;
469+
/**
470+
* 当前构建的 environment 上下文
471+
*/
472+
environment: EnvironmentContext;
473+
};
474+
475+
function ModifyHTML(
476+
callback: (html: string, context: Context) => MaybePromise<string>,
477+
): void;
478+
```
479+
480+
- **示例：**
481+
482+
```ts
483+
const myPlugin = () => ({
484+
setup(api) {
485+
api.modifyHTML((html) => {
486+
return html.replace('foo', 'bar');
487+
});
488+
},
489+
});
490+
```
491+
492+
基于 `filename` 来修改 HTML 内容：
493+
494+
```ts
495+
const myPlugin = () => ({
496+
setup(api) {
497+
api.modifyHTML((html, { filename }) => {
498+
if (filename === 'foo.html') {
499+
return html.replace('foo', 'bar');
500+
}
501+
return html;
502+
});
503+
},
504+
});
505+
```
506+
440507
### modifyHTMLTags
441508

442-
修改注入到 HTML 中的标签。
509+
修改注入到 HTML 中的标签。这个钩子在 [modifyHTML](#modifyhtml) 钩子之前触发。
443510

444511
- **类型：**
445512

0 commit comments

Comments
 (0)