Micro-Frontend Architecture & Federation Guide

Import Maps for Native Module Loading #

Import maps shift module resolution from build-time bundlers to the browser’s native ES module loader, enabling lightweight, zero-runtime-overhead micro-frontend architectures. This guide details configuration syntax, dynamic injection patterns, and production deployment strategies for enterprise-scale applications.

Key Implementation Points:

Setup & Configuration #

Construct a valid JSON import map that maps bare specifiers to absolute CDN paths with immutable version hashes. Unlike traditional bundler configurations, import maps operate entirely at the browser level, meaning resolution logic must be explicitly defined before the module graph is parsed. Align your dependency resolution strategy with patterns previously handled during Configuring Webpack Module Federation to ensure consistent shared library behavior across host and remote boundaries.

Inject the map synchronously in the <head> before any <script type="module"> execution. The browser parses import maps exactly once during the initial document parsing phase; asynchronous or deferred injection will result in resolution race conditions and unhandled TypeError exceptions.

Integration Patterns #

Wire import maps into host shells by implementing a centralized registry service that aggregates remote manifest versions and pushes consolidated maps to the client. For hot-swappable remotes, use document.createElement('script') with type="importmap" to inject updated mappings at runtime. However, native browser implementations only apply maps parsed before the first module import. To achieve true runtime overrides, pair dynamic injection with a shim-based loader.

Contrast this approach with plugin-driven architectures like Setting Up Vite with Federation Plugins to evaluate bundle size reductions and simplified CI/CD pipelines. Native resolution removes the need for complex runtime chunk extraction, allowing the browser to fetch only the exact modules required by the current route.

Edge Cases & Failure Modes #

Enterprise deployments must address CORS restrictions, cache invalidation bottlenecks, and duplicate dependency instantiation. Enforce strict Access-Control-Allow-Origin headers on all module endpoints. ES modules require successful CORS preflight checks; missing headers trigger opaque fetch failures that bypass standard JavaScript error boundaries and silently break remote execution.

Prevent duplicate module instantiation by ensuring all remotes reference identical versioned paths in the shared map. If different remotes map the same bare specifier to divergent URLs, the browser loads separate instances, breaking singleton patterns (e.g., React context, Redux stores) and increasing memory footprint. When native resolution fails due to network partitioning or malformed maps, implement fallback routing and graceful degradation strategies outlined in Using import maps as a lightweight federation alternative.

Testing & Validation #

Establish CI/CD verification pipelines to validate map integrity, analyze network waterfalls, and automate resolution mocking. Use window.importShim or es-module-shims in test runners to simulate native resolution without triggering actual network calls. This enables deterministic unit testing of module resolution logic across isolated environments.

Validate module load order and dependency tree consistency against baseline Webpack & Vite Module Federation Implementation benchmarks to ensure parity in initial load times and time-to-interactive metrics. Implement Subresource Integrity (SRI) checks on all mapped URLs to detect corrupted or tampered module payloads before execution.

Deployment Strategy #

Configure CDN distribution with Cache-Control: no-cache, must-revalidate to guarantee clients always fetch the latest version mapping. Import maps act as routing tables; serving stale maps forces browsers to resolve deprecated module paths, causing cascading runtime failures across distributed remotes.

Utilize atomic deployment techniques: host the new map at a versioned URL, update the shell reference, and purge CDN caches simultaneously. This prevents partial deployments where the host references a new map but remotes still serve legacy payloads. Instrument window.addEventListener('error') and performance.getEntriesByType('resource') to track 404s and latency spikes for unmapped or slow modules, feeding telemetry into your observability stack.

Code Examples #

Static Import Map with Immutable Versioned Paths #

<script type="importmap">
{
 "imports": {
 "@company/ui-core": "https://cdn.example.com/libs/ui-core/1.4.2/index.js",
 "@company/auth": "https://cdn.example.com/libs/auth/2.1.0/index.js",
 "lodash-es": "https://cdn.example.com/libs/lodash-es/4.17.21/lodash.js"
 }
}
</script>

Runtime Implication: Maps bare module specifiers to absolute, version-pinned CDN URLs. Must be placed in <head> before any module scripts execute. The browser resolves these paths synchronously during the initial parse phase, eliminating build-time aliasing overhead.

Dynamic Runtime Map Injection for Hot-Swappable Remotes #

async function updateImportMap(newMap) {
 const script = document.createElement('script');
 script.type = 'importmap';
 script.textContent = JSON.stringify({ imports: newMap });
 document.head.appendChild(script);
 // Note: Native browsers only apply maps before first import.
 // Use es-module-shims for dynamic override in production.
}

Runtime Implication: Demonstrates programmatic injection. Highlights the native browser limitation where maps are parsed once, necessitating polyfills for true runtime updates. Suitable for pre-initialization configuration or paired with module shims.

Polyfill Fallback Configuration for Legacy Browsers #

<script async src="https://ga.jspm.io/npm:es-module-shims@1.8.2/dist/es-module-shims.js"></script>
<script type="importmap-shim">
{
 "imports": {
 "@company/ui-core": "/libs/ui-core/1.4.2/index.js"
 }
}
</script>
<script type="module-shim">import '@company/ui-core';</script>

Runtime Implication: Uses es-module-shims to polyfill import map behavior in Safari <16.4 and older Chromium versions, ensuring cross-browser compatibility. The shim intercepts import() calls and resolves them against the provided JSON, maintaining near-native performance.

Common Pitfalls #

FAQ #

How do import maps handle version resolution for shared dependencies? Import maps use exact string matching for bare specifiers. Version resolution is managed manually by updating the map JSON to point to new immutable URLs, requiring coordinated deployment across all consuming remotes.

Can dynamic imports override a static import map at runtime? Native browsers parse import maps only once during initial page load. To override at runtime, you must use a polyfill like es-module-shims or implement a custom module loader that intercepts import() calls.

What is the recommended fallback strategy for unsupported browsers? Deploy es-module-shims conditionally using feature detection (HTMLScriptElement.supports('importmap')). The polyfill provides near-native resolution performance while maintaining compatibility with Safari <16.4 and legacy Chromium.

Related content