feat: chunk importmap by bhbs · Pull Request #16552 · vitejs/vite

bhbs · 2024-04-29T06:51:18Z

It seems that many people have been requesting improvements in chunk cache efficiency, so I've created this PR. Please take a look and review this! Thank you, Vite team!

Description

Fixes: #6773
PoC: #15373
Discussion: #15372

Creating an importmap for chunks helps prevent cascading cache invalidation. This importmap features a list of filenames with file ID-based hashes linked to filenames with content-based hashes. When one chunk references another, it uses the ID-hashed filename instead of the content-hashed filename. As a result, only the updated chunk requires cache invalidation in the browser, leaving intermediary chunks unchanged. This strategy enhances the cache hit rate following deployments.

Implementation

During the renderChunk step, file hash placeholders in the code are overwritten with stable ID hashes. This process also maintains a record of the hash placeholders and their corresponding ID hashes. (After that, during the augmentHash step, filenames are assigned based on the content.)

Based on the generated chunk list and the record of hash placeholders and their corresponding hashes, an importmap is generated and inserted into the HTML.

Others

An importmap is generated for legacy bundles using the same method, but a systemjs-importmap is inserted instead of a standard importmap.
The importmap is considered during CSS processing (cssPostPlugin).
The importmap is considered during import analysis (buildImportAnalysisPlugin).
Only one importmap can be loaded at a time (MDN). If an importmap already exists, it needs to be merged (buildHtmlPlugin).

bolt-new-by-stackblitz · 2024-04-29T06:51:20Z

Run & review this pull request in StackBlitz Codeflow.

olivierbeaulieu · 2024-07-12T14:28:25Z

This fixes such a gigantic performance issue in almost every vite app out there - thanks a lot! Hopefully this can get merged soon 👀

Lgowen · 2024-08-15T10:10:38Z

So this PR has not been merged yet, right?

paolostyle · 2024-09-11T21:27:18Z

Is there any way to ask the maintainers to review this? It's a shame that such a useful PR is open for over 4 months without any reviews...

C-Higgins · 2024-09-18T21:35:00Z

What is the simplest way to consume this code manually, until (if ever) it gets merged?

juanespinola05 · 2024-09-19T12:40:46Z

What is the simplest way to consume this code manually, until (if ever) it gets merged?

This ☝

sapphi-red

Thanks for working on this! Sorry that it took time to review.
While I think it needs some small things to polish, the approach looks good to me. I think the remaining tasks are to think about how this works with experimental.renderBuiltUrl and think about the interaction with plugins.

sapphi-red · 2024-10-17T02:52:18Z

+## html.chunkImportMap
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Whether to inject importmap for generated chunks. This importmap is used to optimize caching efficiency.
+


It seems build.chunkImportMap is used instead of html.chunkImportMap in the code.
I think build.chunkImportMap is better as I think we should have an option to generate the import map in a separate file so that frameworks and users using backend integration can use it.
Let's move this description to docs/config/build-options.md.

Might even be worth being an experimental feature. build.experimentalChunkImportMap

Im really looking forward to this change as itll be a massive win for users.

I expect though at this time there may be gotchas we need to learn and patch, as people report behaviour issues with there individual setups.

I think we can set experimental without changing the name. 👍

Nice, I need to use this feature as backend integration 👍 . It would be great if we could export ImportMap contents into a file like import-maps.json, and the consumers can name as the build.manifest feature (ref: https://vite.dev/config/build-options.html#build-manifest)

sapphi-red · 2024-10-17T03:19:35Z

+        return [
+          base + augmentFacadeModuleIdHash(output.preliminaryFileName),
+          base + output.fileName,
+        ]


📝 Note to reviewers: the mapping by the browsers is operated after both the module specifier and the key of import maps are resolved to absolute URLs.
https://html.spec.whatwg.org/multipage/webappapis.html#import-maps:~:text=Such%20remappings%20operate,app.mjs%22

sapphi-red · 2024-10-17T03:21:36Z

+      config.root,
+      normalizePath(filename),
+    )
+    const assetsBase = getBaseInHTML(relativeUrlPath, config)


