> ## Documentation Index
> Fetch the complete documentation index at: https://knitkit.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# knitkit CLI Reference: build, types, and validate commands

> Reference for every knitkit CLI command — build, types generate, types sync, and validate — with flags, output structure, and example output.

The knitkit CLI (`@knitkit/cli`) automates the build-side half of module federation: it bundles each shared package to an ESM asset via esbuild, copies your exposed modules, computes sha384 SRI hashes, writes `dist/knit.manifest.json`, and provides separate subcommands for generating TypeScript declarations from your exposed modules and syncing types from remote manifests into your host application. Install it as a development dependency and run commands from the root of your federated micro-frontend.

```bash theme={null}
npm i -D @knitkit/cli
```

All commands accept an optional `[cwd]` argument that overrides the working directory. When omitted, the current working directory is used.

***

## `knitkit build [cwd]`

`knitkit build` reads `knit.config.json` from the project root, bundles each package listed in `shared` to a self-contained ESM file using esbuild, copies each path listed in `exposes` into `dist/exposes/`, computes a `sha384` SRI hash for every shared asset, and writes the completed `dist/knit.manifest.json`.

### `knit.config.json` fields

The build command reads its configuration from `knit.config.json` in the working directory.

| Field      | Type                    | Required | Description                                                                         |
| ---------- | ----------------------- | -------- | ----------------------------------------------------------------------------------- |
| `name`     | string                  | yes      | The remote's logical name — must match `[a-z][a-z0-9_-]*`. Becomes `manifest.name`. |
| `shared`   | string\[]               | yes      | Package names (e.g. `["react", "react-dom"]`) to bundle as shared ESM assets.       |
| `exposes`  | string\[]               | yes      | Relative file paths (e.g. `["src/CartWidget.tsx"]`) to copy into `dist/exposes/`.   |
| `platform` | `"browser"` \| `"node"` | no       | Target platform for esbuild. Defaults to `"browser"`.                               |

### Output structure

```
dist/
├── shared/
│   ├── react-18.3.1.js          # bundled ESM for each shared package
│   └── react-dom-18.3.1.js
├── exposes/
│   └── CartWidget.js            # copied exposed module files
└── knit.manifest.json           # the completed manifest
```

* **`dist/shared/<pkg>-<version>.js`** — esbuild output for each shared package, named with the installed version so URLs are cache-safe.
* **`dist/exposes/<file>`** — a direct copy of each path declared in `exposes`, preserving the filename.
* **`dist/knit.manifest.json`** — the completed manifest with `spec`, `name`, `exposes`, `shared` (including SRI `integrity` for each shared asset), and a `meta` block with `buildTime` and detected `framework`.

### Example

```bash theme={null}
knitkit build
# knitkit: wrote /project/dist/knit.manifest.json
```

Example manifest output:

```json theme={null}
{
  "spec": "0.1",
  "name": "checkout",
  "exposes": {
    "./CartWidget": {
      "url": "./exposes/CartWidget.js"
    }
  },
  "shared": {
    "react": {
      "version": "18.3.1",
      "requiredVersion": "^18.3.1",
      "singleton": true,
      "url": "./shared/react-18.3.1.js",
      "integrity": "sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9r7jQfbYyF3sD5nK8n+dvY3nK0O2uP0kQ=="
    }
  },
  "meta": {
    "buildTime": "2026-06-12T18:00:00.000Z",
    "framework": "react@18"
  }
}
```

<Note>
  `requiredVersion` is automatically set to `^<version>` (caret range) by the build command. If you need a stricter or looser range, edit the manifest after building or patch it in your deployment pipeline.
</Note>

***

## `knitkit types generate [cwd]`

`knitkit types generate` uses the project's installed TypeScript compiler to emit a `.d.ts` declaration file for each exposed module and writes the files to `dist/types/`. It then patches `dist/knit.manifest.json` in place, setting the `types` field on each matching `exposes` entry to point at the generated declaration.

Run this command after `knitkit build`, since it reads and patches the manifest that `build` produces.

```bash theme={null}
knitkit types generate
# knitkit: generated 2 declaration file(s) in dist/types
```

### Output

```
dist/
├── types/
│   ├── CartWidget.d.ts           # emitted declaration for ./CartWidget expose
│   └── CheckoutForm.d.ts
└── knit.manifest.json            # patched: exposes[].types populated
```

