Skip to content

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.