Import Map
Definition
Browsers can load ES modules natively, but they only understand imports that point at a URL — a relative path or an absolute one. A statement such as import React from react means nothing to them, because there is no node_modules folder to look in. An import map fixes that. It is a script tag with the type attribute set to importmap, containing JSON whose imports object maps bare specifiers to real URLs, usually on a CDN. Once that map is in the document, every module the page loads can use the short name and the browser rewrites it. Import maps are supported in current versions of all major browsers; older ones ignore the tag and the imports fail.
Why It Matters
This is the piece that lets a generated page look like a modern codebase while still being one file you can upload. Without it, every import in the page has to carry a long versioned CDN URL, repeated in each module, and changing a version means a find-and-replace across the file. With it, the version lives in one place. It also keeps the code portable: paste the same modules into a real project with a bundler and they resolve without edits. The cost is discipline — the map is not validated, so a typo in a URL produces a failed network request and a blank page with one console error, not a build error you would have caught earlier.
How It Works
The import map must appear before the first module script that depends on it, and a document may contain only one. Inside, imports holds exact names, and a trailing slash entry acts as a prefix rule, so mapping a package name plus slash lets deep imports resolve too. A scopes object can override a mapping for modules loaded from a particular path, which is how two versions of the same library can coexist. The browser resolves each specifier once, then fetches the module over HTTP, and the server must send it with a JavaScript MIME type or the browser refuses to execute it. Because the map is inline HTML, a static host such as 99helpers serves it as part of the file and never has to understand it.
Real-World Example
A data analyst publishes a chart viewer at sales-charts.99helpers.site. The page maps three bare names — a charting library, a date helper and a small utility — to pinned jsdelivr URLs in a six-line import map, then imports them by name in a module script. When the charting library releases a breaking change, the fix is one URL in one place rather than eleven import statements scattered through the file.
Common Mistakes
- ✕Placing the import map after the module script that needs it — the browser has already tried to resolve the specifier and failed
- ✕Adding a second import map to the same document, which is ignored, leaving half the names unresolved
- ✕Mapping a bare name without the matching trailing-slash entry, so deep imports into that package still fail
- ✕Pointing at a CDN path that serves the CommonJS build — an ES module import of it will throw on the first named export
Related Terms
ES Module
JavaScript's built-in module format, using import and export statements. Browsers load ES modules natively from a script tag with type set to module, with no bundler involved.
React via CDN
Running React by loading it from script tags on a public CDN rather than installing it and bundling it. It lets a single HTML file render a React app with no npm, no bundler and no compile step.
Inline JavaScript
JavaScript written inside the HTML document — in a script element with no src attribute, or in an attribute such as onclick — rather than loaded from a .js file. It keeps a generated page to one file.
CDN
A content delivery network: a set of servers spread across the world that keep copies of your files and answer each visitor from somewhere close to them. It is the service; the machines it runs on are its edge network.
Asset Bundling
Asset bundling combines many source files into a few output files before a site is published. Dozens of JavaScript modules become one or two scripts; several stylesheets become one.
Put a file online in seconds
Drop in a document, an image, a page or a whole static website and share the link — free, with no build step and no server to set up.
Host a file free →