How knitkit Works: Remotes, Manifests, and Import Maps

Understand remotes, hosts, manifests, shared dependencies, and import-map negotiation — the building blocks of knitkit module federation.

knitkit federation is built from a small set of composable ideas: a host that consumes federated modules, remotes that publish them, a manifest that describes what a remote offers, an import map that enforces singleton shared dependencies, and an expose key convention for addressing individual modules. Understanding these building blocks makes every other part of the system predictable.

Host and Remote

A remote is any application or library that runs knitkit build. It produces a knit.manifest.json describing the modules it exposes and the shared dependencies it contributes, along with the built ESM artifacts for each. A remote is completely self-contained: serve its dist/ directory from any static host and it is ready to be consumed.

A host is any application that calls registerRemotes at boot time. The host fetches one or more remote manifests, negotiates shared dependency versions across all participants (including its own declared shared dependencies), injects a single import map, and then loads individual exposed modules on demand with loadRemote.

The host and remote do not need to know about each other at build time. The only coupling is the manifest URL, which is provided at runtime. This means you can deploy a new version of a remote and have the host pick it up on the next page load without any changes to the host’s build.

A single application can be both a host and a remote simultaneously — it can expose its own modules via a manifest while also loading modules from other remotes.

The Manifest

The manifest (knit.manifest.json) is the contract between a remote and its consumers. It is a versioned JSON document that the host fetches at boot to learn what the remote offers and what shared dependencies it expects.

Here is a representative manifest:

knit.manifest.json

{
  "spec": "0.1",
  "name": "checkout",
  "exposes": {
    "./CartWidget": {
      "url": "./exposes/CartWidget.js",
      "types": "./types/CartWidget.d.ts"
    },
    "./CheckoutForm": {
      "url": "./exposes/CheckoutForm.js"
    }
  },
  "shared": {
    "react": {
      "version": "18.3.1",
      "requiredVersion": "^18.2.0",
      "singleton": true,
      "url": "./shared/react-18.3.1.js",
      "integrity": "sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9r7jQ..."
    }
  },
  "meta": {
    "buildTime": "2026-06-12T18:00:00Z",
    "framework": "react@18"
  }
}

Field	Required	Description
spec	Yes	The manifest spec version. Currently "0.1". The runtime rejects manifests with an unrecognised spec version.
name	Yes	The remote’s identifier, used as the prefix in loadRemote. Lowercase [a-z][a-z0-9_-]*.
exposes	Yes	Map of expose key → expose declaration. May be an empty object.
shared	Yes	Map of package name → shared declaration. May be an empty object.
meta	No	Free-form metadata. Suggested keys: buildTime, framework.

All relative URLs in the manifest (url, types) resolve against the manifest’s own URL. You can host a remote on any path or CDN origin and nothing breaks.

Shared Dependencies

Shared dependencies are packages that must resolve to a single instance across the host and all remotes. The canonical example is React: if a remote’s hooks run against a different React instance than the host’s renderer, React throws. The same constraint applies to any library that uses module-level singletons — stores, routers, context providers.

knitkit solves this with a direct property of import maps: one import map entry maps to one URL, and one URL means one module instance in the browser cache. There is no share scope, no runtime reference counting, and no configuration flag that can accidentally create a second copy.

Each participant in the federation — the host and every remote — declares its shared dependencies with three key fields:

Field	Description
version	The exact version this participant contributes (i.e. what it built against).
requiredVersion	A semver range this participant can accept. Supports ^, ~, >=, exact, and x-ranges like 1.x.
singleton	If true (the default), a version conflict throws KNIT_ERR_SINGLETON_CONFLICT. If false, an incompatible version is loaded in isolation via an import map scopes entry.

Set singleton: true for any package that uses module-level state or React context. Setting singleton: false on React, for example, re-introduces the very problem knitkit is designed to eliminate.

Import Map Negotiation

When you call registerRemotes, the runtime runs the following sequence:

1. Fetch manifests — each remote’s knit.manifest.json is fetched in parallel. The response URL is used as the base for resolving relative url fields, so the manifest is portable.
2. Negotiate shared deps — negotiateShared merges the shared declarations from the host and all remotes. For each package, it selects the highest version that satisfies every participant’s requiredVersion. If any participant declares singleton: true and no single version satisfies all ranges, the runtime throws KNIT_ERR_SINGLETON_CONFLICT immediately rather than silently loading a duplicate.
3. Inject the import map — injectImportMap writes a <script type="importmap"> element into the document (or the equivalent structure in Node/edge environments) before any module import resolves through it. Every import "react" — from the host or from any remote — now resolves to the single winning URL.
4. Register remotes — the runtime stores each remote’s manifest and base URL so loadRemote can look up expose URLs later.

Call getLastResult() after registerRemotes to inspect the full NegotiationResult, including which version won for each package and from which URL. This is the programmatic equivalent of reading the import map in DevTools.

Expose Keys

The exposes object in the manifest uses keys written with a leading ./, following the Node.js package exports convention:

"exposes": {
  "./CartWidget": { "url": "./exposes/CartWidget.js" },
  "./CheckoutForm": { "url": "./exposes/CheckoutForm.js" }
}

When a consumer calls loadRemote, they combine the remote’s name with the expose key, omitting the ./:

const CartWidget = await loadRemote("checkout/CartWidget");
//                                   ^^^^^^^^  ^^^^^^^^^^
//                                   name      expose key (without ./)

The runtime automatically normalises the key by prepending ./ before looking it up in the manifest. If the key is not found, loadRemote throws KNIT_ERR_LOAD_FAILED and lists the available keys in the error’s suggestion field.

SRI Integrity

The manifest’s integrity field on each shared dependency and expose declaration holds a Subresource Integrity hash computed by @knitkit/cli at build time:

"react": {
  "version": "18.3.1",
  "url": "./shared/react-18.3.1.js",
  "integrity": "sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K..."
}

The integrity field is consumed in two ways:

• In the browser, the runtime places the hash in the import map’s integrity key (available in Chrome 127+, Firefox 138+, Safari 18.4+). The browser enforces the hash on the module fetch, refusing to execute a tampered file.
• In Node SSR, @knitkit/node’s loader hooks verify the hash against the fetched bytes before the module is evaluated, providing the same protection server-side.

The integrity field is optional in the manifest schema. Remotes built without @knitkit/cli can omit it, but SRI verification will not be possible for those modules. For production deployments, always run knitkit build to get computed hashes.