Reference

Stability tiers

Know which entry points are safe to depend on before 1.0, and which ones can change under you without notice.

Three tiers

Clivly is pre-1.0. Every published entry point sits in one of three tiers, so you can tell which imports are safe to build on before you depend on them.

1 · Stable — Breaking changes only in a major release. clivly/sdk — createClivlySDK, createChatSessionHandler, defineClivlyConfig, the error classes.

2 · Beta — May change in a minor, but only after a deprecation cycle. clivly/drizzle, clivly/vite, and the three clivly/auth/* adapters.

3 · Internal — No guarantee at all — may change or vanish in a patch. clivly/internal and everything under it.

Import from the right place

The rule that catches people out: the package root is not a library import.

imports.ts
// Tier 1 — stable. Breaking changes only in a major.
import { createClivlySDK, createChatSessionHandler } from "clivly/sdk";

// Tier 2 — beta. May change in a minor, with deprecation first.
import { fromDrizzle } from "clivly/drizzle";
import { createClerkAuthAdapter } from "clivly/auth/clerk";

// Tier 3 — internal. No guarantee, may change in a patch.
import { compileEntityView } from "clivly/internal/view-compiler";

// Never do this. The package root is the CLI binary, not a library —
// it imports node:fs / node:child_process at module scope and throws
// on Workers and other edge runtimes.
// import clivly from "clivly";
  • clivly/sdk is the supported runtime import path. The clivly package root is the CLI binary — importing it from app code throws on Workers and other edge runtimes.
  • clivly/core/* still resolves but is deprecated in favour of clivly/internal/*; it emits a one-time process warning naming the replacement.
  • Deprecation warnings use process.emitWarning, so they stay off stdout and cannot corrupt machine-readable CLI output.