@knitkit/runtime — Full Browser Runtime API Reference

Full API reference for @knitkit/runtime: registerRemotes, loadRemote, negotiateShared, injectImportMap, validateManifest, getShareInfo, and error types.

The @knitkit/runtime package is the browser-side core of knitkit. It fetches remote manifests, negotiates shared dependency versions, injects a native ES module import map, and exposes lazy module loading — all in under 5 KB with zero dependencies. Import from @knitkit/runtime in your host application’s entry point; every export below is available from that single specifier.

---

registerRemotes(remotes, options?)

registerRemotes is the primary entry point for a host application. It fetches (or accepts inline) each remote’s manifest, runs shared-dependency version negotiation, injects the resulting import map into the document, and stores registrations so that subsequent loadRemote calls can resolve module URLs. Call it once, before any loadRemote call or <script type="module"> that imports federated modules.

registerRemotes(
  remotes: RegisterRemotesInput[],
  options?: RegisterRemotesOptions
): Promise<NegotiationResult>

Parameters

remotes · RegisterRemotesInput[] · required

An array of remote descriptors. Each entry identifies a remote by name and tells the runtime where to find its manifest.

Show RegisterRemotesInput fields

name · string · required

The logical name of the remote. This becomes the prefix used in loadRemote specifiers — e.g. a remote named "checkout" is loaded as loadRemote("checkout/CartWidget").

manifest · string | Manifest · required

Either an absolute or relative URL string pointing to the remote’s knit.manifest.json, or an already-parsed Manifest object for inline/pre-fetched use. When a URL string is provided, the runtime fetches it with credentials: "same-origin" and uses the resolved response URL as the base for relative asset paths.

options · RegisterRemotesOptions

Optional configuration for the host side of negotiation.

Show RegisterRemotesOptions fields

options.hostShared · Record<string, HostSharedDecl>

A map of package name to the host’s own copy of that shared dependency. Declare this when the host itself has bundled or loaded a shared package (e.g. React) and wants it to participate in version negotiation.

Show HostSharedDecl fields

version · string · required

The exact semver version the host provides (e.g. "18.3.1").

requiredVersion · string · required

The semver range the host requires from any shared copy (e.g. "^18.2.0").

singleton · boolean

When true (the default), a version conflict with any remote throws KNIT_ERR_SINGLETON_CONFLICT rather than falling back to a scoped copy.

url · string · required

URL to the host’s prebundled ESM asset for this package.

integrity · string

Optional SRI hash (sha384-...) for the asset.

importAs · string

The package name as the host references it in the import map. Defaults to the key name.

Returns

Promise<NegotiationResult> — resolves once all manifests are fetched and the import map has been injected.

winners · Record<string, { version: string; url: string; integrity?: string; source: string }>

For each shared package, the single winning version that was selected and the URL that will be used for it. source is the remote name (or "host") that contributed the winning copy.

scopes · Record<string, Record<string, string>>

Fallback import map scopes for any non-singleton packages where a participant’s required version range could not be satisfied by the winner. Each key is a URL scope prefix; its value maps package names to the scoped fallback URL.

importMap · ImportMap

The fully computed import map payload — { imports, scopes?, integrity? } — that was injected into the document. Useful for server-side rendering where you need to serialize the map into HTML.

report · ResolutionReport

A human-readable resolution report keyed by package name. Each entry contains the winner details, any fallbacks, and a boolean conflict flag. Inspect this with getShareInfo() during debugging.

Example

import { registerRemotes } from "@knitkit/runtime";

await registerRemotes(
  [
    { name: "checkout", manifest: "https://cdn.example.com/checkout/knit.manifest.json" },
    { name: "recommendations", manifest: "https://cdn.example.com/recs/knit.manifest.json" },
  ],
  {
    hostShared: {
      react: {
        version: "18.3.1",
        requiredVersion: "^18.2.0",
        singleton: true,
        url: "/static/shared/react-18.3.1.js",
      },
    },
  },
);

