Runtime

The Native Federation Runtime — the classic browser-side library that reads remoteEntry.json files, builds an import map, and loads remote modules on demand.

The runtime — @softarc/native-federation-runtime — is the small browser-side library that reads remoteEntry.json files, constructs an ES module import map, injects it into the DOM, and resolves loadRemoteModule() calls against it. It is the classic Native Federation runtime: one version of each shared dependency, wired up on startup, and loaded on demand.

What the Runtime Does

Given a list of remotes (or a manifest URL that resolves to one), the runtime:

• Loads the host's own remoteEntry.json and registers its shared dependencies at the root of the import map.
• Fetches each remote's remoteEntry.json in parallel and registers:
  • the remote's exposed modules as root imports keyed by <remoteName>/<exposedKey>;
  • the remote's shared dependencies under a scope keyed by the remote's base URL.
• Merges everything into a single import map and injects it as a <script type="importmap-shim"> into document.head — so it needs es-module-shims in the page.
• Exposes a loadRemoteModule() helper that performs a dynamic import() (through importShim) against that import map.
• Optionally opens a Server-Sent Events connection to a remote's buildNotificationsEndpoint to reload the page when the remote rebuilds (dev only).

What the Runtime Does Not Do

The classic runtime is deliberately thin. Things that are not handled here (and are reasons to reach for the Orchestrator in v4):

• No semver-range resolution. Each shared dependency gets one URL per scope. If two remotes share different versions of rxjs they simply each keep their own — the runtime does not compare ranges or pick a common version. The first URL registered under a given packageName@version wins for the external lookup (see Externals registry).
• No share scopes. There is a single implicit scope per remote base URL; there is no shareScope concept.
• No persistent caching. Every page load re-fetches every remoteEntry.json. You can append a query string via cacheTag for cache-busting, but there is no localStorage/sessionStorage layer.
• No pluggable storage or logger. Errors go to console.error; state lives on globalThis.__NATIVE_FEDERATION__.

If any of those matter to you, look at the Orchestrator.

Where It Fits

The runtime is the consumer of the artifacts that Core emits. The contract between build and runtime is the remoteEntry.json file — the runtime does not care which bundler produced it. For how the runtime relates to the other layers, see the Architecture Overview.

In this section

• Getting Started — install the package, add es-module-shims, split your bootstrap.
• initFederation — how the host sets federation up: manifest vs. inline map, cache busting, error handling.
• loadRemoteModule — both call signatures, lazy remote registration and fallbacks.
• The Import Map — how imports and scopes are constructed, how externals are deduplicated, importmap-shim, and Trusted Types.
• API Reference — the complete public surface of @softarc/native-federation-runtime.