Import Maps & Browser-Native Module Resolution
Import Maps bind bare specifiers like "react" to hashed CDN URLs directly in HTML, isolating cache invalidation to the exact file that changed. Pair them with ES Module live bindings and modulepreload hints so the browser skips bundler manifests without waterfall latency.
Import Map Specifier Resolution & Scopes
Trace how the browser registers an import map, resolves scoped bare specifiers, and avoids waterfalls.
HTML parser ingests <script type='importmap'> into the document's module resolution table.
"imports": { "lit": "/cdn/lit.3.2.1.js" }- mapRegistered
- true
- globalEntries
- 2
- scopedEntries
- 1
Under the Hood
The HTML parser registers a single merged module map per document from <script type="importmap"> before any module script executes. When Blink's module loader encounters import { x } from "pkg", it resolves "pkg" against imports and scopes by longest-prefix match without network round-trips.
- Isolated Cache Busting: Updating
"date-fns"only rewrites its one hashed URL inside the inline import map, leaving every other vendor module cached. - Scoped Overrides: The
scopeskey maps a specific path prefix (e.g."/legacy/") to an older major version without polluting the global module graph. - Integrity Enforcement: Adding an
"integrity"dictionary inside the import map supplies SRI hashes for dynamically resolved ES modules.
<script type="importmap">
{
"imports": {
"lit": "/cdn/lit.3.2.1.js",
"@app/ui": "/assets/ui.8f2a1c.js"
},
"scopes": {
"/legacy/": { "lit": "/cdn/lit.2.8.0.js" }
}
}
</script>
<link rel="modulepreload" href="/cdn/lit.3.2.1.js" />Problem Genealogy
- 2014 (SystemJS & Runtime Loaders): Polyfilled module maps shipped 25-45 KB of loader JS and blocked execution until
fetch()waterfalls resolved every dependency. - 2018 (Webpack Chunk-Manifest Cascading): Bundlers rewrote every parent chunk hash whenever a leaf module changed, invalidating 150 KB+ vendor bundles on one-line fixes.
- 2023 (Baseline Import Maps): Native HTML resolution eliminated runtime loader JS and stabilized single-module cache keys across micro-frontends.
Production Pitfalls
- Deep Dependency Waterfalls: Without
<link rel="modulepreload">for transitive imports, Blink discovers leaf modules sequentially after parsing each parent, adding 3-5 RTTs to LCP. - Late Map Injection: Inserting a
<script type="importmap">after any<script type="module">has already started throws or gets ignored in strict engine order.
- When not to use unbundled Import Maps: Do not serve 500+ tiny raw
.jssource files over HTTP without bundling ormodulepreload; HTTP/2 header overhead and per-file compression losses outweigh cache-key isolation.
Connections & Logical Next Steps
Import Maps map bare specifiers onto ES Module graph URLs while preserving live read-only bindings.
Nested import-map subgraphs still require modulepreload links so the preload scanner fetches deep dependencies early.