refactor: add JSDoc & types to improve HtmlRspackPlugin, IgnorePlugin…

… options types (#8004) * refactor: add JSDoc & types for HtmlRspackPlugin, IgnorePlugin. * chore: add JSDoc about HtmlRspackPlugin options.base
web-infra-dev · Sep 27, 2024 · 27a7495 · 27a7495 · rspack-bot · Sep 27, 2024
1 parent ff45bc1
commit 27a7495
Show file tree

Hide file tree

Showing 5 changed files with 126 additions and 120 deletions.
diff --git a/packages/rspack/etc/api.md b/packages/rspack/etc/api.md
@@ -4656,49 +4656,9 @@ const hotUpdateMainFilename: z.ZodString;
 
 // @public (undocumented)
 export const HtmlRspackPlugin: {
-    new (c?: {
-        filename?: string | undefined;
-        publicPath?: string | undefined;
-        chunks?: string[] | undefined;
-        hash?: boolean | undefined;
-        base?: string | {
-            target?: "_self" | "_blank" | "_parent" | "_top" | undefined;
-            href?: string | undefined;
-        } | undefined;
-        template?: string | undefined;
-        templateContent?: string | ((args_0: Record<string, any>, ...args_1: unknown[]) => string | Promise<string>) | undefined;
-        templateParameters?: boolean | Record<string, string> | ((args_0: Record<string, any>, ...args_1: unknown[]) => Record<string, any> | Promise<Record<string, any>>) | undefined;
-        inject?: boolean | "head" | "body" | undefined;
-        scriptLoading?: "module" | "blocking" | "defer" | "systemjs-module" | undefined;
-        excludeChunks?: string[] | undefined;
-        sri?: "sha256" | "sha384" | "sha512" | undefined;
-        minify?: boolean | undefined;
-        title?: string | undefined;
-        favicon?: string | undefined;
-        meta?: Record<string, string | Record<string, string>> | undefined;
-    } | undefined): {
+    new (c?: HtmlRspackPluginOptions | undefined): {
         name: BuiltinPluginName;
-        _args: [c?: {
-            filename?: string | undefined;
-            publicPath?: string | undefined;
-            chunks?: string[] | undefined;
-            hash?: boolean | undefined;
-            base?: string | {
-                target?: "_self" | "_blank" | "_parent" | "_top" | undefined;
-                href?: string | undefined;
-            } | undefined;
-            template?: string | undefined;
-            templateContent?: string | ((args_0: Record<string, any>, ...args_1: unknown[]) => string | Promise<string>) | undefined;
-            templateParameters?: boolean | Record<string, string> | ((args_0: Record<string, any>, ...args_1: unknown[]) => Record<string, any> | Promise<Record<string, any>>) | undefined;
-            inject?: boolean | "head" | "body" | undefined;
-            scriptLoading?: "module" | "blocking" | "defer" | "systemjs-module" | undefined;
-            excludeChunks?: string[] | undefined;
-            sri?: "sha256" | "sha384" | "sha512" | undefined;
-            minify?: boolean | undefined;
-            title?: string | undefined;
-            favicon?: string | undefined;
-            meta?: Record<string, string | Record<string, string>> | undefined;
-        } | undefined];
+        _args: [c?: HtmlRspackPluginOptions | undefined];
         affectedHooks: "done" | "make" | "compile" | "emit" | "afterEmit" | "invalid" | "thisCompilation" | "afterDone" | "compilation" | "normalModuleFactory" | "contextModuleFactory" | "initialize" | "shouldEmit" | "infrastructureLog" | "beforeRun" | "run" | "assetEmitted" | "failed" | "shutdown" | "watchRun" | "watchClose" | "environment" | "afterEnvironment" | "afterPlugins" | "afterResolvers" | "beforeCompile" | "afterCompile" | "finishMake" | "entryOption" | undefined;
         raw(compiler: Compiler): BuiltinPlugin;
         apply(compiler: Compiler): void;
@@ -4730,76 +4690,27 @@ type HtmlRspackPluginHooks = {
 };
 
 // @public (undocumented)
-export type HtmlRspackPluginOptions = z.infer<typeof htmlRspackPluginOptions>;
-
-// @public (undocumented)
-const htmlRspackPluginOptions: z.ZodObject<{
-    filename: z.ZodOptional<z.ZodString>;
-    template: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
-    templateContent: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodFunction<z.ZodTuple<[z.ZodRecord<z.ZodString, z.ZodAny>], z.ZodUnknown>, z.ZodUnion<[z.ZodString, z.ZodPromise<z.ZodString>]>>]>>;
-    templateParameters: z.ZodOptional<z.ZodUnion<[z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodString>, z.ZodBoolean]>, z.ZodFunction<z.ZodTuple<[z.ZodRecord<z.ZodString, z.ZodAny>], z.ZodUnknown>, z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodAny>, z.ZodPromise<z.ZodRecord<z.ZodString, z.ZodAny>>]>>]>>;
-    inject: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["head", "body"]>, z.ZodBoolean]>>;
-    publicPath: z.ZodOptional<z.ZodString>;
-    base: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodObject<{
-        href: z.ZodOptional<z.ZodString>;
-        target: z.ZodOptional<z.ZodEnum<["_self", "_blank", "_parent", "_top"]>>;
-    }, "strict", z.ZodTypeAny, {
-        target?: "_self" | "_blank" | "_parent" | "_top" | undefined;
-        href?: string | undefined;
-    }, {
-        target?: "_self" | "_blank" | "_parent" | "_top" | undefined;
-        href?: string | undefined;
-    }>]>>;
-    scriptLoading: z.ZodOptional<z.ZodEnum<["blocking", "defer", "module", "systemjs-module"]>>;
-    chunks: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    excludeChunks: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    sri: z.ZodOptional<z.ZodEnum<["sha256", "sha384", "sha512"]>>;
-    minify: z.ZodOptional<z.ZodBoolean>;
-    title: z.ZodOptional<z.ZodString>;
-    favicon: z.ZodOptional<z.ZodString>;
-    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>>;
-    hash: z.ZodOptional<z.ZodBoolean>;
-}, "strict", z.ZodTypeAny, {
-    filename?: string | undefined;
-    publicPath?: string | undefined;
-    chunks?: string[] | undefined;
-    hash?: boolean | undefined;
-    base?: string | {
-        target?: "_self" | "_blank" | "_parent" | "_top" | undefined;
-        href?: string | undefined;
-    } | undefined;
-    template?: string | undefined;
-    templateContent?: string | ((args_0: Record<string, any>, ...args_1: unknown[]) => string | Promise<string>) | undefined;
-    templateParameters?: boolean | Record<string, string> | ((args_0: Record<string, any>, ...args_1: unknown[]) => Record<string, any> | Promise<Record<string, any>>) | undefined;
-    inject?: boolean | "head" | "body" | undefined;
-    scriptLoading?: "module" | "blocking" | "defer" | "systemjs-module" | undefined;
-    excludeChunks?: string[] | undefined;
-    sri?: "sha256" | "sha384" | "sha512" | undefined;
-    minify?: boolean | undefined;
-    title?: string | undefined;
-    favicon?: string | undefined;
-    meta?: Record<string, string | Record<string, string>> | undefined;
-}, {
-    filename?: string | undefined;
-    publicPath?: string | undefined;
-    chunks?: string[] | undefined;
-    hash?: boolean | undefined;
+export type HtmlRspackPluginOptions = {
+    title?: string;
+    filename?: string;
+    template?: string;
+    templateContent?: string | TemplateRenderFunction;
+    templateParameters?: Record<string, string> | boolean | TemplateParamFunction;
+    inject?: boolean | "head" | "body";
+    publicPath?: string;
     base?: string | {
-        target?: "_self" | "_blank" | "_parent" | "_top" | undefined;
-        href?: string | undefined;
-    } | undefined;
-    template?: string | undefined;
-    templateContent?: string | ((args_0: Record<string, any>, ...args_1: unknown[]) => string | Promise<string>) | undefined;
-    templateParameters?: boolean | Record<string, string> | ((args_0: Record<string, any>, ...args_1: unknown[]) => Record<string, any> | Promise<Record<string, any>>) | undefined;
-    inject?: boolean | "head" | "body" | undefined;
-    scriptLoading?: "module" | "blocking" | "defer" | "systemjs-module" | undefined;
-    excludeChunks?: string[] | undefined;
-    sri?: "sha256" | "sha384" | "sha512" | undefined;
-    minify?: boolean | undefined;
-    title?: string | undefined;
-    favicon?: string | undefined;
-    meta?: Record<string, string | Record<string, string>> | undefined;
-}>;
+        href?: string;
+        target?: "_self" | "_blank" | "_parent" | "_top";
+    };
+    scriptLoading?: "blocking" | "defer" | "module" | "systemjs-module";
+    chunks?: string[];
+    excludeChunks?: string[];
+    sri?: "sha256" | "sha384" | "sha512";
+    minify?: boolean;
+    favicon?: string;
+    meta?: Record<string, string | Record<string, string>>;
+    hash?: boolean;
+};
 
 // @public (undocumented)
 type IBigIntStats = IStatsBase<bigint> & {
@@ -15632,6 +15543,12 @@ export class Template {
     static toPath(str: string): string;
 }
 
+// @public (undocumented)
+type TemplateParamFunction = (params: Record<string, any>) => Record<string, any> | Promise<Record<string, any>>;
+
+// @public (undocumented)
+type TemplateRenderFunction = (params: Record<string, any>) => string | Promise<string>;
+
 // @public (undocumented)
 interface TerserCompressOptions {
     // (undocumented)

diff --git a/packages/rspack/src/builtin-plugin/HtmlRspackPlugin.ts b/packages/rspack/src/builtin-plugin/HtmlRspackPlugin.ts
@@ -27,17 +27,103 @@ type HtmlPluginTag = {
 	toString?: () => string;
 };
 
+export type TemplateRenderFunction = (
+	params: Record<string, any>
+) => string | Promise<string>;
+
 const templateRenderFunction = z
 	.function()
 	.args(z.record(z.string(), z.any()))
-	.returns(z.string().or(z.promise(z.string())));
+	.returns(
+		z.string().or(z.promise(z.string()))
+	) satisfies z.ZodType<TemplateRenderFunction>;
+
+export type TemplateParamFunction = (
+	params: Record<string, any>
+) => Record<string, any> | Promise<Record<string, any>>;
 
 const templateParamFunction = z
 	.function()
 	.args(z.record(z.string(), z.any()))
 	.returns(
 		z.record(z.string(), z.any()).or(z.promise(z.record(z.string(), z.any())))
-	);
+	) satisfies z.ZodType<TemplateParamFunction>;
+
+export type HtmlRspackPluginOptions = {
+	/** The title to use for the generated HTML document. */
+	title?: string;
+
+	/**
+	 * The file to write the HTML to. You can specify a subdirectory here too (eg: pages/index.html).
+	 * @default 'index.html'
+	 */
+	filename?: string;
+
+	/** The template file path. */
+	template?: string;
+
+	/**
+	 * 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.
+	 */
+	templateContent?: string | TemplateRenderFunction;
+
+	/**
+	 * 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.
+	 */
+	templateParameters?: Record<string, string> | boolean | TemplateParamFunction;
+
+	/**
+	 * 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.
+	 */
+	inject?: boolean | "head" | "body";
+
+	/** The publicPath used for script and link tags. */
+	publicPath?: string;
+
+	/** Inject a [base](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base) tag */
+	base?:
+		| string
+		| { href?: string; target?: "_self" | "_blank" | "_parent" | "_top" };
+
+	/**
+	 * 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.
+	 * @default 'defer'
+	 * */
+	scriptLoading?: "blocking" | "defer" | "module" | "systemjs-module";
+
+	/** Allows you to add only some chunks. */
+	chunks?: string[];
+
+	/** Allows you to skip some chunks. */
+	excludeChunks?: string[];
+
+	/** The sri hash algorithm, disabled by default. */
+	sri?: "sha256" | "sha384" | "sha512";
+
+	/**
+	 * Controls whether to minify the output.
+	 * @default false
+	 */
+	minify?: boolean;
+
+	/** Adds the given favicon path to the output HTML. */
+	favicon?: string;
+
+	/**
+	 * If true then append a unique rspack compilation hash to all included scripts and CSS files.
+	 * This is useful for cache busting
+	 * @default false
+	 * */
+	meta?: Record<string, string | Record<string, string>>;
+
+	/** Inject a base tag */
+	hash?: boolean;
+};
 
 const htmlRspackPluginOptions = z.strictObject({
 	filename: z.string().optional(),
@@ -79,8 +165,7 @@ const htmlRspackPluginOptions = z.strictObject({
 	favicon: z.string().optional(),
 	meta: z.record(z.string().or(z.record(z.string()))).optional(),
 	hash: z.boolean().optional()
-});
-export type HtmlRspackPluginOptions = z.infer<typeof htmlRspackPluginOptions>;
+}) satisfies z.ZodType<HtmlRspackPluginOptions>;
 
 const HtmlRspackPluginImpl = create(
 	BuiltinPluginName.HtmlRspackPlugin,

diff --git a/packages/rspack/src/builtin-plugin/IgnorePlugin.ts b/packages/rspack/src/builtin-plugin/IgnorePlugin.ts
@@ -9,10 +9,14 @@ import { create } from "./base";
 
 export type IgnorePluginOptions =
 	| {
+			/** A RegExp to test the resource against. */
 			resourceRegExp: NonNullable<RawIgnorePluginOptions["resourceRegExp"]>;
+
+			/** A RegExp to test the context (directory) against. */
 			contextRegExp?: RawIgnorePluginOptions["contextRegExp"];
 	  }
 	| {
+			/** A Filter function that receives `resource` and `context` as arguments, must return boolean. */
 			checkResource: NonNullable<RawIgnorePluginOptions["checkResource"]>;
 	  };
 
@@ -24,7 +28,7 @@ const IgnorePluginOptions = z.union([
 	z.object({
 		checkResource: z.function(z.tuple([z.string(), z.string()]), z.boolean())
 	})
-]);
+]) satisfies z.ZodType<IgnorePluginOptions>;
 
 export const IgnorePlugin = create(
 	BuiltinPluginName.IgnorePlugin,

diff --git a/website/docs/en/plugins/rspack/html-rspack-plugin.mdx b/website/docs/en/plugins/rspack/html-rspack-plugin.mdx
@@ -142,7 +142,7 @@ type HtmlRspackPluginOptions = {
   template?: string;
   templateContent?: string | ((params: Record<string, any>) => string | Promise<string>);
   templateParameters?: Record<string, string> | (oldParams: params: Record<string, any>) => Record<string, any> | Promise<Record<string, any>>;
-  inject?: 'head' | 'body' | false;
+  inject?: 'head' | 'body' | boolean;
   publicPath?: string;
   base?: string | {
     href?: string;
@@ -216,7 +216,7 @@ type HtmlRspackPluginOptions = {
     },
     {
       name: '`inject`',
-      type: "`'head' | 'body' | false | undefined`",
+      type: "`'head' | 'body' | boolean | undefined`",
       default: 'undefined',
       description:
         '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`.',

diff --git a/website/docs/zh/plugins/rspack/html-rspack-plugin.mdx b/website/docs/zh/plugins/rspack/html-rspack-plugin.mdx
@@ -142,7 +142,7 @@ type HtmlRspackPluginOptions = {
   template?: string;
   templateContent?: string | ((params: Record<string, any>) => string | Promise<string>);
   templateParameters?: Record<string, string> | (oldParams: params: Record<string, any>) => Record<string, any> | Promise<Record<string, any>>;
-  inject?: 'head' | 'body' | false;
+  inject?: 'head' | 'body' | boolean;
   publicPath?: string;
   base?: string | {
     href?: string;
@@ -215,7 +215,7 @@ type HtmlRspackPluginOptions = {
     },
     {
       name: '`inject`',
-      type: "`'head'|'body'|false|undefined`",
+      type: "`'head'|'body'|boolean|undefined`",
       default: 'undefined',
       description:
         '产物注入位置，使用 `false` 则不注入，不指定时则会根据 scriptLoading 的配置自动判断',
Name	Base (2024-09-27 8b80b6f)	Current	Change
10000_development-mode + exec	2.24 s ± 35 ms	2.27 s ± 46 ms	+1.08 %
10000_development-mode_hmr + exec	708 ms ± 7.7 ms	706 ms ± 11 ms	-0.30 %
10000_production-mode + exec	2.91 s ± 59 ms	2.9 s ± 24 ms	-0.39 %
arco-pro_development-mode + exec	1.86 s ± 67 ms	1.85 s ± 85 ms	-0.53 %
arco-pro_development-mode_hmr + exec	437 ms ± 2.3 ms	437 ms ± 2.8 ms	-0.00 %
arco-pro_production-mode + exec	3.28 s ± 66 ms	3.35 s ± 75 ms	+1.98 %
arco-pro_production-mode_generate-package-json-webpack-plugin + exec	3.37 s ± 101 ms	3.37 s ± 80 ms	-0.01 %
threejs_development-mode_10x + exec	1.7 s ± 20 ms	1.71 s ± 24 ms	+0.51 %
threejs_development-mode_10x_hmr + exec	791 ms ± 14 ms	790 ms ± 15 ms	-0.13 %
threejs_production-mode_10x + exec	5.27 s ± 26 ms	5.28 s ± 28 ms	+0.13 %
suite	result
modernjs	✅ success
_selftest	✅ success
nx	❌ failure
rspress	✅ success
rslib	✅ success
rsbuild	✅ success
examples	✅ success
devserver	✅ success