# @kazzle/app

The one versioned package for building Kazzle apps. It owns the app-facing
TypeScript contracts, tool helpers, the Vite preview helper, app templates, and
server/CLI-only app migrations.

This file is the ownership doc referenced by the code comments in this package
and in the server. Read it before changing exports, templates, or the
compatibility policy.

## Why this package exists

App contracts used to be copied into every generated app repo as vendored files
(`kazzle.types.ts`, `kazzle.vite.ts`). Copies drift, can't be versioned, and give
the AI stale types. This package replaces the copies with real imports:

```ts
import { defineConfig } from '@kazzle/app';
import { defineTools } from '@kazzle/app/tools';
import { kazzleAppVite, kazzleAppPwa } from '@kazzle/app/vite';
import { registerAppSW } from '@kazzle/app/pwa';
```

## Subpath exports — keep them separate

One npm package, one version, many subpaths. The split is a hard contract, not a
convenience: process apps that only need tools must not pull in Vite/plugin code,
and the root export must stay tiny and dependency-free.

| Subpath | Owns | Runtime deps |
|---|---|---|
| `@kazzle/app` | `defineConfig`, `KazzleConfig` + component/trigger/env types | none |
| `@kazzle/app/tools` | `defineTools`, `KazzleTool` types, Zod input helper types | `zod` (peer, type-only) |
| `@kazzle/app/client` | install-scoped client: per-install secrets, sibling component URLs | none |
| `@kazzle/app/vite` | `kazzleAppVite` + `kazzleAppPwa` (HOST/PORT + production SW plugins) | `vite` (peer), `vite-plugin-pwa` |
| `@kazzle/app/pwa` | `registerAppSW()` browser registration (owns `virtual:pwa-register`) | none (virtual module at build) |
| `@kazzle/app/templates` | programmatic template manifest + asset readers (server/generator only) | none |
| `@kazzle/app/migrations` | versioned app upgrade metadata + codemods (server/CLI only) | none |

To add an export: add the `src/*.ts` file, add it to `exports` in
`package.json`, and document it in the table above.

## Build model — source in dev, dist on npm

- Workspace consumers (server, tests, typecheck) resolve `exports` → raw `.ts`
  source. Bun and `tsc` read TS directly, so there is no build step for the
  monorepo. This mirrors `@kazzle/framework`.
- The published package resolves package `exports` → compiled `dist/*.js`
  + `dist/*.d.ts`, because apps installed from npm need JS + types.
- `bun run build` (`scripts/build.ts`) emits `dist/`; templates ship directly
  from the package `templates/` directory.
- Templates ship as package assets (`files: ["dist", "templates"]`) so the
  server generator reads the exact versioned template for every app it creates.

## Package size

Templates are package assets, not runtime imports. A generated app that imports
`@kazzle/app`, `@kazzle/app/tools`, or `@kazzle/app/vite` only loads that
subpath. Keep templates source-only and avoid generated artifacts so the npm
tarball stays small; use `npm pack --dry-run` when adding large files.

## Versioning

`@kazzle/app` shares the root Kazzle version during pre-launch (`package.json`
`version` mirrors the repo root). CI's version-bump job syncs it before pack +
publish. Splitting into independent semver waits until there is a real
post-launch reason. See `documents/cicd.md`.

## Compatibility

Publish/check enforcement lives on the server in
`server/apps/apps.sdk-compat.ts` (supported / deprecated / blocked ranges +
migration command). Docs are not the enforcement layer.