The patched manifest entry looks like:

```json theme={null}
"./CartWidget": {
  "url": "./exposes/CartWidget.js",
  "types": "./types/CartWidget.d.ts"
}
```

<Note>
  `knitkit types generate` requires `typescript` to be installed in your project. Install it with `npm i -D typescript` if it is not already present. The command uses the TypeScript compiler API directly — no `tsconfig.json` is required, though one is respected if present in your project.
</Note>

***

## `knitkit types sync [cwd]`

`knitkit types sync` reads `knit.host.json` from the working directory, fetches each listed remote's manifest, downloads the `.d.ts` files referenced in each `exposes[].types` field, and writes a `knitkit-remotes.d.ts` declaration that augments the `RemoteModules` interface in `@knitkit/runtime`. After syncing, `loadRemote("checkout/CartWidget")` returns a properly typed value.

```bash theme={null}
knitkit types sync
# knitkit: synced 3 remote type file(s); wrote .knitkit/types/knitkit-remotes.d.ts
```

### `knit.host.json` fields

| Field      | Type                                        | Required | Description                                                                                          |
| ---------- | ------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `remotes`  | `Array<{ name: string; manifest: string }>` | yes      | Each entry gives a remote's logical name and a URL or local path to its `knit.manifest.json`.        |
| `typesDir` | string                                      | no       | Where to write downloaded `.d.ts` files and the generated declaration. Defaults to `.knitkit/types`. |

Example `knit.host.json`:

```json theme={null}
{
  "remotes": [
    { "name": "checkout", "manifest": "https://cdn.example.com/checkout/knit.manifest.json" },
    { "name": "recommendations", "manifest": "https://cdn.example.com/recs/knit.manifest.json" }
  ]
}
```

### Output

```
.knitkit/
└── types/
    ├── checkout/
    │   └── CartWidget.d.ts         # downloaded from remote manifest
    ├── recommendations/
    │   └── ProductCard.d.ts
    └── knitkit-remotes.d.ts        # augments RemoteModules
```

The generated `knitkit-remotes.d.ts` looks like:

```ts theme={null}
// AUTO-GENERATED by `knitkit types sync`. Do not edit.
import type R0 from "./checkout/CartWidget";
import type R1 from "./recommendations/ProductCard";
declare module "@knitkit/runtime" {
  interface RemoteModules {
    "checkout/CartWidget": R0;
    "recommendations/ProductCard": R1;
  }
}
export {};
```

Add the `typesDir` directory to your `tsconfig.json` `include` array so TypeScript picks up the augmentation:

```json theme={null}
{
  "include": ["src", ".knitkit/types"]
}
```

<Note>
  Only remotes whose `exposes` entries include a `types` field are synced. Run `knitkit types generate` on your remote project first to populate that field.
</Note>

***

## `knitkit validate <manifest>`

`knitkit validate` reads a manifest JSON file from disk and validates it against the knitkit manifest spec using the same `validateManifest` function that `@knitkit/runtime` uses at runtime. Use it in CI pipelines or pre-deploy checks to catch manifest errors before they reach the browser.

```bash theme={null}
knitkit validate <manifest>
```

<ParamField body="manifest" type="string" required>
  Path to the manifest file to validate (e.g. `dist/knit.manifest.json`).
</ParamField>

### Exit codes

| Code | Meaning                                                           |
| ---- | ----------------------------------------------------------------- |
| `0`  | The manifest is valid.                                            |
| `1`  | The manifest is structurally invalid (failed `validateManifest`). |
| `2`  | Usage error — missing `<manifest>` argument or unknown command.   |

### Example output

Successful validation:

```bash theme={null}
$ knitkit validate dist/knit.manifest.json
knitkit: dist/knit.manifest.json is valid
```

Failed validation:

```bash theme={null}
$ knitkit validate dist/knit.manifest.json
knitkit: Manifest at dist/knit.manifest.json shared["react"].version "latest" is not a valid version.
  suggestion: Use an exact "x.y.z" version (the installed version of the package).
```

<Tip>
  Add `knitkit validate dist/knit.manifest.json` as a step after `knitkit build` in your CI workflow. It catches version string errors, missing required fields, and spec mismatches before the manifest is deployed.
</Tip>