feat: chunk importmap

docs/config/build-options.md

@@ -279,3 +279,10 @@ There are cases that file system watching does not work with WSL2.
 See [`server.watch`](./server-options.md#server-watch) for more details.
 
 :::
+
+## build.chunkImportMap
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Whether to inject importmap for generated chunks. This importmap is used to optimize caching efficiency.

docs/guide/features.md

@@ -715,7 +715,7 @@ Do not allow `data:` for [`script-src`](https://developer.mozilla.org/en-US/docs
 
 ## Build Optimizations
 
-> Features listed below are automatically applied as part of the build process and there is no need for explicit configuration unless you want to disable them.
+> Features listed below (except for the chunk importmap feature) are automatically applied as part of the build process and there is no need for explicit configuration unless you want to disable them.
 
 ### CSS Code Splitting
 
@@ -749,3 +749,7 @@ Entry ---> (A + C)
 ```
 
 It is possible for `C` to have further imports, which will result in even more roundtrips in the un-optimized scenario. Vite's optimization will trace all the direct imports to completely eliminate the roundtrips regardless of import depth.
+
+### Chunk importmap
+
+Creating an import map for chunks helps prevent the issue of cascading cache invalidation. This import map features a list of stable file IDs linked to filenames with content-based hashes. When one chunk references another, it utilizes the file ID instead of the content-hashed filename. As a result, only the updated chunk needs cache invalidation in the browser, leaving intermediary chunks unchanged. This strategy enhances the cache hit rate following deployments.

packages/plugin-legacy/src/index.ts

@@ -136,6 +136,51 @@ const _require = createRequire(import.meta.url)
 const nonLeadingHashInFileNameRE = /[^/]+\[hash(?::\d+)?\]/
 const prefixedHashInFileNameRE = /\W?\[hash(?::\d+)?\]/
 
+const hashPlaceholderLeft = '!~{'
+const hashPlaceholderRight = '}~'
+const hashPlaceholderOverhead =
+  hashPlaceholderLeft.length + hashPlaceholderRight.length
+const maxHashSize = 22
+// from https://github.com/rollup/rollup/blob/91352494fc722bcd5e8e922cd1497b34aec57a67/src/utils/hashPlaceholders.ts#L41-L46
+const hashPlaceholderRE = new RegExp(
+  // eslint-disable-next-line regexp/strict, regexp/prefer-w
+  `${hashPlaceholderLeft}[0-9a-zA-Z_$]{1,${
+    maxHashSize - hashPlaceholderOverhead
+  }}${hashPlaceholderRight}`,
+  'g',
+)
+
+const hashPlaceholderToFacadeModuleIdHashMap = new Map<string, string>()
+
+function augmentFacadeModuleIdHash(name: string): string {
+  return name.replace(
+    hashPlaceholderRE,
+    (match) => hashPlaceholderToFacadeModuleIdHashMap.get(match) ?? match,
+  )
+}
+
+function createChunkImportMap(
+  bundle: OutputBundle,
+  base: string,
+): Record<string, string> {
+  return Object.fromEntries(
+    Object.values(bundle)
+      .filter((chunk): chunk is OutputChunk => chunk.type === 'chunk')
+      .map((output) => {
+        return [
+          base + augmentFacadeModuleIdHash(output.preliminaryFileName),
+          base + output.fileName,
+        ]
+      }),
+  )
+}
+
+export function getHash(text: Buffer | string, length = 8): string {
+  const h = hash('sha256', text, 'hex').substring(0, length)
+  if (length <= 64) return h
+  return h.padEnd(length, '_')
+}
+
 function viteLegacyPlugin(options: Options = {}): Plugin[] {
   let config: ResolvedConfig
   let targets: Options['targets']
@@ -167,6 +212,7 @@ function viteLegacyPlugin(options: Options = {}): Plugin[] {
   const isDebug =
     debugFlags.includes('vite:*') || debugFlags.includes('vite:legacy')
 
+  const chunkImportMap = new Map()
   const facadeToLegacyChunkMap = new Map()
   const facadeToLegacyPolyfillMap = new Map()
   const facadeToModernPolyfillMap = new Map()
@@ -519,6 +565,16 @@ function viteLegacyPlugin(options: Options = {}): Plugin[] {
         }
       }
 
+      if (config.build.chunkImportMap) {
+        const hashPlaceholder = chunk.fileName.match(hashPlaceholderRE)?.[0]
+        if (hashPlaceholder) {
+          hashPlaceholderToFacadeModuleIdHashMap.set(
+            hashPlaceholder,
+            getHash(chunk.facadeModuleId ?? chunk.fileName),
+          )
+        }
+      }
+
       if (!genLegacy) {
         return null
       }
@@ -574,13 +630,26 @@ function viteLegacyPlugin(options: Options = {}): Plugin[] {
       return null
     },
 
-    transformIndexHtml(html, { chunk }) {
+    transformIndexHtml(html, { chunk, filename, bundle }) {
       if (config.build.ssr) return
       if (!chunk) return
       if (chunk.fileName.includes('-legacy')) {
         // The legacy bundle is built first, and its index.html isn't actually emitted if
         // modern bundle will be generated. Here we simply record its corresponding legacy chunk.
         facadeToLegacyChunkMap.set(chunk.facadeModuleId, chunk.fileName)
+
+        if (config.build.chunkImportMap) {
+          const relativeUrlPath = path.posix.relative(
+            config.root,
+            normalizePath(filename),
+          )
+          const assetsBase = getBaseInHTML(relativeUrlPath, config)
+          chunkImportMap.set(
+            chunk.facadeModuleId,
+            createChunkImportMap(bundle!, assetsBase),
+          )
+        }
+
         if (genModern) {
           return
         }
@@ -703,6 +772,19 @@ function viteLegacyPlugin(options: Options = {}): Plugin[] {
         })
       }
 
+      if (config.build.chunkImportMap) {
+        const imports = chunkImportMap.get(chunk.facadeModuleId)
+
+        if (imports) {
+          tags.push({
+            tag: 'script',
+            attrs: { type: 'systemjs-importmap' },
+            children: JSON.stringify({ imports }),
+            injectTo: 'head-prepend',
+          })
+        }
+      }
+
       return {
         html,
         tags,

packages/vite/src/node/__tests__/build.spec.ts

@@ -60,6 +60,42 @@ describe('build', () => {
     assertOutputHashContentChange(result[0], result[1])
   })
 
+  test('file hash should not change when changes for dynamic entries while chunk map option enabled', async () => {
+    const buildProject = async (text: string) => {
+      return (await build({
+        root: resolve(__dirname, 'packages/build-project'),
+        logLevel: 'silent',
+        build: {
+          chunkImportMap: true,
+          write: false,
+        },
+        plugins: [
+          {
+            name: 'test',
+            resolveId(id) {
+              if (id === 'entry.js' || id === 'subentry.js') {
+                return '\0' + id
+              }
+            },
+            load(id) {
+              if (id === '\0entry.js') {
+                return `window.addEventListener('click', () => { import('subentry.js') });`
+              }
+              if (id === '\0subentry.js') {
+                return `console.log(${text})`
+              }
+            },
+          },
+        ],
+      })) as RollupOutput
+    }
+
+    const result = await Promise.all([buildProject('foo'), buildProject('bar')])
+
+    expect(result[0].output[0].fileName).toBe(result[1].output[0].fileName)
+    expect(result[0].output[1].fileName).not.toBe(result[1].output[1].fileName)
+  })
+
   test('file hash should change when pure css chunk changes', async () => {
     const buildProject = async (cssColor: string) => {
       return (await build({

packages/vite/src/node/build.ts

@@ -53,6 +53,7 @@ import { resolveEnvironmentPlugins } from './plugin'
 import { manifestPlugin } from './plugins/manifest'
 import type { Logger } from './logger'
 import { dataURIPlugin } from './plugins/dataUri'
+import { chunkImportMapPlugin } from './plugins/chunkImportMap'
 import { buildImportAnalysisPlugin } from './plugins/importAnalysisBuild'
 import { ssrManifestPlugin } from './ssr/ssrManifestPlugin'
 import { buildLoadFallbackPlugin } from './plugins/loadFallback'
@@ -265,6 +266,12 @@ export interface BuildEnvironmentOptions {
    * @default null
    */
   watch?: WatcherOptions | null
+  /**
+   * Whether to inject importmap for generated chunks.
+   * This importmap is used to optimize caching efficiency.
+   * @default false
+   */
+  chunkImportMap?: boolean
   /**
    * create the Build Environment instance
    */
@@ -385,6 +392,7 @@ export function resolveBuildEnvironmentOptions(
     reportCompressedSize: true,
     chunkSizeWarningLimit: 500,
     watch: null,
+    chunkImportMap: false,
     createEnvironment: (name, config) => new BuildEnvironment(name, config),
   }
 
@@ -490,6 +498,9 @@ export async function resolveBuildPlugins(config: ResolvedConfig): Promise<{
         await asyncFlatten(arraify(config.build.rollupOptions.plugins))
       ).filter(Boolean) as Plugin[]),
       ...(config.isWorker ? [webWorkerPostPlugin()] : []),
+      ...(!config.isWorker && config.build.chunkImportMap
+        ? [chunkImportMapPlugin()]
+        : []),
     ],
     post: [
       buildImportAnalysisPlugin(config),

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

@@ -0,0 +1,117 @@
+import path from 'node:path'
+import type { OutputBundle, OutputChunk } from 'rollup'
+import MagicString from 'magic-string'
+import { getHash, normalizePath } from '../utils'
+import type { Plugin } from '../plugin'
+import type { ResolvedConfig } from '../config'
+import type { IndexHtmlTransformHook } from './html'
+
+const hashPlaceholderLeft = '!~{'
+const hashPlaceholderRight = '}~'
+const hashPlaceholderOverhead =
+  hashPlaceholderLeft.length + hashPlaceholderRight.length
+export const maxHashSize = 22
+// from https://github.com/rollup/rollup/blob/91352494fc722bcd5e8e922cd1497b34aec57a67/src/utils/hashPlaceholders.ts#L41-L46
+const hashPlaceholderRE = new RegExp(
+  // eslint-disable-next-line regexp/strict, regexp/prefer-w
+  `${hashPlaceholderLeft}[0-9a-zA-Z_$]{1,${
+    maxHashSize - hashPlaceholderOverhead
+  }}${hashPlaceholderRight}`,
+  'g',
+)
+
+const hashPlaceholderToFacadeModuleIdHashMap = new Map()
+
+function augmentFacadeModuleIdHash(name: string): string {
+  return name.replace(
+    hashPlaceholderRE,
+    (match) => hashPlaceholderToFacadeModuleIdHashMap.get(match) ?? match,
+  )
+}
+
+export function createChunkImportMap(
+  bundle: OutputBundle,
+  base: string = '',
+): Record<string, string> {
+  return Object.fromEntries(
+    Object.values(bundle)
+      .filter((chunk): chunk is OutputChunk => chunk.type === 'chunk')
+      .map((output) => {
+        return [
+          base + augmentFacadeModuleIdHash(output.preliminaryFileName),
+          base + output.fileName,
+        ]
+      }),
+  )
+}
+
+export function chunkImportMapPlugin(): Plugin {
+  return {
+    name: 'vite:chunk-importmap',
+
+    // If the hash part is simply removed, there is a risk of key collisions within the importmap.
+    // For example, both `foo/index-[hash].js` and `index-[hash].js` would become `assets/index-.js`.
+    // Therefore, a hash is generated from the facadeModuleId to avoid this issue.
+    renderChunk(code, _chunk, _options, meta) {
+      Object.values(meta.chunks).forEach((chunk) => {
+        const hashPlaceholder = chunk.fileName.match(hashPlaceholderRE)?.[0]
+        if (!hashPlaceholder) return
+        if (hashPlaceholderToFacadeModuleIdHashMap.get(hashPlaceholder)) return
+
+        hashPlaceholderToFacadeModuleIdHashMap.set(
+          hashPlaceholder,
+          getHash(chunk.facadeModuleId ?? chunk.fileName),
+        )
+      })
+
+      const s = new MagicString(code)
+      // note that MagicString::replace is used instead of String::replace
+      s.replace(
+        hashPlaceholderRE,
+        (match) => hashPlaceholderToFacadeModuleIdHashMap.get(match) ?? match,
+      )
+      return { code: s.toString(), map: s.generateMap({ hires: 'boundary' }) }
+    },
+  }
+}
+
+export function postChunkImportMapHook(
+  config: ResolvedConfig,
+): IndexHtmlTransformHook {
+  return (html, ctx) => {
+    if (!config.build.chunkImportMap) return
+
+    const { filename, bundle } = ctx
+
+    const relativeUrlPath = path.posix.relative(
+      config.root,
+      normalizePath(filename),
+    )
+    const assetsBase = getBaseInHTML(relativeUrlPath, config)
+
+    return {
+      html,
+      tags: [
+        {
+          tag: 'script',
+          attrs: { type: 'importmap' },
+          children: JSON.stringify({
+            imports: createChunkImportMap(bundle!, assetsBase),
+          }),
+          injectTo: 'head-prepend',
+        },
+      ],
+    }
+  }
+}
+
+function getBaseInHTML(urlRelativePath: string, config: ResolvedConfig) {
+  // Prefer explicit URL if defined for linking to assets and public files from HTML,
+  // even when base relative is specified
+  return config.base === './' || config.base === ''
+    ? path.posix.join(
+        path.posix.relative(urlRelativePath, '').slice(0, -2),
+        './',
+      )
+    : config.base
+}