feat: build.modulePreload options

docs/config/build-options.md

@@ -17,21 +17,65 @@ The transform is performed with esbuild and the value should be a valid [esbuild
 
 Note the build will fail if the code contains features that cannot be safely transpiled by esbuild. See [esbuild docs](https://esbuild.github.io/content-types/#javascript) for more details.
 
-## build.polyfillModulePreload
+## build.modulePreload
 
-- **Type:** `boolean`
+- **Type:** `boolean | { polyfill?: boolean, resolveDependencies?: ResolveModulePreloadDependenciesFn }`
 - **Default:** `true`
 
-Whether to automatically inject [module preload polyfill](https://guybedford.com/es-module-preloading-integrity#modulepreload-polyfill).
-
-If set to `true`, the polyfill is auto injected into the proxy module of each `index.html` entry. If the build is configured to use a non-html custom entry via `build.rollupOptions.input`, then it is necessary to manually import the polyfill in your custom entry:
+By default, a [module preload polyfill](https://guybedford.com/es-module-preloading-integrity#modulepreload-polyfill) is automatically injected. The polyfill is auto injected into the proxy module of each `index.html` entry. If the build is configured to use a non-html custom entry via `build.rollupOptions.input`, then it is necessary to manually import the polyfill in your custom entry:
 
 ```js
 import 'vite/modulepreload-polyfill'
 ```
 
 Note: the polyfill does **not** apply to [Library Mode](/guide/build#library-mode). If you need to support browsers without native dynamic import, you should probably avoid using it in your library.
 
+The polyfill can be disabled using `{ polyfill: false }`.
+
+The list of chunks to preload for each dynamic import is computed by Vite. By default, an absolute path including the `base` will be used when loading these dependencies. If the `base` is relative (`''` or `'./'`), `import.meta.url` is used at runtime to avoid absolute paths that depends on final the deployed base.
+
+There is experimental support for fine grained control over the dependencies list and their paths using the `resolveDependencies` function. It expects a function of type `ResolveModulePreloadDependenciesFn`
+
+```ts
+type ResolveModulePreloadDependenciesFn = (
+  url: string,
+  deps: string[],
+  context: {
+    importer: string
+  }
+) => (string | { runtime?: string })[]
+```
+
+The `resolveDependencies` function will be called for each dynamic import with a list of the chunks it depends on. A new dependencies array can be returned with these filtered or more dependencies injected, and their paths modified. The `deps` paths are relative to the `build.outDir`.
+
+```js
+    modulePreload: {
+        resolveDependencies: (url, deps, { importer }) => {
+            return deps.map((dep) => {
+                if (...) {
+                    // a relative path to the importer makes the dependency independent of the base
+                    // this is the default
+                    return { relative: dep } // ~ `path.relative(path.dirname(importer), dep)`
+                }
+                else if (...) {
+                    // a runtime expression can be returned
+                    return { runtime: `globalThis.__preloadPath(${dep}, import.meta.url)` }
+                }
+                // returning the dep as is defaults to the regular resolution
+                return dep
+            })
+        }
+    }
+```
+
+## build.polyfillModulePreload
+
+- **Type:** `boolean`
+- **Default:** `true`
+- **Deprecated** use `build.modulePreload.polyfill` instead
+
+Whether to automatically inject [module preload polyfill](https://guybedford.com/es-module-preloading-integrity#modulepreload-polyfill).
+
 ## build.outDir
 
 - **Type:** `string`

packages/vite/src/node/build.ts

@@ -73,8 +73,15 @@ export interface BuildOptions {
    * whether to inject module preload polyfill.
    * Note: does not apply to library mode.
    * @default true
+   * @deprecated use `modulePreload.polyfill` instead
    */
   polyfillModulePreload?: boolean
+  /**
+   * Configure module preload
+   * Note: does not apply to library mode.
+   * @default true
+   */
+  modulePreload?: boolean | ModulePreloadOptions
   /**
    * Directory relative from `root` where build output will be placed. If the
    * directory exists, it will be removed before the build.
@@ -229,16 +236,59 @@ export interface LibraryOptions {
 
 export type LibraryFormats = 'es' | 'cjs' | 'umd' | 'iife'
 
-export type ResolvedBuildOptions = Required<BuildOptions>
+export interface ModulePreloadOptions {
+  /**
+   * whether to inject module preload polyfill.
+   * Note: does not apply to library mode.
+   * @default true
+   */
+  polyfill?: boolean
+  /**
+   * Resolve the list of dependencies to preload for
+   * a given dynamic import
+   * @experimental
+   */
+  resolveDependencies?: ResolveModulePreloadDependenciesFn
+}
+
+export type ResolveModulePreloadDependenciesFn = (
+  url: string,
+  deps: string[],
+  context: {
+    importer: string
+  }
+) => (string | { runtime?: string; relative?: string })[]
+
+export type ResolvedBuildOptions = Required<
+  Omit<BuildOptions, 'polyfillModulePreload'>
+>
 
 export function resolveBuildOptions(
   raw: BuildOptions | undefined,
   isBuild: boolean,
   logger: Logger
 ): ResolvedBuildOptions {
+  const deprecatedPolyfillModulePreload = raw?.polyfillModulePreload
+  if (raw) {
+    const { polyfillModulePreload, ...rest } = raw
+    raw = rest
+    if (deprecatedPolyfillModulePreload !== undefined) {
+      logger.warn(
+        'polyfillModulePreload is deprecated. Use modulePreload.polyfill instead.'
+      )
+    }
+    if (
+      deprecatedPolyfillModulePreload === false &&
+      raw.modulePreload === undefined
+    ) {
+      raw.modulePreload = { polyfill: false }
+    }
+  }
+
+  const modulePreload = raw?.modulePreload
+
   const resolved: ResolvedBuildOptions = {
     target: 'modules',
-    polyfillModulePreload: true,
     outDir: 'dist',
     assetsDir: 'assets',
     assetsInlineLimit: 4096,
@@ -267,7 +317,14 @@ export function resolveBuildOptions(
       warnOnError: true,
       exclude: [/node_modules/],
       ...raw?.dynamicImportVarsOptions
-    }
+    },
+    modulePreload:
+      typeof modulePreload === 'object'
+        ? {
+            polyfill: true,
+            ...modulePreload
+          }
+        : modulePreload ?? true
   }
 
   // handle special build targets

packages/vite/src/node/config.ts

@@ -60,7 +60,11 @@ import { resolveSSROptions } from './ssr'
 
 const debug = createDebugger('vite:config')
 
-export type { RenderBuiltAssetUrl } from './build'
+export type {
+  RenderBuiltAssetUrl,
+  ModulePreloadOptions,
+  ResolveModulePreloadDependenciesFn
+} from './build'
 
 // NOTE: every export in this file is re-exported from ./index.ts so it will
 // be part of the public API.

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

@@ -581,8 +581,10 @@ export function buildHtmlPlugin(config: ResolvedConfig): Plugin {
         processedHtml.set(id, s.toString())
 
         // inject module preload polyfill only when configured and needed
+        const { modulePreload } = config.build
         if (
-          config.build.polyfillModulePreload &&
+          (modulePreload === true ||
+            (typeof modulePreload === 'object' && modulePreload.polyfill)) &&
           (someScriptsAreAsync || someScriptsAreDefer)
         ) {
           js = `import "${modulePreloadPolyfillId}";\n${js}`

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

@@ -108,13 +108,26 @@ function preload(
 export function buildImportAnalysisPlugin(config: ResolvedConfig): Plugin {
   const ssr = !!config.build.ssr
   const isWorker = config.isWorker
-  const insertPreload = !(ssr || !!config.build.lib || isWorker)
-
-  const relativePreloadUrls = config.base === './' || config.base === ''
-
-  const scriptRel = config.build.polyfillModulePreload
-    ? `'modulepreload'`
-    : `(${detectScriptRel.toString()})()`
+  const insertPreload = !(
+    ssr ||
+    !!config.build.lib ||
+    isWorker ||
+    config.build.modulePreload === false
+  )
+
+  const customResolveModulePreloadDependencies =
+    typeof config.build.modulePreload === 'object' &&
+    config.build.modulePreload.resolveDependencies
+  const isRelativeBase = config.base === './' || config.base === ''
+  const relativePreloadUrls =
+    isRelativeBase || customResolveModulePreloadDependencies
+
+  const { modulePreload } = config.build
+  const scriptRel =
+    modulePreload === true ||
+    (typeof modulePreload === 'object' && modulePreload.polyfill)
+      ? `'modulepreload'`
+      : `(${detectScriptRel.toString()})()`
   const assetsURL = relativePreloadUrls
     ? `function(dep,importerUrl) { return new URL(dep, importerUrl).href }`
     : `function(dep) { return ${JSON.stringify(config.base)}+dep }`
@@ -367,7 +380,12 @@ export function buildImportAnalysisPlugin(config: ResolvedConfig): Plugin {
     },
 
     generateBundle({ format }, bundle) {
-      if (format !== 'es' || ssr || isWorker) {
+      if (
+        format !== 'es' ||
+        ssr ||
+        isWorker ||
+        config.build.modulePreload === false
+      ) {
         return
       }
 
@@ -454,25 +472,56 @@ export function buildImportAnalysisPlugin(config: ResolvedConfig): Plugin {
               }
 
               if (markerStartPos > 0) {
-                s.overwrite(
-                  markerStartPos,
-                  markerStartPos + preloadMarkerWithQuote.length,
-                  // the dep list includes the main chunk, so only need to reload when there are
-                  // actual other deps. Don't include the assets dir if the default asset file names
-                  // are used, the path will be reconstructed by the import preload helper
+                const { modulePreload } = config.build
+                // the dep list includes the main chunk, so only need to reload when there are actual other deps.
+                const depsArray =
                   deps.size > 1 ||
-                    // main chunk is removed
-                    (hasRemovedPureCssChunk && deps.size > 0)
-                    ? `[${[...deps]
-                        .map((d) =>
-                          JSON.stringify(
-                            relativePreloadUrls
-                              ? path.relative(path.dirname(file), d)
-                              : d
+                  // main chunk is removed
+                  (hasRemovedPureCssChunk && deps.size > 0)
+                    ? [...deps]
+                    : []
+                const toRelative = (dep: string) =>
+                  path.relative(path.dirname(file), dep)
+                const resolvedDependencies =
+                  url &&
+                  typeof modulePreload === 'object' &&
+                  modulePreload.resolveDependencies
+                    ? modulePreload
+                        .resolveDependencies(url, depsArray, { importer: file })
+                        .map((dep) => {
+                          if (typeof dep === 'object') {
+                            if (dep.runtime) {
+                              return dep.runtime
+                            }
+                            if (dep.relative) {
+                              return JSON.stringify(toRelative(dep.relative))
+                            }
+                            throw new Error(
+                              `Invalid dependency object, no runtime or relative option specified`
+                            )
+                          }
+                          return JSON.stringify(
+                            depsArray.includes(dep)
+                              ? isRelativeBase
+                                ? toRelative(dep)
+                                : config.base + dep
+                              : dep
                           )
+                        })
+                    : depsArray.map((d) =>
+                        // Don't include the assets dir if the default asset file names
+                        // are used, the path will be reconstructed by the import preload helper
+                        JSON.stringify(
+                          relativePreloadUrls
+                            ? path.relative(path.dirname(file), d)
+                            : d
                         )
-                        .join(',')}]`
-                    : `[]`,
+                      )
+
+                s.overwrite(
+                  markerStartPos,
+                  markerStartPos + preloadMarkerWithQuote.length,
+                  `[${resolvedDependencies.join(',')}]`,
                   { contentOnly: true }
                 )
                 rewroteMarkerStartPos.add(markerStartPos)

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

@@ -36,14 +36,16 @@ export async function resolvePlugins(
   const buildPlugins = isBuild
     ? (await import('../build')).resolveBuildPlugins(config)
     : { pre: [], post: [] }
+  const { modulePreload } = config.build
 
   return [
     isWatch ? ensureWatchPlugin() : null,
     isBuild ? metadataPlugin() : null,
     preAliasPlugin(config),
     aliasPlugin({ entries: config.resolve.alias }),
     ...prePlugins,
-    config.build.polyfillModulePreload
+    modulePreload === true ||
+    (typeof modulePreload === 'object' && modulePreload.polyfill)
       ? modulePreloadPolyfillPlugin(config)
       : null,
     ...(isDepsOptimizerEnabled(config, false) ||

playground/preload/__tests__/preload-disabled/preload-disabled.spec.ts

@@ -0,0 +1,22 @@
+import { describe, expect, test } from 'vitest'
+import { browserLogs, isBuild, page, viteTestUrl } from '~utils'
+
+test('should have no 404s', () => {
+  browserLogs.forEach((msg) => {
+    expect(msg).not.toMatch('404')
+  })
+})
+
+describe.runIf(isBuild)('build', () => {
+  test('dynamic import', async () => {
+    const appHtml = await page.content()
+    expect(appHtml).toMatch('This is <b>home</b> page.')
+  })
+
+  test('dynamic import with comments', async () => {
+    await page.goto(viteTestUrl + '/#/hello')
+    const html = await page.content()
+    expect(html).not.toMatch(/link rel="modulepreload"/)
+    expect(html).not.toMatch(/link rel="stylesheet"/)
+  })
+})

playground/preload/__tests__/preload-disabled/vite.config.js

@@ -0,0 +1 @@
+module.exports = require('../../vite.config-preload-disabled')

playground/preload/__tests__/resolve-deps/preload-resolve-deps.spec.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from 'vitest'
+import { browserLogs, isBuild, page, viteTestUrl } from '~utils'
+
+test('should have no 404s', () => {
+  browserLogs.forEach((msg) => {
+    expect(msg).not.toMatch('404')
+  })
+})
+
+describe.runIf(isBuild)('build', () => {
+  test('dynamic import', async () => {
+    const appHtml = await page.content()
+    expect(appHtml).toMatch('This is <b>home</b> page.')
+  })
+
+  test('dynamic import with comments', async () => {
+    await page.goto(viteTestUrl + '/#/hello')
+    const html = await page.content()
+    expect(html).toMatch(
+      /link rel="modulepreload".*?href="http.*?\/Hello\.\w{8}\.js"/
+    )
+    expect(html).toMatch(
+      /link rel="stylesheet".*?href="http.*?\/Hello\.\w{8}\.css"/
+    )
+  })
+})

playground/preload/__tests__/resolve-deps/vite.config.js

@@ -0,0 +1 @@
+module.exports = require('../../vite.config-resolve-deps')

playground/preload/package.json

@@ -6,7 +6,15 @@
     "dev": "vite",
     "build": "vite build",
     "debug": "node --inspect-brk ../../packages/vite/bin/vite",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "dev:resolve-deps": "vite --config vite.config-resolve-deps.ts",
+    "build:resolve-deps": "vite build --config vite.config-resolve-deps.ts",
+    "debug:resolve-deps": "node --inspect-brk ../../packages/vite/bin/vite --config vite.config-resolve-deps.ts",
+    "preview:resolve-deps": "vite preview --config vite.config-resolve-deps.ts",
+    "dev:preload-disabled": "vite --config vite.config-preload-disabled.ts",
+    "build:preload-disabled": "vite build --config vite.config-preload-disabled.ts",
+    "debug:preload-disabled": "node --inspect-brk ../../packages/vite/bin/vite --config vite.config-preload-disabled.ts",
+    "preview:preload-disabled": "vite preview --config vite.config-preload-disabled.ts"
   },
   "dependencies": {
     "vue": "^3.2.37",