What are import maps?

ES modules with direct URLs have been around for a while, allowing us to write code like:

import { something } from 'https://cdn.example.com/packages/module/v1.2.3/index.js';

Import maps provide a level of indirection between module specifiers and the actual URL where the module resides. They’re a simple JSON structure that maps from import specifiers to URLs:

<script type="importmap">
{
  "imports": {
    "react": "https://esm.sh/react@18.2.0",
    "react-dom": "https://esm.sh/react-dom@18.2.0",
    "lib/": "https://cdn.skypack.dev/lib@1.2.3/"
  }
}
</script>

With this map in place, our application code can now use clean, maintainable imports:

import React from 'react';
import ReactDOM from 'react-dom';
import { helper } from 'lib/helper.js';

The browser uses the import map to resolve these imports to their actual URLs at runtime. No bundler required!

Why this matters now

Import maps aren’t new, and thye’ve been in the works for years. What’s changed is that they’re finally supported across all major browsers. Chrome added support back in version 89, Firefox implemented them in version 108, and Safari finally joined the party in version 16.4, released earlier this year.

This cross-browser support means we can start using import maps in production without fallbacks or polyfills.

The current state of JavaScript module management

The reality is, despite the browser support for ES modules, the vast majority of web projects today still rely on bundlers like webpack, Rollup, Vite, esbuild, or Parcel. This is for good reasons:

  • Performance optimization through bundling and minification
  • Transpilation for wider browser support
  • Tree-shaking to eliminate unused code
  • Support for non-JavaScript assets like CSS, images, and more
  • Development conveniences like hot module replacement

Most developers aren’t writing direct ES module imports in production code. Instead, we use package managers like npm or yarn, and let bundlers handle the module resolution and optimization.

So where do import maps fit in this ecosystem? They’re not a replacement for bundlers in most large-scale applications, but they do open up interesting possibilities for specific use cases.

The strength of import maps

1. Versioning and dependency management

With import maps, updating a dependency becomes a one-line change:

- "react": "https://esm.sh/react@18.1.0"
+ "react": "https://esm.sh/react@18.2.0"

Every module that imports ‘react’ will now use the new version. No need to search and replace across your codebase.

2. Progressive enhancement without bundling

Import maps enable sophisticated caching strategies without bundling. This is particularly valuable for progressive enhancement approaches where you want core functionality to work without JavaScript, but enhance the experience when it’s available.

For example, you can serve the minimal JavaScript needed for core functionality, then use import maps to lazily load enhanced features only when they’re needed.

This might warrant a brief post experimenting the pattern if this became more prevalent

3. Development/production switching

// Development importmap
{
  "imports": {
    "app/": "/src/",
    "react": "https://esm.sh/react@18.2.0?dev"
  }
}

// Production importmap
{
  "imports": {
    "app/": "/dist/",
    "react": "https://esm.sh/react@18.2.0"
  }
}

4. Reducing the “hidden magic” in projects

Modern JavaScript development often involves a lot of “magic” happening under the hood with imports. Tools like webpack, Vite, and others transform imports in ways that are invisible in the source code.

Import maps make the mapping explicitand you can see exactly what URL a module resolves to by checking the import map.

Use cases

Here are some patterns where import maps offer unique advantages:

Micro-frontends without the complexity

Import maps are ideal for micro-frontend architectures. Each team can develop their components independently, and the shell application can use an import map to stitch everything together.

<script type="importmap">
{
  "imports": {
    "shell/": "/shell/",
    "team-a/": "https://team-a-app.example.com/modules/",
    "team-b/": "https://team-b-app.example.com/modules/"
  }
}
</script>

Dependency sharing in multi-page applications

For multi-page applications, import maps ensure consistent dependency versions across pages without bundling everything together:

<!-- shared-deps.html (included in every page) -->
<script type="importmap">
{
  "imports": {
    "react": "https://esm.sh/react@18.2.0",
    "react-dom": "https://esm.sh/react-dom@18.2.0",
    "utils/": "/shared/utils/"
  }
}
</script>

This pattern also gives you the benefits of code-splitting without the complexity of a bundler’s configuration.

Versioned deployments

When deploying new versions of an application, you can include a version hash in your module paths:

<script type="importmap">
{
  "imports": {
    "app/": "/dist/a7f3bc9/"
  }
}
</script>

This ensures clean cache invalidation when deploying changes.

The limitations and trade-offs

Import maps aren’t a silver bullet, and there are valid concerns:

  1. Dependency management complexity: Import maps shift some dependency management responsibility from your build tools to your application code, which can introduce its own complexities.

  2. Performance considerations: Unbundled ESM imports mean more HTTP requests, which can impact performance despite HTTP/2 and HTTP/3 improvements. For large applications, bundling still offers performance advantages.

  3. Limited to browser environments: Import maps are a browser feature, meaning different module resolution strategies between browser and Node.js environments.

  4. No tree-shaking: Automatic tree-shaking and dead code elimination are still bundler’s league.

Conclusion

Import maps represent a significant step toward a more mature module ecosystem in the browser. They bridge the gap between Node.js-style bare imports and URL-based ES modules, providing flexibility without requiring bundlers.

While they won’t replace bundlers for most production applications. Particularly large ones, where performance is critical. They offer new possibilities for development workflows, simpler deployment strategies, and more transparent dependency management.

The reality is that bundlers will continue to dominate the JavaScript ecosystem for the foreseeable future. However, now that we have cross-browser support for import maps, they become a viable alternative for specific use cases and smaller projects where simplicity is valued over optimization.

From building a small site that could benefit from the simplicity of direct ES modules, or exploring micro-frontend architectures, or just wanting to better understand the module ecosystem. Import maps give developers more options, and that’s always a good thing. They allow us to be more intentional about when and how we use bundlers, rather than reaching for them by default for every project.