HTML Academy · Lesson

Import Maps importmap

Map bare module specifiers to URLs with importmap.

Import Maps importmap is a free HTML Academy lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the HTML Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

The Bare Specifier Problem

In Node, import "lodash" works because the resolver finds node_modules/lodash. Browsers do not have node_modules — they need a real URL. Without help, import "lodash" throws "Failed to resolve module specifier".

What Import Maps Do

An import map declares a JSON dictionary that maps bare specifiers (and URL prefixes) to real URLs. The browser consults the map at module resolution time, converting import "lodash" into a fetch from the URL you configured.

<script type="importmap">
{
  "imports": {
    "lodash": "https://esm.sh/lodash@4.17.21",
    "preact": "https://esm.sh/preact"
  }
}
</script>

Declaration Order Matters

The import map must appear before any <script type="module"> that uses bare specifiers — once a module has started resolving imports, the map is locked in. Place the <script type="importmap"> near the top of the <head>.

Prefix Mappings

Trailing-slash entries match URL prefixes: "@/": "/src/" maps any import "@/utils/sum.js" to /src/utils/sum.js. This is how you simulate the "alias" syntax that bundlers commonly support.

Versioning via Map

An import map centralizes version choices: change "react" from esm.sh/react@18 to esm.sh/react@19 in one place and every importing module picks up the new URL. Without an import map, every import site has its own version hard-coded.

Scopes

The scopes key allows different mappings for different parts of your site. Inside /admin/ you might want a newer version of a dependency than in /public/; scopes let you target by path.

{
  "imports": { "lodash": "https://esm.sh/lodash@4" },
  "scopes": {
    "/admin/": { "lodash": "https://esm.sh/lodash@5" }
  }
}

One Map Per Document

Each document can have at most one <script type="importmap">. Putting two on the same page is invalid; merge their content into a single block to combine entries.

External Import Maps

You can host the map at an external URL with <script type="importmap" src="map.json">. Browser support is newer than inline maps but is now widespread; useful when you want to cache a large map separately from the document.

Generating Import Maps

Tools like JSPM Generator and esbuild's --servedir mode produce import maps from package.json automatically. Generated maps include every transitive dependency, mapping each to a CDN URL — a node_modules-free workflow.

Browser Support

Import maps ship in Chrome, Edge, Safari and Firefox. Older browsers ignore the <script type="importmap"> tag, which means bare specifiers fail. For broad legacy support, build with a bundler that resolves the specifiers at build time and serve plain URLs.

Polyfill Option

The ES Module Shims polyfill (es-module-shims.js) adds import map support — and several newer features — to older browsers. Include it before your importmap script. Most modern projects skip the polyfill and rely on native support.

Knowledge Check

Why must an <script type="importmap"> appear before any module script that uses bare specifiers?

Summary

Import maps map bare specifiers and URL prefixes to real URLs, restoring node-style "import lodash" in the browser. Declare them once per document before any module script, optionally externally via src, with scopes for per-path overrides. Combine with a CDN (esm.sh, jsdelivr) for a node_modules-free workflow.

Frequently asked questions

Is the “Import Maps importmap” lesson free?

Yes — the full text of “Import Maps importmap” is free to read here on the web, and the HTML Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the HTML Academy course, upgrade to CoddyKit PRO.

What will I learn in “Import Maps importmap”?

Map bare module specifiers to URLs with importmap. You practise HTML Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start HTML Academy?

No prior experience is required. HTML Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Import Maps importmap” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this HTML Academy lesson?

Yes. Every HTML Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to HTML Academy