---

loadRemote(specifier)

loadRemote dynamically imports an exposed module from a previously registered remote. It resolves the module URL from the stored registration, delegates to the native import() function, and returns the module’s default export when one is present, or the full namespace object otherwise.

loadRemote<K extends keyof RemoteModules>(specifier: K): Promise<RemoteModules[K]>
loadRemote<T = unknown>(specifier: string): Promise<T>

Parameters

specifier · string · required

A string of the form "<remoteName>/<exposeKey>". The ./ prefix on the expose key is optional — "checkout/CartWidget" and "checkout/./CartWidget" resolve identically. The remoteName must match a name passed to registerRemotes.

Returns

Promise<T> — the module’s default export if the loaded module has one, otherwise the full ES module namespace object.

Type safety

When you run knitkit types sync, the command generates a declaration file that augments the RemoteModules interface in @knitkit/runtime. After that, specifiers listed in RemoteModules are fully typed; unregistered specifiers fall back to unknown.

Example

import { loadRemote } from "@knitkit/runtime";

// Returns CartWidget's default export, typed if RemoteModules is augmented.
const CartWidget = await loadRemote("checkout/CartWidget");

// Generic override for untyped cases.
const data = await loadRemote<{ items: string[] }>("inventory/ProductList");

Error codes

Code	When thrown
KNIT_ERR_NOT_REGISTERED	The remoteName portion of the specifier has not been registered via registerRemotes.
KNIT_ERR_LOAD_FAILED	The specifier format is invalid, the expose key does not exist in the remote’s manifest, or the underlying import() call fails (network error, CORS, parse error).

---

getLastResult()

getLastResult returns the NegotiationResult produced by the most recent registerRemotes call, or null if registerRemotes has not been called yet. Use this for post-boot inspection or logging without needing to hold a reference to the registerRemotes promise.

getLastResult(): NegotiationResult | null

---

getShareInfo()

getShareInfo returns the ResolutionReport from the last negotiation. The report is a flat, human-readable summary of which version won for each package, which participants fell back to a scoped copy, and whether any conflicts were detected. Unlike getLastResult, this function always returns a valid object (an empty report when negotiation has not run).

getShareInfo(): ResolutionReport

Example

import { getShareInfo } from "@knitkit/runtime";

const report = getShareInfo();
for (const [pkg, info] of Object.entries(report.packages)) {
  console.log(`${pkg}@${info.winner.version} from ${info.winner.source}`);
  if (info.conflict) {
    console.warn(`  ↳ ${info.fallbacks.length} fallback(s)`);
  }
}

---

negotiateShared(manifests, hostShared?)

negotiateShared is the low-level version negotiation engine. registerRemotes calls it internally — most application code never needs to call it directly. It is re-exported from @knitkit/node for server-side rendering scenarios where you want to run negotiation in Node.js without touching the DOM.

negotiateShared(
  manifests: Array<{ name: string; manifest: Manifest; baseUrl: string }>,
  hostShared?: Record<string, HostSharedDecl>,
  hostBaseUrl?: string,
): NegotiationResult

Parameters

manifests · Array<{ name: string; manifest: Manifest; baseUrl: string }> · required

Parsed manifests to negotiate. baseUrl is the absolute URL of the manifest document; relative shared[].url values are resolved against it.

hostShared · Record<string, HostSharedDecl>

Optional host-side shared declarations, identical in shape to the options.hostShared accepted by registerRemotes.

hostBaseUrl · string

Optional base URL for resolving relative URLs within hostShared entries. Defaults to "".

Returns

NegotiationResult — synchronously; no network I/O is performed.

---

injectImportMap(importMap)

injectImportMap merges a computed import map into the document’s <script type="importmap"> element. If no such element exists it creates one and appends it to <head>. If one already exists it merges imports, scopes, and integrity objects into the existing map.

injectImportMap(importMap: ImportMap): void

importMap · ImportMap · required

