◆ KOVO
Star
Menu

Getting Started

View as Markdown

Installation

If you just want to get a page on screen fast, start with the Quickstart. This page covers prerequisites, scaffold options, generated files, and the two command surfaces Kovo projects use.

Prerequisites#

  • Node.js 22.15+ - the minimum Node line supported by the current toolchain. Repository automation enables Node's transform-types flag where workspace source TS is loaded directly.
  • pnpm 10+ - the workspace package manager.
  • TypeScript, strict - Kovo's correctness guarantees are guarantees about TypeScript programs that stay inside the sound subset. The starter ships strict TypeScript because the compiler can only prove handler, form, route, and data-binding facts about code that keeps those facts typed.

Scaffold a project#

sh
pnpm create kovo my-app
cd my-app
pnpm install

The default starter uses PGlite with Drizzle's Postgres dialect. SQLite is still experimental and single-principal/local-dev only, so opt into it explicitly:

sh
pnpm create kovo my-app -- --dialect sqlite --experimental-sqlite

The CLI accepts:

create-kovo <target-directory> [--name <package-name>] [--dialect postgres|sqlite] [--disable-git]

--postgres and --sqlite are accepted aliases. --sqlite still requires --experimental-sqlite. This acknowledgement must be on the command line; ambient environment state cannot select the weaker single-principal posture. The target directory must be empty when it already exists; the command refuses to merge into a non-empty app. By default, create-kovo initializes a Git repository after writing the scaffold. Pass --disable-git to skip that. If the target is already inside a Git or Mercurial repository, the command does not create a nested Git repository.

Pre-v1: not on npm yet. These commands describe the intended flow and work today inside the Kovo repository as workspace packages - clone the repo and work in a workspace member, as the Tutorial does.

What the starter writes#

The scaffold is intentionally real, not a blank page. It writes:

  • Better Auth over the same Drizzle database as app data.
  • A session provider, sign-in/sign-out mutations, and anonymous-to-session CSRF binding.
  • A guarded home route plus /login.
  • A contact schema, seeded database, typed contact query, and guarded add-contact mutation.
  • Styled UI components, theme tokens, document CSS, Vitest coverage, Vite/Kovo config, and CI.
  • .env.example, .gitignore, and a gitignored .env with a fresh local CSRF secret.
  • A Git repository for the new app, unless you passed --disable-git or scaffolded inside an existing Git/Mercurial repository.

The generated .env is for local development only. Set BETTER_AUTH_SECRET or KOVO_CSRF_SECRET to a strong deployment secret before serving the app outside your machine.

The everyday commands#

This is the authoritative command table; the Quickstart links here rather than repeating it.

Command What it does
npm run dev Bootstrap-first Kovo dev server (kovo dev ./src/app.tsx).
npm run check kovo check: format, lint, type, sound-subset, compiler, and current-source proof.
npm run check:endpoint-posture After build, exercises the emitted server and checks its declared endpoint fixtures.
npm run test kovo test: Vitest suites with Kovo's bootstrap ordering.
npm run build:prod Production build through kovo build ./src/app.tsx.
npm start Run the emitted Node server from dist/server/server.mjs.

One app-facing command surface#

Kovo owns development, checks, tests, builds, graph inspection, and copy-in commands such as kovo add. Vite Plus remains a pinned implementation dependency rather than an app-facing workflow. The CLI guide covers the complete Kovo surface.

If you internalize one command, make it npm run check. It proves handler references, form fields, navigation targets, data-binding paths, the sound TypeScript subset, and the current compiler/security graph. The deployment-backed endpoint-posture audit follows a successful npm run build:prod.

Spec & diagnostics

The framework-owned sound-subset classifier enforces the app-authored subset Kovo relies on for SPEC §6.6 client-capture and sink guarantees. After build, npm run check:endpoint-posture runs the production probe and validates its .kovo/endpoint-posture.json facts through one kovo check endpoint-posture command.

Which primitive comes from which package#

Newcomers trip on import paths before anything else. The split is small and stable:

Primitive Package What it is
route, query, mutation, s, domain, guards, session @kovojs/server server-side facts: routes, typed reads/writes, schemas, domains, guards, sessions
component, form @kovojs/core the component model and form helpers used in TSX
Better Auth adapters and guards @kovojs/better-auth session adaptation and auth mutations backed by Better Auth
Drizzle extraction helpers @kovojs/drizzle query/write metadata the compiler can audit
Styled UI components @kovojs/ui/* public component subpaths, also available through kovo add copy-in

The mental model and Queries chapter repeat this inline where the primitives first appear.

Where to go next#