I guess this does not take experimental.renderBuiltUrl into account. For non-runtime ones, we can generate a static import map. But for runtime ones, I guess we would need to output an script that constructs an import map.

I haven’t come up with a good way to use it together with the renderBuiltUrl runtime yet.
Considering that we need to handle the import map from other plugins, we’ll need some kind of clever solution.
Are there any other options that could be used as a reference?

I’ll need some time to investigate and think it over.

I guess there aren't any.

sapphi-red · 2024-10-17T03:58:55Z

@@ -519,6 +566,16 @@ function viteLegacyPlugin(options: Options = {}): Plugin[] {
        }
      }



When build.chunkImportMap is enabled, I guess the application won't work if the browser does not support import maps but supports all features included in detectModernBrowserDetector.
I think we need to add if(HTMLScriptElement&&HTMLScriptElement.supports("importmap"))throw new Error; to detectModernBrowserDetector and modernChunkLegacyGuard.

I tried simply adding an if statement at the end of detectModernBrowserDetector, but it doesn't seem to have worked 👀
It seems that __vite_legacy_guard inside modernChunkLegacyGuard is not being executed from anywhere.
Could you explain how it works?

It seems that __vite_legacy_guard inside modernChunkLegacyGuard is not being executed from anywhere.
Could you explain how it works?

The current modernChunkLegacyGuard uses the fact that browsers errors without executing a script if the script has invalid syntax (unsupported syntax). But in this case, we are judging with runtime code instead of a syntax. So I was suggesting adding the code in modernChunkLegacyGuard (i.e. changing modernChunkLegacyGuard to `if(HTMLScriptElement&&HTMLScriptElement.supports("importmap"))throw new Error;`);export function __vite_legacy_guard(){${detectModernBrowserDetector}};`.

That said, I noticed that the script that has the throw new Error won't run but still the scripts imported by that script would run. Hmm...

sapphi-red · 2024-10-17T04:01:59Z

+      const chunkImportMap = config.build.chunkImportMap
+        ? createChunkImportMap(bundle)
+        : {}


Probably we need to think about how to let other plugins access this information. I assume other plugins will need to access this information sometimes.

sapphi-red · 2024-10-17T04:11:40Z

+      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 codeProcessed = augmentFacadeModuleIdHash(code)
+      return {
+        code: codeProcessed,
+        map: new MagicString(codeProcessed).generateMap({
+          hires: 'boundary',
+        }),


📝 For reviewers: This works as rollup calculates the chunk hash after the renderChunk hooks are run since Rollup 3.

Reference: https://www.youtube.com/watch?v=cFwO9UvDzfI

bhbs · 2024-10-17T14:13:43Z

Thank you for the review ✨
I should have some time this weekend, so I'll incorporate your feedback.

…solver

…ilePathInJS`

bhbs · 2024-10-21T15:23:09Z

I’ve pushed what I have for now!
But still these tasks remains:

I think the remaining tasks are to think about how this works with experimental.renderBuiltUrl and think about the interaction with plugins.

I need more time 🧐

sapphi-red · 2024-10-22T04:38:19Z

+
+### 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.


Suggested change

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.

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.

To enable this feature, set [`build.chunkImportMap`](/config/build-options.md#build-chunkimportmap) to `true`.

sapphi-red · 2024-10-22T04:42:57Z

+## html.chunkImportMap
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Whether to inject importmap for generated chunks. This importmap is used to optimize caching efficiency.
+


I think we can set experimental without changing the name. 👍

sapphi-red · 2024-10-22T04:43:02Z

+## build.chunkImportMap
+
+- **Type:** `boolean`
+- **Default:** `false`


Suggested change

- **Default:** `false`

- **Default:** `false`

- **Experimental**

#16552 (comment)

sapphi-red · 2024-10-22T04:50:24Z

@@ -519,6 +566,16 @@ function viteLegacyPlugin(options: Options = {}): Plugin[] {
        }
      }



It seems that __vite_legacy_guard inside modernChunkLegacyGuard is not being executed from anywhere.
Could you explain how it works?

