Configuration

Every option you can pass to initFederation — host entry, import-map implementation, logging, resolution modes and storage.

Everything you pass as the second argument to initFederation lives on this page. Options are grouped into five concerns — host entry, import-map implementation, logging, modes, and storage — and every option ships with a sensible default, so a bare initFederation(manifest) is already a valid call.

• 1. Host configuration
• 2. Import-map implementation
• 3. Logging
• 4. Modes — strictness & resolution profile
• 5. Storage

1. Host configuration

A host remote entry is a remoteEntry.json published by the host itself. Whenever an external appears both in the host entry and in a regular remote, the host version wins — making this the right escape hatch for locking a framework or design-system version globally.

type HostOptions = {
  hostRemoteEntry?:
    | string
    | false
    | {
        name?: string;
        url: string;
        cacheTag?: string;
        integrity?: string;
      };
  manifestIntegrity?: string;
};

Example

import { initFederation } from "@softarc/native-federation-orchestrator";

initFederation("http://example.org/manifest.json", {
  manifestIntegrity: "sha384-…",
  hostRemoteEntry: {
    url: "./remoteEntry.json",
    cacheTag: "v1.2.3",
    integrity: "sha384-…",
  },
});

Per-remote pinning lives in the manifest itself — entries can be either the existing string form or a { url, integrity } object, and the two forms can coexist:

{
  "team/mfe1": "https://mfe1.example.org/remoteEntry.json",
  "team/mfe2": {
    "url": "https://mfe2.example.org/remoteEntry.json",
    "integrity": "sha384-…"
  }
}

2. Import-map implementation

The orchestrator commits a standard import map to the DOM and uses the browser's own import() to load modules. For older browsers — or whenever you need dynamic init — swap in es-module-shims.

type ImportMapOptions = {
  loadModuleFn?: (url: string) => Promise<unknown>;
  setImportMapFn?: (
    importMap: ImportMap,
    opts?: { override?: boolean },
  ) => Promise<ImportMap>;
  reloadBrowserFn?: () => void;
  trustedTypesPolicyName?: string | false;
};

Two ready-made presets

import "es-module-shims";
import { initFederation } from "@softarc/native-federation-orchestrator";
import {
  useShimImportMap,
  useDefaultImportMap,
  replaceInDOM,
} from "@softarc/native-federation-orchestrator/options";

initFederation("http://example.org/manifest.json", {
  // Option 1 — native import maps (default)
  ...useDefaultImportMap(),

  // Option 2 — es-module-shims
  ...useShimImportMap({ shimMode: true }),

  // Option 3 — custom
  loadModuleFn: (url) => customImport(url),
  setImportMapFn: replaceInDOM("importmap"),

  // Option 4 — rename the Trusted Types policy to match a stricter CSP allowlist
  trustedTypesPolicyName: "my-app-nfo",
});

3. Logging

Diagnostics for both development and production. Ships with two built-in loggers and accepts any object that matches the Logger interface.

type LoggingOptions = {
  logger?: Logger;
  logLevel?: "debug" | "warn" | "error";
  sse?: boolean;
};

interface Logger {
  debug(step: number, msg: string, details?: unknown): void;
  warn(step: number, msg: string, details?: unknown): void;
  error(step: number, msg: string, details?: unknown): void;
}

Example

import { initFederation } from "@softarc/native-federation-orchestrator";
import {
  noopLogger,
  consoleLogger,
} from "@softarc/native-federation-orchestrator/options";

initFederation("http://example.org/manifest.json", {
  logLevel: "debug",
  logger: consoleLogger, // or noopLogger, or a custom Logger
});

4. Modes — strictness & resolution profile

Mode options are the hyperparameters for the Version Resolver: how strict to be when something unexpected happens, and how aggressively to reuse cached state.

