Skip to main content
This page is the full local dev and testing loop for a pack. It assumes you have a pack already scaffolded — if not, start at Your first pack.

​
Build and watch

From the pack repo root: 
bun run build
The build produces CJS + ESM + .d.ts outputs into package/dist/. The publish pipeline only ships what’s under package/.

​
Typecheck and lint

bun run typecheck
Both run through Biome under the hood. Fix on save is usually enough.

​
Unit tests

Vitest is the default. A tiny NATS mock is enough for most frontend tests: 
import { describe, it, expect, vi } from 'vitest';
import { render } from '@testing-library/react';
import TerminalPack from '../src';

vi.mock('@khal-os/sdk', () => ({
  useNats: () => ({
    publish: vi.fn(),
    subscribe: vi.fn((_subject, _cb) => () => {}),
  }),
}));

describe('TerminalPack', () => {
  it('renders an empty terminal', () => {
    const { container } = render(<TerminalPack />);
    expect(container.firstChild).toBeTruthy();
  });
});
Run tests: 
bun run test

​
Integration tests

For full-stack packs, a lightweight integration test talks to your service over a local NATS instance:
1

Start a local NATS

Any NATS server will do — e.g., nats-server -js if you have it installed, or a Docker one-liner.
2

Point your service at it

Set KHAL_NATS_URL=nats://localhost:4222 when running the service in test mode.
3

Publish and assert

From a test harness, publish on your service’s input subject and assert on its output subject.

​
The khal-dev QA CLI

The @khal-os/dev-cli package ships khal-dev — a pack-focused QA toolkit. Subcommands live under app-kit/packages/dev-cli/src/commands/. Key commands:
  • khal-dev app-create — scaffold a new pack (alternative to gh repo create --template).
  • khal-dev qa <sub> — the QA family. Inspect app-kit/packages/dev-cli/src/commands/qa/ for the current list of sub-checks; khal-dev qa --help on your installed copy is authoritative.
The exact QA subcommand list evolves with the toolchain. Run khal-dev qa --help for the live list rather than memorizing it.

​
Debug tips

Frontend: DevTools

The shell runs in a browser (or Tauri WebView). F12 opens DevTools — console, network, React DevTools all work.

Service: container logs

docker logs -f <container> while running the service via docker run locally. In a deployed instance, logs flow through the platform’s standard log pipeline — your customer admin knows how to read them.

NATS traffic: pack-nats-viewer

The reference pack-nats-viewer app lets you see subjects flowing through your pack’s namespace. Invaluable for debugging message plumbing.

Manifest validation

khal-app.json is validated by @khal-os/types. If the SDK complains at build time, the error points at the exact path in your manifest.
khal-dev qa output during a local test run

​
What’s next

Publish your pack

Push → CI builds → publish.

khal-app.json reference

The full manifest schema.