The current modernChunkLegacyGuard uses the fact that browsers errors without executing a script if the script has invalid syntax (unsupported syntax). But in this case, we are judging with runtime code instead of a syntax. So I was suggesting adding the code in modernChunkLegacyGuard (i.e. changing modernChunkLegacyGuard to `if(HTMLScriptElement&&HTMLScriptElement.supports("importmap"))throw new Error;`);export function __vite_legacy_guard(){${detectModernBrowserDetector}};`.

That said, I noticed that the script that has the throw new Error won't run but still the scripts imported by that script would run. Hmm...

sapphi-red · 2024-10-22T04:52:40Z

+      config.root,
+      normalizePath(filename),
+    )
+    const assetsBase = getBaseInHTML(relativeUrlPath, config)


I guess there aren't any.

lansi951 · 2025-01-18T08:15:15Z

I think cache is an important issue on the web.
So I waiting to merge this PR.

Are there any updates?

jonomuller · 2025-01-30T13:43:23Z

Are there any updates on this PR? The poor caching performance at the moment is blocking us from using Vite in production.

olivierbeaulieu · 2025-02-05T17:17:32Z

@bhbs we've been running an older version of these changes for a while in production - and it works almost perfectly.

However we've noticed one issue recently with it. I was waiting to create a reproduction for you to look at, but I haven't found the time to do it - so I figure it's probably better to describe the issue now, and maybe it'll make sense to you without a reproduction.

The issue has to do with Async Chunk Loading Optimization, basically the __vite__mapDeps array that gets injected into chunks.

In our codebase, we've seen cases where some changes can cause a chunk that has a __vite__mapDeps array to have the same chunk hash across two different builds, despite its actual content being slightly different due to one or many entries in __vite__mapDeps having changed across builds.

It doesn't seem to ever cause user-visible errors - beyond causing a lot of 404s since we're trying to preload files that do not exist in the importmap, and of course this means that prefetching won't work, leading to slower app loads.

Let me know if that is useful information.

bhbs · 2025-02-10T05:53:46Z

@jonomuller Just to clarify and avoid any misunderstanding, this cascading cache invalidation issue also occurs with other tools—Webpack (Next.js), Rollup, esbuild, etc. The fact that this issue has yet to be fully resolved should not be a reason not to use in production 😀 (That said, if an OSS solution already exists that addresses this problem, I would love to learn about it.)

jonomuller · 2025-02-11T15:52:12Z

@bhbs Thanks for the reply! At least for our use case (coming from a CRA app using Webpack and migrating to Vite), CRA/Webpack seemed to have a solution for this at runtime that did not use importmaps, which then surprised us when switching over to Vite. This article provides a good example of how it works.

Using your solution solves the problem, but we've been unable to use it in production due to browser compatibility issues with import.meta.resolve and importmap (should hopefully be resolved with a polyfill). Without it though, we're seeing that a large majority of chunks are invalidated after each change, which is resulting in worse performance and increased load/cost on our CDN. Definitely not an expert on this stuff so we might be missing something, but this kind of feature seems quite core to Vite.

bhbs · 2025-02-23T07:32:19Z

@jonomuller
Thank you for the information!
After checking, I see you’re right—cascading invalidation has indeed been solved in other tools like Webpack.

bhbs · 2025-02-23T07:33:13Z

In this PR, I aim to tackle the issue in a more elegant way using an import map. With Webpack, for example, when the map is contained in the entry JS file, changes to a terminal chunk file require reloading the HTML, the entry file, and the terminal chunk file. However, by utilizing an import map, you only need to reload the HTML and the terminal chunk file.

And, we need to consider browser compatibility issues as well.
For this PR, the remaining tasks are

improve modernChunkLegacyGuard
take experimental.renderBuiltUrl into account

I apologize for the delay—I’ve been busy with personal matters lately, so I’d be grateful for any contributions from others.

JacobNWolf · 2025-02-26T01:34:01Z

In this PR, I aim to tackle the issue in a more elegant way using an import map. With Webpack, for example, when the map is contained in the entry JS file, changes to a terminal chunk file require reloading the HTML, the entry file, and the terminal chunk file. However, by utilizing an import map, you only need to reload the HTML and the terminal chunk file.

And, we need to consider browser compatibility issues as well. For this PR, the remaining tasks are

improve modernChunkLegacyGuard

take experimental.renderBuiltUrl into account

I apologize for the delay—I’ve been busy with personal matters lately, so I’d be grateful for any contributions from others.

Do you need help getting this across the finish line? Personally would love to help — have an issue with this occurring in Astro when I'm loading long-term cached documents that reference Javascript and CSS files that have been renamed with new hashes on rebuild. Would love to help fix my this problem for Vite.

lansi951 · 2025-03-06T06:26:41Z

Importmap can be loaded from external file.
And sometimes, it needs to use importmap file like Nuxt.
How about adding importmap file output option?

lansi951 · 2025-03-06T06:39:55Z

In legacy browsers, this polyfill can be used to support Importmap.
https://github.com/guybedford/es-module-shims

bhbs marked this pull request as ready for review April 29, 2024 06:59

bhbs mentioned this pull request May 2, 2024

feat: 🧪 chunkMap #15373

Closed

bhbs force-pushed the chunk-importmap branch from 1a0eaf5 to ef5d053 Compare September 19, 2024 13:58

feat: chunk importmap

9bed85b

bhbs force-pushed the chunk-importmap branch from ef5d053 to 9bed85b Compare September 19, 2024 14:04

sapphi-red self-requested a review October 16, 2024 10:44

sapphi-red added the p3-significant High priority enhancement (priority) label Oct 17, 2024

sapphi-red reviewed Oct 17, 2024

View reviewed changes

bhbs added 6 commits October 19, 2024 22:53

Merge branch 'main' into chunk-importmap

a0e94cc

docs: mv chunk importmap

bb63e50

refactor: remove redundant chunkName reference

eaca13c

refactor: use import.meta.resolve instead of homemade import map re…

5f898b3

…solver

refactor: use MagicString::replace instead of String::replace

553e503

refactor: mv replacement to before passing the filename to `toOutputF…