type ModeOptions = {
  strict?:
    | boolean
    | {
        strictRemoteEntry?: boolean;
        strictExternalCompatibility?: boolean;
        strictExternalSameVersionCompatibility?: boolean;
        strictExternalVersion?: boolean;
        strictImportMap?: boolean;
      };
  profile?: {
    latestSharedExternal?: boolean;
    skipInvalidExternalVersions?: boolean;
    overrideCachedRemotes?: "always" | "never" | "init-only";
    overrideCachedRemotesIfURLMatches?: boolean;
    cacheTag?: string;
  };
  feature?: {
    convertFlatSharedInfo?: boolean;
    useAutoExternalPooling?: boolean;
  };
};

Strictness

All flags default to false, which means "log and continue". Setting strict: true turns them all on at once.

Resolution profile

The profile controls how the resolver picks winners and whether it refreshes cached remotes.

overrideCachedRemotes values:

• 'never' — don't touch cached remotes, ever. Strongest cache, slowest pickup of new versions.
• 'init-only' (default) — allow overrides during initFederation, skip during dynamic init. Good compromise.
• 'always' — always check and possibly refetch. Use when cache freshness matters more than bandwidth.

Features

Opt-in behaviors that change how shared externals are processed and stored. Both default to false.

Two ready-made profiles

import { initFederation } from "@softarc/native-federation-orchestrator";
import {
  defaultProfile,
  cachingProfile,
} from "@softarc/native-federation-orchestrator/options";

// defaultProfile
// { latestSharedExternal: false, skipInvalidExternalVersions: false, overrideCachedRemotes: 'init-only', overrideCachedRemotesIfURLMatches: false }

// cachingProfile
// { latestSharedExternal: false, skipInvalidExternalVersions: false, overrideCachedRemotes: 'never',     overrideCachedRemotesIfURLMatches: false }

initFederation("http://example.org/manifest.json", {
  strict: true,
  profile: cachingProfile,
});

5. Storage

The orchestrator keeps its internal caches (remote info, shared externals, scoped externals) inside a storage entry. The default is an in-memory map on globalThis, but any Storage-compatible backend works.

type StorageOptions = {
  storage?: StorageEntryCreator;
  clearStorage?: boolean;
  storageNamespace?: string;
};

Example

import { initFederation } from "@softarc/native-federation-orchestrator";
import {
  globalThisStorageEntry,
  localStorageEntry,
  sessionStorageEntry,
} from "@softarc/native-federation-orchestrator/options";

initFederation("http://example.org/manifest.json", {
  clearStorage: true,
  storageNamespace: "__custom_namespace__",

  // Option 1 — in-memory (default)
  storage: globalThisStorageEntry,

  // Option 2 — persisted for the browser session
  storage: sessionStorageEntry,

  // Option 3 — persisted across browser restarts
  storage: localStorageEntry,
});

Putting it together

import { initFederation } from "@softarc/native-federation-orchestrator";
import {
  consoleLogger,
  sessionStorageEntry,
  useShimImportMap,
  cachingProfile,
} from "@softarc/native-federation-orchestrator/options";

const { loadRemoteModule } = await initFederation(manifest, {
  // Host
  hostRemoteEntry: { url: "./host-remoteEntry.json", cacheTag: "2025-04-22" },

  // Import map
  ...useShimImportMap({ shimMode: true }),

  // Logging
  logLevel: "warn",
  logger: consoleLogger,

  // Modes
  strict: { strictRemoteEntry: true, strictExternalCompatibility: true },
  profile: cachingProfile,

  // Storage
  storage: sessionStorageEntry,
  storageNamespace: "__NATIVE_FEDERATION__",
  clearStorage: false,
});

See also

• The orchestrator docs — Which shows a bit more in-depth how the orchestrator can be configured.
• Security & Subresource Integrity — CSP setup for the built-in Trusted Types policy and the SRI trust chain (manifest → remoteEntry.json → modules).
• Version Resolver — how the profile and strictness flags actually shape resolution output.
• Architecture — caches — what lives in the storage namespace.
• Getting Started — worked examples for the quickstart, registry and custom setups.