Import Maps
debt(d7/e3/b5/t7)
Closest to 'only careful code review or runtime testing' (d7). The term's detection_hints indicate no automated tooling (`automated: no`), and the common mistake about declaration order (import map must come before module scripts) won't be caught by linters or compilers—only discovered through runtime testing or careful review.
Closest to 'simple parameterised fix' (e3). The quick_fix is straightforward: reorder script tags, swap CDN URLs to ESM-compatible sources, and update the import map declaration. These are contained changes within the HTML/module setup, not cross-cutting refactors.
Closest to 'persistent productivity tax' (b5). Import maps affect how all module resolution works in the web context (`applies_to: web`). Teams must decide on CDN sources, maintain the import map as dependencies change, and coordinate across projects if shared. It's not load-bearing enough for b7 (not every change is shaped by it), but it does slow down work streams that touch module dependencies.
Closest to 'serious trap' (t7). The misconception explicitly warns that import maps replace bundlers—a significant wrong mental model—and common mistakes reveal contradictions: developers expect CommonJS CDN URLs to work, or expect Node.js support (where import maps don't apply). These represent serious gotchas that contradict how similar module concepts work in other environments.
TL;DR
Explanation
Import maps (<script type='importmap'>) define a JSON mapping of bare specifiers to URLs. Without a bundler: import 'lodash' resolves to 'https://cdn.jsdelivr.net/npm/lodash@4.17.21/+esm'. This enables CDN-based ES module development without npm/bundler. Also supports scopes for version-specific imports in nested dependencies. Import maps must be declared before any module scripts. Fully supported in Chrome 89+, Firefox 108+, Safari 16.4+. Use esm.sh or skypack for CDN-hosted ES modules.
Common Misconception
Why It Matters
Common Mistakes
- Declaring import map after module scripts — must come first.
- Using CommonJS CDN URLs — import maps need ES module (ESM) URLs.
- Expecting import maps to work in Node.js — they're a browser feature (Node has its own resolution).
Code Examples
<!-- Before import maps: requires bundler for bare specifiers -->
<script>
import lodash from 'lodash'; // Fails in browser
</script><script type="importmap">
{
"imports": {
"lodash": "https://cdn.jsdelivr.net/npm/lodash@4.17.21/+esm",
"react": "https://esm.sh/react@18",
"react-dom/client": "https://esm.sh/react-dom@18/client"
}
}
</script>
<script type="module">
import _ from 'lodash'; // Works!
</script>