knitkit Config Files: knit.config.json and knit.host.json

Reference for knit.config.json (remote build config) and knit.host.json (host type-sync config) — all fields, types, and examples.

knitkit uses two separate JSON files to keep remote-build concerns and host type-sync concerns cleanly apart. Remotes carry a knit.config.json that drives knitkit build and knitkit types generate; hosts carry a knit.host.json that drives knitkit types sync. Neither file is required if you don’t use the corresponding command — you only create the file you need.

---

knit.config.json — remote build config

Place knit.config.json at your project root (the same directory where you run knitkit build). The CLI reads this file to know which packages to emit as shared ESM assets, which local modules to expose, and how to label the remote in manifests and import maps.

name · string · required

The remote’s unique identifier. Must match [a-z][a-z0-9_-]* (lowercase, start with a letter). This value becomes the prefix consumers use in loadRemote("<name>/..."). Changing it after publishing is a breaking change for every host that has registered the remote.

shared · string[] · required

An array of npm package names to bundle as shared ESM assets and list in the manifest’s shared section. Declare every package that must resolve to a single instance across the host and all remotes (for example, react, react-dom, or any shared store). The CLI resolves each entry from your local node_modules, emits a standalone ESM file, and records the version + SRI hash in the manifest.

exposes · string[] · required

An array of relative file paths (from the project root) to the modules you want to make loadable by hosts. Use the same ./src/... prefix that would work in an import statement from the root. The CLI builds each path to an ESM bundle, records it under the exposes map in the manifest, and optionally generates a .d.ts file alongside it.

Example values: "./src/CartWidget.tsx", "./src/utils/format.ts"

platform · "browser" | "node" · default: "\"browser\""

Controls which esbuild target platform the CLI uses when bundling exposed modules. Set to "node" for remotes that run in Node SSR only; leave as the default "browser" for anything that runs in the browser or at the edge.

Full example

{
  "name": "checkout",
  "shared": ["react", "react-dom", "zustand"],
  "exposes": [
    "./src/CartWidget.tsx",
    "./src/MiniCart.tsx",
    "./src/hooks/useCart.ts"
  ],
  "platform": "browser"
}

The name field is validated at load time by the CLI. If you omit it or provide a non-string value, knitkit build throws immediately with the message knit.config.json: "name" is required. Similarly, missing or non-array shared and exposes produce descriptive errors before any build work begins.

---

knit.host.json — host type-sync config

Place knit.host.json at your host project’s root. The knitkit types sync command reads this file to know which remote manifests to fetch, where each remote’s .d.ts files live, and where to write the generated knitkit-remotes.d.ts declaration that augments @knitkit/runtime’s RemoteModules interface — giving loadRemote("checkout/CartWidget") full TypeScript types.

remotes · Array<{ name: string; manifest: string }> · required

An array of remote descriptors. Each entry needs:

• name (string) — the remote’s identifier, matching its knit.config.json name field. This becomes the key prefix in loadRemote("<name>/...") and the subdirectory name inside typesDir.
• manifest (string) — a URL (HTTP/HTTPS) or a local file path (relative to the project root) pointing to the remote’s knit.manifest.json. The CLI fetches or reads this file to discover .d.ts locations.

typesDir · string · default: "\".knitkit/types\""

The directory where knitkit types sync writes downloaded .d.ts files and the generated knitkit-remotes.d.ts declaration. The path is relative to the project root. Each remote gets its own subdirectory: <typesDir>/<remoteName>/<exposedModule>.d.ts.

After syncing, add the generated declaration to your tsconfig.json include array — for example ".knitkit/types/knitkit-remotes.d.ts" — so TypeScript picks it up.

Full example

{
  "remotes": [
    {
      "name": "checkout",
      "manifest": "https://cdn.example.com/checkout/knit.manifest.json"
    },
    {
      "name": "recommendations",
      "manifest": "./remotes/recommendations/knit.manifest.json"
    }
  ],
  "typesDir": ".knitkit/types"
}

Add your typesDir (default .knitkit/types) to .gitignore — the generated files are derived artifacts that should be regenerated on demand, not tracked in version control. Run knitkit types sync as a step in your CI pipeline (after npm install and before tsc) so type checks always reflect the latest remote API.