Import maps

An import map is a JSON block in an HTML page that tells the browser which URL to load for each module name used in import statements.

Browsers can load ES modules natively, but they only understand URLs. A line such as import { html } from 'lit' uses a bare specifier, and without help the browser does not know where lit lives. An import map supplies that mapping. It is a browser standard, and all current major browsers support it.

Example

<script type="importmap">
{
  "imports": {
    "lit": "https://cdn.example.com/lit/index.js",
    "orders-app": "https://cdn.example.com/orders/main.js"
  }
}
</script>
<script type="module">
  import('orders-app');
</script>

Changing the URL for orders-app in the map changes which version every importer receives. No application has to be rebuilt. For this reason import maps are a building block of many single-spa setups and of Native Federation, which generates the map at runtime from the metadata of each remote.

Common misunderstanding

An import map only translates names to URLs. It does not bundle code, download it ahead of time or negotiate versions. If two applications need different major versions of the same library, you have to express that yourself with scopes, a section of the map that applies a different mapping to modules loaded from a given path.

The map also has to be in place before the modules that depend on it are loaded, so its position in the page matters.

Treat the import map as production configuration. One wrong line can break every micro-frontend on the page, so generate it in the pipeline and validate it before publishing. The micro-frontends page shows where it sits in a platform.

Related terms

• Native Federation
• single-spa
• Remote entry and manifest