47ce953

…ilePathInJS`

sapphi-red reviewed Oct 22, 2024

View reviewed changes

Merge branch 'main' into chunk-importmap

a4740c6

montalvomiguelo mentioned this pull request Feb 16, 2025

Use bare modules with vite dev server slavafyi/vite-plugin-shopify-import-maps#18

Open

lemonmade mentioned this pull request Mar 15, 2025

Add import maps to avoid cache invalidation lemonmade/quilt#860

Open

Boshen mentioned this pull request Jun 20, 2025

[Feature Request]: chunk importmap rolldown/rolldown#5025

Closed

sapphi-red mentioned this pull request Feb 6, 2026

feat(build): chunk importmap #21580

Open

		@@ -519,6 +566,16 @@ function viteLegacyPlugin(options: Options = {}): Plugin[] {
		}
		}


		### 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.

	- Default: `false`
	- Default: `false`
	- Experimental

Uh oh!

Conversation

bhbs commented Apr 29, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Implementation

Others

Uh oh!

bolt-new-by-stackblitz Bot commented Apr 29, 2024

Uh oh!

olivierbeaulieu commented Jul 12, 2024

Uh oh!

Lgowen commented Aug 15, 2024

Uh oh!

paolostyle commented Sep 11, 2024

Uh oh!

C-Higgins commented Sep 18, 2024

Uh oh!

juanespinola05 commented Sep 19, 2024

Uh oh!

sapphi-red left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bhbs commented Oct 17, 2024

Uh oh!

bhbs commented Oct 21, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lansi951 commented Jan 18, 2025

Uh oh!

jonomuller commented Jan 30, 2025

Uh oh!

olivierbeaulieu commented Feb 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bhbs commented Feb 10, 2025

Uh oh!

jonomuller commented Feb 11, 2025

Uh oh!

bhbs commented Feb 23, 2025

bhbs commented Apr 29, 2024 •

edited

Loading

sapphi-red left a comment •

edited

Loading

olivierbeaulieu commented Feb 5, 2025 •

edited

Loading

bhbs commented Feb 23, 2025 •

edited

Loading