From 27a7495c4a4a49fbbebf2420c4ba986b536a180a Mon Sep 17 00:00:00 2001 From: qixuan <58852732+GiveMe-A-Name@users.noreply.github.com> Date: Fri, 27 Sep 2024 17:13:08 +0800 Subject: [PATCH] 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 --- packages/rspack/etc/api.md | 139 ++++-------------- .../src/builtin-plugin/HtmlRspackPlugin.ts | 93 +++++++++++- .../rspack/src/builtin-plugin/IgnorePlugin.ts | 6 +- .../en/plugins/rspack/html-rspack-plugin.mdx | 4 +- .../zh/plugins/rspack/html-rspack-plugin.mdx | 4 +- 5 files changed, 126 insertions(+), 120 deletions(-) diff --git a/packages/rspack/etc/api.md b/packages/rspack/etc/api.md index 670244af6aa..f558391e00c 100644 --- 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, ...args_1: unknown[]) => string | Promise) | undefined; - templateParameters?: boolean | Record | ((args_0: Record, ...args_1: unknown[]) => Record | Promise>) | 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> | 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, ...args_1: unknown[]) => string | Promise) | undefined; - templateParameters?: boolean | Record | ((args_0: Record, ...args_1: unknown[]) => Record | Promise>) | 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> | 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; - -// @public (undocumented) -const htmlRspackPluginOptions: z.ZodObject<{ - filename: z.ZodOptional; - template: z.ZodOptional>; - templateContent: z.ZodOptional], z.ZodUnknown>, z.ZodUnion<[z.ZodString, z.ZodPromise]>>]>>; - templateParameters: z.ZodOptional, z.ZodBoolean]>, z.ZodFunction], z.ZodUnknown>, z.ZodUnion<[z.ZodRecord, z.ZodPromise>]>>]>>; - inject: z.ZodOptional, z.ZodBoolean]>>; - publicPath: z.ZodOptional; - base: z.ZodOptional; - target: z.ZodOptional>; - }, "strict", z.ZodTypeAny, { - target?: "_self" | "_blank" | "_parent" | "_top" | undefined; - href?: string | undefined; - }, { - target?: "_self" | "_blank" | "_parent" | "_top" | undefined; - href?: string | undefined; - }>]>>; - scriptLoading: z.ZodOptional>; - chunks: z.ZodOptional>; - excludeChunks: z.ZodOptional>; - sri: z.ZodOptional>; - minify: z.ZodOptional; - title: z.ZodOptional; - favicon: z.ZodOptional; - meta: z.ZodOptional]>>>; - hash: z.ZodOptional; -}, "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, ...args_1: unknown[]) => string | Promise) | undefined; - templateParameters?: boolean | Record | ((args_0: Record, ...args_1: unknown[]) => Record | Promise>) | 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> | 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 | 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, ...args_1: unknown[]) => string | Promise) | undefined; - templateParameters?: boolean | Record | ((args_0: Record, ...args_1: unknown[]) => Record | Promise>) | 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> | 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>; + hash?: boolean; +}; // @public (undocumented) type IBigIntStats = IStatsBase & { @@ -15632,6 +15543,12 @@ export class Template { static toPath(str: string): string; } +// @public (undocumented) +type TemplateParamFunction = (params: Record) => Record | Promise>; + +// @public (undocumented) +type TemplateRenderFunction = (params: Record) => string | Promise; + // @public (undocumented) interface TerserCompressOptions { // (undocumented) diff --git a/packages/rspack/src/builtin-plugin/HtmlRspackPlugin.ts b/packages/rspack/src/builtin-plugin/HtmlRspackPlugin.ts index 65eeb114966..32f58cb9363 100644 --- 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 | Promise; + 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; + +export type TemplateParamFunction = ( + params: Record +) => Record | Promise>; 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; + +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 | 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>; + + /** 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; +}) satisfies z.ZodType; const HtmlRspackPluginImpl = create( BuiltinPluginName.HtmlRspackPlugin, diff --git a/packages/rspack/src/builtin-plugin/IgnorePlugin.ts b/packages/rspack/src/builtin-plugin/IgnorePlugin.ts index 6a2481c2b96..1bc0faf6bb4 100644 --- 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; + + /** 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; }; @@ -24,7 +28,7 @@ const IgnorePluginOptions = z.union([ z.object({ checkResource: z.function(z.tuple([z.string(), z.string()]), z.boolean()) }) -]); +]) satisfies z.ZodType; 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 index c0cecb69d14..d0f9cf48971 100644 --- 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 | Promise); templateParameters?: Record | (oldParams: params: Record) => Record | Promise>; - 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 index ce50947147e..c13da557a37 100644 --- 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 | Promise); templateParameters?: Record | (oldParams: params: Record) => Record | Promise>; - 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 的配置自动判断',