API Reference

The public API surface of @softarc/native-federation-runtime v3 — initFederation, loadRemoteModule, the lower-level building blocks, the Module Federation bridge and type exports.

@softarc/native-federation-runtime exposes a small set of functions and types. Most applications only use initFederation and loadRemoteModule; the lower-level helpers are useful when integrating with custom bootstrap flows, test setups or adapter code.

Everything below is reachable from the package root. The package has a single entry point — there are no subpath exports.

Functions

Export	Kind	Summary
`initFederation(remotesOrManifestUrl?, options?)`	function	Main host-side entry point. Loads the host's `remoteEntry.json`, fetches every remote's `remoteEntry.json`, builds and injects the import map. Returns the final `ImportMap`. See `initFederation`.
`loadRemoteModule(remoteName, exposedModule)` / `loadRemoteModule(options)`	function	Dynamically imports an exposed module from a registered remote. Supports lazy registration via `options.remoteEntry` and a `fallback` for graceful degradation. See `loadRemoteModule`.
`processRemoteInfos(remotes, options?)`	function	Fetches and registers a batch of remotes in parallel and merges their import maps. Honours `throwIfRemoteNotFound` and `cacheTag`. Returns the merged `ImportMap` — it does not inject anything. Called internally by `initFederation`.
`fetchAndRegisterRemote(federationInfoUrl, remoteName?)`	function	Fetches and registers a single remote. Computes the remote's import map and, if the `remoteEntry.json` includes a `buildNotificationsEndpoint`, starts watching for rebuild events. Falls back to the `name` in `remoteEntry.json` when `remoteName` is omitted.
`processHostInfo(hostInfo, relBundlesPath?)`	function	Builds the host's contribution to the import map from a `FederationInfo` and registers its shared deps as externals. Useful in flows that load the host's info themselves. `relBundlesPath` defaults to `'./'`.
`mergeImportMaps(a, b)`	function	Shallow-merges two `ImportMap` values. Second argument wins on key collisions.
`getShared(options?)`	function	Converts the externals registry into the `shared` shape webpack Module Federation expects, so both systems resolve to one instance per package. Options: `{ singleton: boolean; requiredVersionPrefix: '^' \| '~' \| '>' \| '>=' \| '' }` — both default to a non-singleton, exact-version config.

Types

Export	Kind	Summary
`InitFederationOptions`	interface	`{ cacheTag?: string; deployUrl?: string }` — options accepted by `initFederation`. See `deployUrl` and `cacheTag`.
`ProcessRemoteInfoOptions`	interface	Extends `InitFederationOptions` with `throwIfRemoteNotFound: boolean`. Drives the strict/forgiving error behaviour in `processRemoteInfos`.
`LoadRemoteModuleOptions<T>`	type	Long-form options for `loadRemoteModule`: `remoteEntry?`, `remoteName?`, `exposedModule`, `fallback?`.
`FederationInfo`	interface	The parsed `remoteEntry.json`: `{ name, exposes, shared, buildNotificationsEndpoint? }`.
`ExposesInfo`	interface	One entry of `exposes`: `{ key, outFileName, dev? }`.
`SharedInfo`	type	One entry of `shared`: `{ singleton, strictVersion, requiredVersion, version?, packageName, outFileName, dev? }`.
`ImportMap`	type	The browser import-map shape: `{ imports: Imports; scopes: Scopes }`.
`Imports`	alias	`Record<string, string>` — bare-specifier to URL.
`Scopes`	alias	`Record<string, Imports>` — scope URL prefix to scoped imports.
`ShareObject` / `ShareConfig` / `ShareOptions`	types	The Module Federation shapes produced and consumed by `getShared`.

Constants

Export	Kind	Summary
`BUILD_NOTIFICATIONS_ENDPOINT`	const	`'/@angular-architects/native-federation:build-notifications'`. The SSE path the Angular dev server exposes for rebuild events.
`BuildNotificationType`	enum	`COMPLETED` (`'federation-rebuild-complete'`), `ERROR`, `CANCELLED`. Only `COMPLETED` triggers a page reload.
`BuildNotificationOptions`	interface	`{ enable: boolean; endpoint: string }` — the builder-side shape mirrored here so adapters can share the type.

Global state

The runtime stores its registries on globalThis.__NATIVE_FEDERATION__:

type NfCache = {
  externals:             Map<string, string>;  // "pkg@version" -> URL
  remoteNamesToRemote:   Map<string, Remote>;   // remoteName    -> info + baseUrl
  baseUrlToRemoteNames:  Map<string, string>;   // baseUrl       -> remoteName
};

The object is created on first import and reused afterwards, so a second copy of the runtime on the same page shares the same registries. The helpers that read and write it (addRemote, getRemote, hasRemote, getRemoteNameByBaseUrl, isRemoteInitialized, getExternalUrl, setExternalUrl) are internal — they are not re-exported from the package root. Reach for the global object directly if you need to inspect state, as getShared does.

Mixing with webpack Module Federation

getShared exists for pages that run both Native Federation and classic Module Federation remotes. It walks the externals registry, splits each pkg@version key, and emits an MF shared entry whose get() loads the already-resolved URL through importShim:

import { getShared } from '@softarc/native-federation-runtime';

const shared = getShared({ singleton: true, requiredVersionPrefix: '^' });

Keys starting with /@id/ or @angular-architects/module-federation, and keys with an empty version, are filtered out. Hand the result to your MF runtime as its shared scope so both systems agree on one instance per package.