阅读中文版本

Import Maps for Module Resolution

An import map is a JSON declaration that tells the browser how to resolve module specifiers, enabling bare package names and versioned URLs without a bundler.

Definition

An import map is a script of type importmap whose JSON body maps module specifiers used in imports to concrete URLs, letting the browser resolve bare names and remap paths.

It is used to run un-bundled modules in the browser, to swap implementations in tests, and to centralise dependency versions. Compared to simpler alternatives, this concept fits best when the trade-off it represents is the one the system actually cares about.

When to use it

A common use case is applying it at the boundary where the cost of getting it wrong is highest, and the scenario usually involves a concrete guarantee the system must uphold. Unlike an ad hoc approach, it makes that guarantee explicit, reviewable, and testable.

How it works

The map must appear before the first module load, and browsers allow only a single import map per document, so it belongs early in the head.

Trailing slashes distinguish prefix mappings from exact specifier mappings; a prefix mapping rewrites any specifier that begins with the key plus a slash.

Trade-offs and alternatives

The mechanism resolves URLs only and cannot polyfill module semantics, so it works alongside strict Content Security Policy rather than replacing a build step for older browsers. The main drawback is the extra complexity it introduces, so the benefit should clearly outweigh that cost before a team adopts it.

Common misconceptions

A persistent misconception is that import maps can be added after modules have started loading. Another is that an import map rewrites the contents of a module file. For example, an engineer who assumes otherwise may design around a guarantee that does not actually exist, which only becomes obvious under load or failure.

Anti-patterns to avoid

Two recurring anti-patterns are to declaring multiple import maps or adding one late and to mapping a specifier prefix without the required trailing slash. Both tend to surface as hard-to-debug production issues rather than obvious test failures. Related concepts include CSS Cascade Layers, CSS Container Queries, Third-Party Cookies and Storage Partitioning.