Skip to main content
KhalOS uses two package managers on purpose. The SDK workspace (the @khal-os/* packages you’ll import into your pack) is a pnpm monorepo. Each pack-* repo (including pack-template) is a bun workspace. Knowing which tool runs where is the only setup detail that trips up first-time contributors.

​
TL;DR

pnpm

For the @khal-os/* SDK workspace. pnpm install, pnpm build, pnpm typecheck, pnpm lint.

bun

For every pack-* repo (the scaffold you clone from pack-template). bun install, bun run build, bun run typecheck.

​
Node version

Install Node 20 or newer. The @khal-os/* packages target modern Node and bun itself installs cleanly on 20.x. If you use nvm, run nvm use inside any repo that ships an .nvmrc. 
node --version   # v20.x or newer
pnpm --version   # any recent release
bun --version    # 1.x

​
The SDK workspace — pnpm

The SDK workspace ships the four framework packages your pack will depend on: @khal-os/sdk, @khal-os/ui, @khal-os/types, and @khal-os/dev-cli. It uses pnpm and Turbo under the hood. 
pnpm install        # install workspace deps
pnpm build          # turbo run build — build every package
pnpm typecheck      # turbo run typecheck across the workspace
pnpm lint           # biome check
pnpm lint:fix       # biome check --write .
You usually don’t need to run these yourself: the packages publish from CI to GitHub Packages, and your pack consumes them as ordinary npm dependencies. Install them here only if you’re debugging an SDK issue or running a local snapshot of the SDK against your pack.

​
Pack repos — bun

Every pack-* repo — including the scaffold you clone from pack-template — uses bun as both its package manager and its runtime. bun install is fast, workspaces are first-class, and the included bundler already matches the toolchain the template expects. 
bun install         # install pack deps
bun run build       # build the frontend package
bun run typecheck   # type-check all workspaces
bun run lint        # biome lint
bun run test        # run tests (if present)
Don’t cross the streams. Running pnpm install inside a pack-* repo, or bun install inside the SDK workspace, will produce a lockfile the other tool ignores — and the next person on the repo will have to untangle it. When in doubt, check which lockfile is already committed.

​
Verifying your setup

After you’ve cloned the workspace, pick one of each and confirm both install cleanly:
1

SDK workspace

cd repos/app-kit
pnpm install && pnpm build
pnpm build should finish with every package green in the Turbo summary.
2

A reference pack

cd repos/pack-template
bun install && bun run build
bun run build should emit CJS + ESM + .d.ts outputs into package/dist/.
Split terminal showing pnpm install in app-kit on the left and bun install in pack-template on the right, both finishing green.

​
Next steps

Build your first pack

Scaffold a new pack from pack-template, rename the five files, and get a “Hello FDE” component shipping.

Pack anatomy

A directory-level tour of everything inside a pack — manifest, frontend package, backend service, Helm chart, CI.