# Native Federation / import maps

Each team builds its app into plain ES modules. An import map tells the browser where every remote and shared library lives, so the shell loads them at runtime without a bundler-specific loader.

## How it works

1. **Read the manifest.** The shell starts by reading a manifest that maps each remote's name to the URL of its remoteEntry.json.
2. **Build the import map.** From every remote entry, the runtime collects exposed modules and shared libraries and hands the browser one import map.
3. **Import a remote.** When a route needs team A's component, the browser imports it as an ES module from team A's server.
4. **Shared copies resolve once.** Imports of a shared library resolve through the import map to one copy. Team B loads the same way, from its own deployment.

## Try it

**Demo: Shared dependency conflict.**

Team A and Team B both use React, and both start on 18.3, so the browser downloads one shared copy and both apps render. Move Team B to React 19.0 and the two versions no longer share a major version. With no singleton, each app brings its own copy: everything works, but users download a second React, about 45 KB more, and a component from one copy can't render inside the other copy's tree or read its context. Force a singleton instead and only the higher version, 19.0, is loaded, so Team A, built for 18.3, runs on a React it wasn't built for and may break. In Module Federation a singleton version mismatch only prints a warning, and with strictVersion it is a runtime error. Native Federation uses the shared copy silently, and with strictVersion gives that team its own copy instead, so the forced singleton no longer holds. The sizes are illustrative.

Takeaway: Dependency sharing is a real cost. Either teams coordinate versions, or users download duplicates, or a forced singleton breaks someone at runtime. Pick one on purpose.

## Pros

- Teams deploy remotes independently; the manifest points the shell at whatever is deployed.
- Built on ES modules and import maps, so the browser does the module wiring rather than a bundler runtime.
- Same mental model and a similar API to Module Federation, with a migration path from it.

## Cons

- Most of the tooling and examples target Angular; other stacks need the core library or the esbuild adapter.
- Shared library versions still have to be negotiated between teams.
- Remotes share one page, so styles and globals can collide.

## Best when

- Angular teams on the esbuild-based CLI who want runtime composition.
- You want federation without tying every team to webpack.
- Several teams need independent deploys with shared libraries loaded once.

## Avoid when

- One or two teams who could share code as packages.
- Teams on many different frameworks, where sharing libraries brings little.
- You need strong isolation between untrusted parts.

## In code

`main.ts · app.routes.ts (shell)`

```ts
// main.ts: read the manifest, then start the app with the result
initFederation("federation.manifest.json")
  .then((nf) => import("./bootstrap").then((m) => m.bootstrap(nf)))
  .catch((err) => console.error(err));

// app.routes.ts: load team A's exposed component on demand
export const routes = ({ loadRemoteModule }: NativeFederationResult): Routes => [{
  path: "flights",
  loadComponent: () =>
    loadRemoteModule("mfe1", "./Component").then((m) => m.AppComponent),
}];

// federation.manifest.json
// { "mfe1": "https://team-a.example.com/remoteEntry.json" }
```

## Ratings

_Editorial judgement for a typical team, from 1 to 5._

- **Team independence: 4/5** (higher is better). Each remote builds and deploys on its own, and the shell finds it through the manifest at runtime.
- **Runtime performance: 3/5** (higher is better). Each remote adds module requests when it loads, while shared libraries resolve to one copy through the import map.
- **Complexity: 3/5** (lower is simpler). Schematics set up hosts and remotes, but shared versions, manifests per environment and failing remotes are still yours to handle.
- **SSR / SEO support: 3/5** (higher is better). The Angular adapter supports server rendering and hydration, with setup beyond a client-only host.
- **Tech-agnostic: 2/5** (higher is better). The core is framework-agnostic, but sharing works best when every remote uses the same framework, and most tooling is Angular's.
- **Isolation: 2/5** (higher is better). Remotes run as modules in the same page and share globals and styles.
- **UX consistency: 4/5** (higher is better). Remotes render into one page and can share a design system as a shared library.
- **Tooling maturity: 3/5** (higher is better). Maintained documentation, schematics and adapters, with a smaller ecosystem than Module Federation outside Angular.

## Tooling and ecosystem

Native Federation is maintained at [native-federation.com](https://native-federation.com/docs/v4/core/) and is in its v4 line as of November 2026. The framework-agnostic core is `@softarc/native-federation` (4.9). It bundles shared libraries and exposed modules into standalone ES modules, writes a `remoteEntry.json` per remote and an import map for the browser, and provides an esbuild adapter and a contract for writing your own. The Angular adapter, `@angular-architects/native-federation` (22.2), follows Angular's version numbers and builds on the Angular CLI's esbuild-based builder. For Angular 20 and 21, the same adapter is published under another name, `@angular-architects/native-federation-v4`.

The adapter's docs describe it as Module Federation's mental model on browser standards, with a similar API to `@angular-architects/module-federation`. They warn against mixing imports from the two in one app. In v4, `initFederation` (imported from `@angular-architects/native-federation`) resolves to a result whose `loadRemoteModule` the app passes to its routes and services. The older top-level `loadRemoteModule` import is deprecated. Import maps are a standard browser feature ([MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap)). By default the adapter uses es-module-shims in shim mode, which also lets you add remotes after the page has started.

Version mismatches on a `singleton: true` dependency work differently from Module Federation. Native Federation's [version resolver](https://native-federation.com/docs/v4/orchestrator/version-resolver/) lets a remote whose range rejects the shared version silently use the shared copy, which may break at runtime. With `strictVersion: true`, that remote gets its own copy instead. Loading fails only when `strictExternalCompatibility` is turned on.

## Sources

- [Angular adapter — Native Federation Docs](https://native-federation.com/docs/v4/angular-adapter/), native-federation.com
- [Core — Native Federation Docs](https://native-federation.com/docs/v4/core/), native-federation.com
- [Runtime — Native Federation Docs](https://native-federation.com/docs/v4/angular-adapter/runtime/), native-federation.com
- [Native Federation & Module Federation — Native Federation Docs](https://native-federation.com/docs/v4/native-and-module-federation/), native-federation.com
- [Version Resolver — Native Federation Docs](https://native-federation.com/docs/v4/orchestrator/version-resolver/), native-federation.com
- [<script type="importmap">](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap), MDN Web Docs

https://microfrontends.dev/approaches/native-federation-import-maps