◆ KOVO
Star
Menu

Getting Started

View as Markdown

Stability & Versioning

This page answers "is this safe to depend on?". The full policy lives in STABILITY.md at the repo root; this is the short version.

What counts as public#

A symbol is supported public API only if both hold:

  1. it is exported from a package marked public in public-packages.json, and
  2. it is reachable from that package's published exports and is documented (not tagged @internal).

Everything else — private packages, @internal exports, and raw ./src/** — is internal and may change without notice. A CI gate (scripts/api-surface-gate.mjs) and this site's generated API reference keep that line visible.

Public vs internal packages#

Public (depend on these) Internal / special
@kovojs/core, @kovojs/server, @kovojs/browser, @kovojs/drizzle (the real-database data layer — see the data-layer guide) @kovojs/compiler — framework build machinery used behind the kovo CLI; app projects should run kovo compile, kovo check, or kovo explain, not import compiler APIs
@kovojs/better-auth — the Better Auth integration: credential mutations and session forwarding; @kovojs/headless-ui — accessible behavior/attribute builders for UI primitives (see Components & copy-in UI) @kovojs/test — test harness helpers for Kovo apps and packages
@kovojs/style, @kovojs/ui — versioned styled component subpaths such as @kovojs/ui/button; use kovo add only when you want copied source to become app-owned code
@kovojs/cli, create-kovo (CLIs — the kovo executable contract, plus @kovojs/cli's one-shot runKovoCommand facade and kovoCheck/kovoExplain)

Versioning#

Public packages follow SemVer. On the current 0.x line the API is stabilizing: minor bumps may break, patch bumps never do, and every breaking change is in the release notes. At 1.0.0 the standard guarantee applies. Surface that ships before it's frozen is marked experimental_ / @experimental and is exempt until the marker is removed.

The 0.3 line is the cumulative API v1 cut. Run kovo fix api-v1 --check before changing package versions, resolve every refusal, then run kovo fix api-v1 --write. Kovo does not retain preview-era compatibility barrels for the replaced API. The CLI guide shows the migration and links the task-by-task release notes. After 1.0.0, removal requires a deprecation cycle that names the replacement.

Distribution#

Published packages ship built dist/ (JavaScript + rolled-up .d.ts), so depending on Kovo does not couple you to the monorepo's tsconfig. The @internal boundary is enforced by the generated API reference and api-surface gate; rolled-up declarations may still contain implementation details.

Import boundaries#

Use the public roots and subpaths that appear in the generated API reference and public-packages.json. Do not import private packages, @internal symbols, raw ./src/**, or compiler-emitted runtime ABI such as @kovojs/browser/generated.

Author-authored browser helpers come from @kovojs/browser. The @kovojs/browser/client subpath contains one experimental installKovoClient API for a custom application shell. Compiler-built apps and ordinary components do not import it. @kovojs/headless-ui has no public root import; import primitive behavior from subpaths such as @kovojs/headless-ui/select or @kovojs/headless-ui/dialog. @kovojs/ui keeps component symbols on direct component subpaths such as @kovojs/ui/button. The root @kovojs/ui entry intentionally exports no components.

create-kovo is a public CLI package, not an app import surface.

Next#

Spec & diagnostics

Public API boundary, authorable TSX source requirement, and generated/internal separation: SPEC §5.2. Additional package-level policy lives in STABILITY.md and public-packages.json.