Blog | Why Not to Rely on Import Maps for ...

Setting the Stage: Import Maps in the Modern Stack

Import maps arrived as a browser‑native solution for managing module specifiers without a bundler. The promise—declare a single JSON file, point every <script type="module"> to a stable URL, and let the browser handle the rest. For tiny demos or low‑traffic microsites the approach feels elegant, but when the same technique is stretched across a monolithic codebase with hundreds of entry points, the hidden costs surface quickly.

The Allure That Turns Into a Liability

At first glance, import maps appear to solve two classic problems:

Eliminate the need for a build step that rewrites paths.
Provide a single source of truth for CDN‑hosted assets.

The temptation is strong, especially for teams eager to drop Webpack or Vite from their CI pipeline. However, the simplicity is deceptive. Below we expose three concrete failure modes that arise once the application exceeds a modest size.

// example import‑map.json used in many tutorials
{
  "imports": {
    "react": "https://cdn.jsdelivr.net/npm/react@18/umd/react.production.min.js",
    "react-dom": "https://cdn.jsdelivr.net/npm/react-dom@18/umd/react-dom.production.min.js",
    "@my-org/ui": "/static/ui/v2/index.js"
  }
}

Notice the mix of absolute CDN URLs and relative paths. As the application grows, each new team adds its own entries, leading to a sprawling map that quickly becomes a single point of failure.

Failure Mode #1: Cache Invalidation Chaos

Browsers cache each URL independently. When a minor patch updates only @my-org/ui, the import map must be refreshed, yet the underlying CDN‑hosted React bundle remains untouched. Without a cache‑busting strategy, users may receive a stale React version alongside a fresh UI bundle, causing subtle runtime errors that are hard to reproduce.

// naive cache‑busting attempt – appending a query string
{
  "imports": {
    "@my-org/ui": "/static/ui/v2/index.js?v=20240601"
  }
}

The query‑string approach works for the entry it touches, but every dependent module still points to the original URL. A full‑page reload does not guarantee that all modules share a coherent version set. The result is a “version skew” bug that surfaces only under heavy traffic or after a CDN purge.

Failure Mode #2: Network Overhead and Parallel Requests

Import maps do not bundle; each specifier results in an individual HTTP request. In a large‑scale portal with 150 distinct modules, the initial load can trigger dozens of parallel fetches. Even with HTTP/2 multiplexing, the handshake latency adds up, inflating Time‑to‑Interactive (TTI) dramatically on high‑latency mobile networks.

// network waterfall snapshot (simplified)
GET https://cdn.example.com/react.min.js          120 ms
GET https://cdn.example.com/react-dom.min.js      115 ms
GET /static/ui/v2/componentA.js                    90 ms
GET /static/ui/v2/componentB.js                    85 ms
...

Bundlers solve this by concatenating modules into a few optimized chunks, allowing the browser to download a single, cache‑friendly asset. Import maps, by design, cannot provide that level of consolidation.

Failure Mode #3: Lack of Tree‑Shaking and Dead‑Code Elimination

Because each module is fetched as‑is, unused exports travel over the wire anyway. A component library that ships 200 icons will deliver all of them even if a page uses only five. This bloat is especially problematic for progressive web apps (PWAs) that aim to stay under 1 MB for first‑load performance.

// icon library entry point
export * from "./icons/alert.js";
export * from "./icons/check.js";
// … 200 more exports

A bundler with proper tree‑shaking would prune the unused icons during the build, reducing payload size by orders of magnitude. Import maps leave that optimization to the developer, who must manually curate the list—a maintenance nightmare.

Alternative Blueprint: Module Federation with Dynamic Imports

To retain the runtime flexibility of import maps while addressing their shortcomings, many enterprises have turned to Webpack’s Module Federation (or its Vite/Parcel equivalents). Federation lets each team publish a remote entry point that the host application consumes at runtime, but it also supports version negotiation, shared dependency deduplication, and automatic chunking.

// host webpack.config.js
module.exports = {
  // ...
  plugins: [
    new ModuleFederationPlugin({
      name: "host",
      remotes: {
        ui: "ui@https://cdn.example.com/ui/remoteEntry.js"
      },
      shared: {
        react: { singleton: true, requiredVersion: "^18.0.0" },
        "react-dom": { singleton: true, requiredVersion: "^18.0.0" }
      }
    })
  ]
};

The remote application (the UI team) exposes only the modules it wants to share:

// ui/webpack.config.js
module.exports = {
  // ...
  plugins: [
    new ModuleFederationPlugin({
      name: "ui",
      filename: "remoteEntry.js",
      exposes: {
        "./Button": "./src/components/Button.jsx",
        "./Modal": "./src/components/Modal.jsx"
      },
      shared: ["react", "react-dom"]
    })
  ]
};

Consumers load these modules with a standard dynamic import() call, preserving the lazy‑loading benefits of native ES modules while allowing the build system to bundle, minify, and tree‑shake each remote.

// host application consuming a federated component
import React from "react";

const RemoteButton = React.lazy(() => import("ui/Button"));

function Dashboard() {
  return (
    <React.Suspense fallback={<div>Loading…</div>}>
      <RemoteButton />
    </React.Suspense>
  );
}

Step‑by‑Step Migration Guide

Below is a concise tutorial that walks you through converting an existing import‑map‑driven page into a federated architecture. The example assumes a repository layout where /frontend houses the host and /ui holds the remote component library.

# 1. Install required packages
cd frontend
npm i webpack@5 webpack-cli@4 module-federation-plugin@latest --save-dev

cd ../ui
npm i webpack@5 webpack-cli@4 module-federation-plugin@latest --save-dev

2. Create a shared webpack.common.js in both projects to keep React versions aligned:

// webpack.common.js (shared)
module.exports = {
  resolve: {
    extensions: [".js", ".jsx"]
  },
  module: {
    rules: [
      {
        test: /\.[jt]sx?$/,
        use: "babel-loader",
        exclude: /node_modules/
      }
    ]
  }
};

3. Configure the host’s webpack.prod.js to consume the remote:

// host/webpack.prod.js
const { merge } = require("webpack-merge");
const common = require("./webpack.common");
const { ModuleFederationPlugin } = require("webpack").container;

module.exports = merge(common, {
  mode: "production",
  plugins: [
    new ModuleFederationPlugin({
      name: "host",
      remotes: {
        ui: "ui@https://cdn.example.com/ui/remoteEntry.js"
      },
      shared: {
        react: { singleton: true, eager: true },
        "react-dom": { singleton: true, eager: true }
      }
    })
  ],
  output: {
    publicPath: "auto"
  }
});

4. Build and publish the remote. The UI team runs:

# ui/webpack.prod.js (excerpt)
plugins: [
  new ModuleFederationPlugin({
    name: "ui",
    filename: "remoteEntry.js",
    exposes: {
      "./Button": "./src/components/Button.jsx",
      "./Modal": "./src/components/Modal.jsx"
    },
    shared: ["react", "react-dom"]
  })
],
output: {
  publicPath: "https://cdn.example.com/ui/"
}

After npm run build, the remoteEntry.js file is uploaded to the CDN. The host now references it via the federation config, and the browser

♥ Enjoyed this article? Use the like banner at the top of the page to let us know — you can like it more than once! Each additional like from the same reader carries a little less weight than the first, so our appreciation scores reflect genuine enthusiasm rather than accidental clicks. Your feedback helps us understand which topics resonate most.

Why Not to Rely on Import Maps for Large‑Scale Enterprise Frontends