feat: align object interface for transformIndexHtml hook (#9669)

Author: antfu

docs/guide/api-plugin.md

@@ -329,7 +329,7 @@ Vite plugins can also provide hooks that serve Vite-specific purposes. These hoo
 
 ### `transformIndexHtml`
 
-- **Type:** `IndexHtmlTransformHook | { enforce?: 'pre' | 'post', transform: IndexHtmlTransformHook }`
+- **Type:** `IndexHtmlTransformHook | { order?: 'pre' | 'post', handler: IndexHtmlTransformHook }`
 - **Kind:** `async`, `sequential`
 
   Dedicated hook for transforming HTML entry point files such as `index.html`. The hook receives the current HTML string and a transform context. The context exposes the [`ViteDevServer`](./api-javascript#vitedevserver) instance during dev, and exposes the Rollup output bundle during build.

packages/vite/src/node/plugin.ts

@@ -112,7 +112,7 @@ export interface Plugin extends RollupPlugin {
    *
    * By default the transform is applied **after** vite's internal html
    * transform. If you need to apply the transform before vite, use an object:
-   * `{ enforce: 'pre', transform: hook }`
+   * `{ order: 'pre', handler: hook }`
    */
   transformIndexHtml?: IndexHtmlTransform
   /**

packages/vite/src/node/plugins/html.ts

@@ -282,7 +282,9 @@ function handleParseError(
  * Compiles index.html into an entry js module
  */
 export function buildHtmlPlugin(config: ResolvedConfig): Plugin {
-  const [preHooks, postHooks] = resolveHtmlTransforms(config.plugins)
+  const [preHooks, normalHooks, postHooks] = resolveHtmlTransforms(
+    config.plugins
+  )
   preHooks.unshift(preImportMapHook(config))
   postHooks.push(postImportMapHook())
   const processedHtml = new Map<string, string>()
@@ -786,12 +788,16 @@ export function buildHtmlPlugin(config: ResolvedConfig): Plugin {
         if (s) {
           result = s.toString()
         }
-        result = await applyHtmlTransforms(result, postHooks, {
-          path: '/' + relativeUrlPath,
-          filename: id,
-          bundle,
-          chunk
-        })
+        result = await applyHtmlTransforms(
+          result,
+          [...normalHooks, ...postHooks],
+          {
+            path: '/' + relativeUrlPath,
+            filename: id,
+            bundle,
+            chunk
+          }
+        )
         // resolve asset url references
         result = result.replace(assetUrlRE, (_, fileHash, postfix = '') => {
           return toOutputAssetFilePath(this.getFileName(fileHash)) + postfix
@@ -863,9 +869,24 @@ export type IndexHtmlTransformHook = (
 export type IndexHtmlTransform =
   | IndexHtmlTransformHook
   | {
+      order?: 'pre' | 'post' | null
+      /**
+       * @deprecated renamed to `order`
+       */
       enforce?: 'pre' | 'post'
+      /**
+       * @deprecated renamed to `handler`
+       */
       transform: IndexHtmlTransformHook
     }
+  | {
+      order?: 'pre' | 'post' | null
+      /**
+       * @deprecated renamed to `order`
+       */
+      enforce?: 'pre' | 'post'
+      handler: IndexHtmlTransformHook
+    }
 
 export function preImportMapHook(
   config: ResolvedConfig
@@ -914,24 +935,40 @@ export function postImportMapHook(): IndexHtmlTransformHook {
 
 export function resolveHtmlTransforms(
   plugins: readonly Plugin[]
-): [IndexHtmlTransformHook[], IndexHtmlTransformHook[]] {
+): [
+  IndexHtmlTransformHook[],
+  IndexHtmlTransformHook[],
+  IndexHtmlTransformHook[]
+] {
   const preHooks: IndexHtmlTransformHook[] = []
+  const normalHooks: IndexHtmlTransformHook[] = []
   const postHooks: IndexHtmlTransformHook[] = []
 
   for (const plugin of plugins) {
     const hook = plugin.transformIndexHtml
-    if (hook) {
-      if (typeof hook === 'function') {
-        postHooks.push(hook)
-      } else if (hook.enforce === 'pre') {
-        preHooks.push(hook.transform)
+    if (!hook) continue
+
+    if (typeof hook === 'function') {
+      normalHooks.push(hook)
+    } else {
+      // `enforce` had only two possible values for the `transformIndexHtml` hook
+      // `'pre'` and `'post'` (the default). `order` now works with three values
+      // to align with other hooks (`'pre'`, normal, and `'post'`). We map
+      // both `enforce: 'post'` to `order: undefined` to avoid a breaking change
+      const order = hook.order ?? (hook.enforce === 'pre' ? 'pre' : undefined)
+      // @ts-expect-error union type
+      const handler = hook.handler ?? hook.transform
+      if (order === 'pre') {
+        preHooks.push(handler)
+      } else if (order === 'post') {
+        postHooks.push(handler)
       } else {
-        postHooks.push(hook.transform)
+        normalHooks.push(handler)
       }
     }
   }
 
-  return [preHooks, postHooks]
+  return [preHooks, normalHooks, postHooks]
 }
 
 export async function applyHtmlTransforms(

packages/vite/src/node/server/middlewares/indexHtml.ts

@@ -42,14 +42,17 @@ interface AssetNode {
 export function createDevHtmlTransformFn(
   server: ViteDevServer
 ): (url: string, html: string, originalUrl: string) => Promise<string> {
-  const [preHooks, postHooks] = resolveHtmlTransforms(server.config.plugins)
+  const [preHooks, normalHooks, postHooks] = resolveHtmlTransforms(
+    server.config.plugins
+  )
   return (url: string, html: string, originalUrl: string): Promise<string> => {
     return applyHtmlTransforms(
       html,
       [
         preImportMapHook(server.config),
         ...preHooks,
         devHtmlHook,
+        ...normalHooks,
         ...postHooks,
         postImportMapHook()
       ],

playground/html/vite.config.js

@@ -36,8 +36,8 @@ module.exports = {
     {
       name: 'pre-transform',
       transformIndexHtml: {
-        enforce: 'pre',
-        transform(html, { filename }) {
+        order: 'pre',
+        handler(html, { filename }) {
           if (html.includes('/@vite/client')) {
             throw new Error('pre transform applied at wrong time!')
           }