Stabilizing build.chunkImportMap

[sapphi-red]

build.chunkImportMap

• Added in vite@8.1.0
• Rationale: to solve the cascading cache invalidation
• PR
• Docs

We're opening a discussion to gather feedback about this feature.

[btea]

Even if the chunkImportMap configuration is enabled, if a chunk is not referenced or is imported via a script tag, can the corresponding imports information be deleted? 🤔

[sapphi-red]

I'm not sure about the exact scenario. Would you elaborate it?

[btea]

For a simple example, when you initialize a project using `pnpm create vue`, the import map information after building is as shown in the image, but this information is not useful at this point.

[sapphi-red]

I see. I think the difficult point to achieve that is to detect whether the importmap is actually not used. If the chunk contained import.meta.resolve(something), it's hard to know if something can be /assets/index-hash.js.

[timofei-sake]

Hi @sapphi-red,

I'm having following issue, in my understanding it is more on rolldown side including empty chunks in map.

1. A .scss imported by 2+ lazy chunks, becomes a shared chunk. After CSS extraction its JS body is empty → a pure-CSS chunk.
2. Rolldown's plugin still emits an import-map entry dsc-DNFHMQ0v.js → dsc-Dmc5PRar.js and rewrites the importers to use it.
3. Vite then deletes that pure-CSS JS chunk — only the .css is written.
4. The import map (and the rewritten import) now point to a .js that was never written → 500 / "Failed to fetch dynamically imported module."

Is this behavior expected/known for now?

[sapphi-red]

It might be related to #22740

[webJose]

Hello!

I'm the author of the popular vite-plugin-single-spa, and while I did have issues with single-spa creator (may he rest in peace), I will never deny that single-spa is, in my opinion, one of the best micro-frontend solutions.

Because of my differences and my professional need, I decided I needed to create a new micro-frontends library that was more focused and was more versatile. Enter CollageJS.

Specifically, I have split my vite-plugin-single-spa plug-in into 2 plug-ins: @collagejs/vite-im and @collagejs/vite-css. The one relating to import maps is the first one ("im" stands for "import map").

The IM plug-in is given a user-defined import map, and the plug-in injects it to the top of HEAD along with an IIFE in the @collagejs/imo NPM package. "IMO" stands for "Import Map Override", and is my version of single-spa's import-map-overrides NPM package.

I have just tested this feature in a simple test project, and it looks good, but I wonder: Are there any ways to programmatically access or modify the generated import map for the chunks? I don't have a use case right now. I am just trying to learn about what Vite does and offers just in case I can leverage it or need to battle some edge case. I read the documentation that explains this feature, but other than "it's there, it does this because of this motivation", there's nothing else.

[sapphi-red]

There's a guide to access the information.
https://vite.dev/guide/api-plugin#chunk-import-map-information

[webJose]

Thanks for the extra lin, @sapphi-red . This is very helpful.

I think I can give you some feedback, based on my own knowledge of import maps and how Vite works (before this feature). I think it is important to mention it to make sure the Vite team is accounting for these.

I would like to start by mentioning that the import map specification allows for multiple import maps. Browsers are meant to merge them. It would be nice, then, if Vite could allow the insertion or more than one import map (more than one script tag). I guess it would be nice if there could be a way to push more import maps. Seeing that the currently generated import map is part of the bundle, is emit() a way to go? I am guessing No, because these are not really chunks that lie in the file system, but JSON files whose content needs to be inserted in the HTML as script tags, so my guess is that Vite will require additional logic to accomplish this.

Second: Import maps can only be specified before the first JavaScript module executes. This is of particular importance while in "serve" mode. Vite inserts into the HEAD element the /@vite/client script. If an import map is inserted in HEAD after this script, it is ignored by the browser. All import map scripts must be declared before any JavaScript.

Finally, a request: As I explained, both single-spa and CollageJS allow developers the ability to override import map entries. This is very handy for development, as we can debug or develop micro-frontends on deployed environments, reducing the need of development servers. The trick in overrriding depends on the ability to insert the import map with a type different than "importmap" (the one specified in the standard). Both single-spa and CollageJS inject import maps using the "overridable-importmap" type. Then the entry-overriding script runs and generates the true import map script tag with the correct type, after applying the overrides.

So the request would require, if at all possible, that:

1. Each inserted import map could have its script type specified.
2. Vite could provide the ability to insert custom tags immediately after the import map script tags.

If these were features of Vite, it would simplify the work done by import-map-overrides (if it ever gets updated again), @collagejs/imo and any other Vite plug-in that deals with import maps.

---

I don't know how much of this is already accounted for in Vite. Apologies if I'm mentioning things that are already covered.

Thank you!

[sapphi-red]

I don't think those are directly related to this new feature.

[sapphi-red]

This feature doesn't affect the behavior in dev and only adds the importmap during build. If I understand correctly, you're referring to the dev behavior.

[webJose]

It's OK if you don't find the feedback useful. No worries.

I'll just clarify that even though serve mode does have a specific annoyance, the simple fact of adding one import map, be it in serve or build mode, must attempt to go as up in the HEAD element as possible. If, for example, a project adds a script to the HEAD element, the Vite-generated import map needs to go BEFORE said script, or the browser will ignore the import map and the application will not work.

[liuzwZYW]

When used with experimental.renderBuiltUrl, can try dynamically injecting an import map:

const toCdnUrl = (url) => `map2Cdn`;
const importmapScript = document.createElement('script');
importmapScript.type = 'importmap';
const importmap = {
 'xxx.js': toCdnUrl('xxx-1.js')
}
importmapScript.textContent = \`{ "imports": ${JSON.stringify(importmap)} }\`;
document.currentScript.after(importmapScript);

[liuzwZYW]

If possible, provide a Vite configuration option to disable automatic injection into index.html, allowing a custom plugin to read importmap.json and handle the injection during the generateBundle hook.

// vite.config.js

build: {
    chunkImportMap: true,
    chunkImportMapRenderToIndexHtml: false
}