Configuration

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;
    overrideCachedRemotes?: 'always' | 'never' | 'init-only';
    overrideCachedRemotesIfURLMatches?: 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.

Two ready-made profiles

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

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

// cachingProfile
// { latestSharedExternal: 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.