An object with imports (required), scopes (optional), and integrity (optional) keys — the standard import map shape.

Call injectImportMap before any <script type="module"> that resolves specifiers through the map. Native import maps are immutable once a browser’s module graph has started loading, and injecting a map after that point has no effect on already-started loads.

injectImportMap requires a DOM (document must be defined). In Node.js or edge runtimes, it throws KNIT_ERR_IMPORT_MAP_INJECTION_FAILED. Use @knitkit/node for server-side rendering, which handles import map serialization without touching the DOM.

---

validateManifest(input, sourceLabel)

validateManifest parses and validates an unknown value against the knitkit manifest spec. It checks the spec version, name format, exposes and shared structure, semver validity, and field types. On success it returns a fully-typed Manifest object; on failure it throws a FedkitError.

validateManifest(input: unknown, sourceLabel: string): Manifest

input · unknown · required

The raw parsed JSON (e.g. the result of JSON.parse). Pass it before using any manifest fields so you get structured error messages rather than runtime property access failures.

sourceLabel · string · required

A human-readable label included in error messages — typically the manifest URL or file path. Used for diagnostics only.

Throws FedkitError with code KNIT_ERR_MANIFEST_INVALID when any field is missing or invalid. The error’s .message identifies the specific field and the .suggestion field provides a corrective action.

Example

import { validateManifest, isFedkitError } from "@knitkit/runtime";

const raw = await fetch("/federation/knit.manifest.json").then((r) => r.json());
try {
  const manifest = validateManifest(raw, "/federation/knit.manifest.json");
  console.log("Loaded manifest for remote:", manifest.name);
} catch (e) {
  if (isFedkitError(e)) {
    console.error(e.message);
    console.info("Suggestion:", e.suggestion);
  }
}

---

FedkitError and isFedkitError

All errors thrown by @knitkit/runtime are instances of FedkitError. Use isFedkitError to distinguish them from unexpected runtime errors in a catch block.

class FedkitError extends Error {
  readonly code: FedkitErrorCode;
  readonly suggestion?: string;
}

function isFedkitError(e: unknown): e is FedkitError

FedkitError fields

code · FedkitErrorCode

A stable string code identifying the error category. See the full list below.

message · string

A human-readable description including the specific package name, URL, or field that caused the error.

suggestion · string | undefined

An actionable suggestion for resolving the error, when one is available.

Error codes

Code	Thrown by	Cause
KNIT_ERR_NEGOTIATION_CONFLICT	negotiateShared	Reserved for future multi-phase conflict detection.
KNIT_ERR_SINGLETON_CONFLICT	negotiateShared	A singleton: true package has no version that satisfies every participant’s requiredVersion range.
KNIT_ERR_MANIFEST_INVALID	validateManifest	A manifest field is missing, has the wrong type, or contains an invalid semver string or range.
KNIT_ERR_LOAD_FAILED	loadRemote, registerRemotes	Manifest fetch failed (network error or non-2xx status), or the underlying import() call for a module failed.
KNIT_ERR_NOT_REGISTERED	loadRemote	The remote name in the specifier has not been registered via registerRemotes.
KNIT_ERR_IMPORT_MAP_INJECTION_FAILED	injectImportMap	document is not defined (non-browser environment).

Example

import { registerRemotes, isFedkitError } from "@knitkit/runtime";

try {
  await registerRemotes([{ name: "checkout", manifest: "/federation/knit.manifest.json" }]);
} catch (e) {
  if (isFedkitError(e)) {
    switch (e.code) {
      case "KNIT_ERR_SINGLETON_CONFLICT":
        console.error("Version conflict — align shared dep versions across remotes.");
        break;
      case "KNIT_ERR_LOAD_FAILED":
        console.error("Could not reach manifest:", e.message);
        if (e.suggestion) console.info(e.suggestion);
        break;
      default:
        console.error(`[${e.code}] ${e.message}`);
    }
  } else {
    throw e;
  }
}