Import Maps: Browser Support, Modules, Limitations

What are import maps?

Import maps are a WHATWG HTML feature that ship a JSON object inside a script type=importmap tag. The browser uses that JSON to remap bare module specifiers, path prefixes, and per-scope overrides for every import statement and dynamic import call on the page.

Which browsers does import maps support?

Every current Chromium, Gecko, and WebKit release supports import maps, with global support around 95%. Chrome, Edge, Firefox, Safari, Opera, and Samsung Internet all ship the feature on by default, and Internet Explorer never added support.

What are the key features of import maps?

Import maps pack a small but powerful module-resolution layer into one JSON object. The headline features cover bare specifiers, path remapping, scoped overrides, integrity hashes, and merged maps.

• Bare module specifiers: The imports key maps a bare name such as lodash or react to a full URL, so import lodash from "lodash" works in the browser without a bundler.
• Path prefix remapping: An imports key that ends in a slash maps an entire directory tree, so "components/" can point at "/static/v3/components/" and pick up every nested file in one rule.
• Scoped maps: The scopes key applies a different mapping to imports made from a specific URL prefix, so a third-party widget can pin its own version of lodash without breaking the host page.
• Integrity metadata: The integrity key maps a resolved URL to a Subresource Integrity hash, and the browser refuses any module whose hash does not match. Chrome 127+, Firefox 138+, and Safari 18.4+ honor the key.
• Merged import maps: A page may declare more than one script type=importmap tag, and the browser merges them in document order before any module loads.
• Dependency pinning: A single edit to the import map URL swaps every consumer of a dependency to the new version, with no rebuild and no cache-busting trickery on the source files.
• Feature detection: HTMLScriptElement.supports("importmap") returns true on every browser that parses the tag, and false everywhere else, so a page can fall back to es-module-shims at runtime.

How do you check if a browser supports import maps?

Run a one-line feature check in the DevTools console. The browser exposes an HTMLScriptElement.supports static method that returns true for "importmap" on every browser that honors the tag.

• Open DevTools: Right-click any page, choose Inspect, and switch to the Console tab.
• Paste the feature-detection snippet: Copy the snippet below and paste it into the console.
• Run the detection: Press Enter. The console prints whether import maps are supported and appends a sample importmap tag to the document head.
• Confirm the bare specifier works: Run import("lodash").then(m => console.log(typeof m.default)) and watch the network panel for the resolved URL.

// Paste this into the DevTools console to confirm import map support.
if (typeof HTMLScriptElement !== "undefined" &&
    typeof HTMLScriptElement.supports === "function" &&
    HTMLScriptElement.supports("importmap")) {
  console.log("Import maps are supported in this browser.");

  const map = document.createElement("script");
  map.type = "importmap";
  map.textContent = JSON.stringify({
    imports: { "lodash": "https://cdn.jsdelivr.net/npm/lodash-es@4/lodash.js" }
  });
  document.head.appendChild(map);
  console.log("Inline import map appended for the lodash bare specifier.");
} else {
  console.log("Import maps are not supported in this browser.");
}

If the console prints "Import maps are not supported in this browser", load the es-module-shims polyfill before any module imports. Chromium, Gecko, and WebKit current releases all log a positive result.

What are the known issues with import maps?

Import maps ship in every modern browser, but a small set of cross-browser limits still bite real projects. The common pain points are tag ordering, worker scope, single-map limits, integrity-key gaps, and Safari's late arrival.

• Tag ordering matters: The script type=importmap tag must parse before the first module import. A tag placed below the first module load is silently ignored, and the browser falls back to bare-specifier errors.
• One merged map per page: Browsers fold multiple import map tags into a single map, but every tag must declare before the first import. Chrome and Firefox warn in the console when a later tag is dropped.
• Workers and worklets ignore the map: The HTML spec scopes import map resolution to the Window global, so a Worker, ServiceWorker, or AudioWorklet that imports a bare specifier still throws. The matching worker proposal is in draft.
• Integrity key still rolling out: The integrity key landed in Chrome 127, Firefox 138, and Safari 18.4. Older releases ignore the key without a parse error, so a polyfill is needed when SRI on bare specifiers is mandatory.
• Safari was the last engine to ship: Safari only added import maps in 16.4. Pages that need to support iOS 15 or earlier still need es-module-shims or a bundler fallback for those visitors.
• No nested import maps inside shadow DOM: A custom element cannot scope its own import map. Every component on the page reads from the same merged map, so two components that need different versions of the same dependency need scopes URL prefixes instead.
• Forbidden script attributes: The script type=importmap tag rejects src, async, defer, nomodule, crossorigin, integrity, and referrerpolicy attributes. The map JSON must live inline, which rules out a CDN-hosted import map file in current browsers.

In my experience, the trickiest production failure is the silent drop on a late tag. A build pipeline that injects the import map after the first inline module fails on Safari and Firefox, while Chrome warns but still resolves, so a green local test masks a broken iOS deploy. Always render the import map inside the document head before any other script tag.

Citations

All import maps version numbers and platform notes in this guide come from these primary sources:

• WHATWG HTML Standard - Import maps: html.spec.whatwg.org/multipage/webappapis.html#import-maps
• MDN Web Docs - script type=importmap: developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap
• MDN Web Docs - Importing modules using import maps: developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules
• web.dev - Import maps in all modern browsers: web.dev/blog/import-maps-in-all-modern-browsers
• Chrome Platform Status - Import maps: chromestatus.com/feature/5315286962012160
• Chrome for Developers - Import maps integrity: developer.chrome.com/blog/import-maps-integrity
• WebKit blog - Release notes for Safari 16.4: webkit.org/blog/13966/webkit-features-in-safari-16-4
• Mozilla SpiderMonkey blog - JavaScript Import maps Part 1: spidermonkey.dev/blog/2023/02/23/javascript-import-maps-part-1-introduction
• Bugzilla@Mozilla - Implement Import Maps: bugzilla.mozilla.org/show_bug.cgi?id=1688879
• WICG - Import maps proposal repository: github.com/WICG/import-maps
• es-module-shims - Polyfill for import maps: github.com/guybedford/es-module-shims
• Wikipedia - JavaScript modules: en.wikipedia.org/wiki/JavaScript#Modules