Distribution
How @kortix/sdk ships: npm, the CDN ESM bundle, the window.Kortix script global, version lockstep with platform releases, and the entry-point stability tiers.
npm (the default)
npm install @kortix/sdkThe published package is compiled ESM (dist/) with full type declarations.
react and @tanstack/react-query are optional peer dependencies — install
them only if you use @kortix/sdk/react.
import { createKortix } from '@kortix/sdk'; // framework-free core
import { useSession } from '@kortix/sdk/react'; // optional React layer
import { createScopedKortix } from '@kortix/sdk/server'; // Node servers (async_hooks)CDN — no build step
Two browser bundles ship with the package, mirrored automatically by unpkg and jsDelivr:
ESM (dist/kortix.esm.min.js, the package's browser field) — for
<script type="module"> and import maps:
<script type="module">
import { createKortix, classifyTurn } from 'https://unpkg.com/@kortix/sdk/dist/kortix.esm.min.js';
</script>IIFE global (dist/kortix.global.js — what a bare
https://unpkg.com/@kortix/sdk resolves to, via the package's unpkg /
jsdelivr fields) — a single <script> tag that defines window.Kortix:
<script src="https://unpkg.com/@kortix/sdk/dist/kortix.global.js"></script>
<script>
const kortix = Kortix.createKortix({
backendUrl: 'https://api.kortix.com/v1',
getToken: async () => KEY,
});
</script>window.Kortix is the root entry — Kortix.createKortix,
Kortix.classifyTurn, Kortix.ApiError, no namespaces. Streaming works from
the CDN bundles in any modern browser (Safari 16.4+).
Don't mix the ESM build and the IIFE global in one page — you'd get two copies of every class, and
err instanceof ApiError across the boundary silently returns false. Pick one.
Versioning — lockstep with the platform
The SDK version is stamped from the platform release at publish time; the SDK
ships in lockstep with the Kortix platform. There is no separate SDK
release train — a platform release publishes the matching SDK. Pin a version
or use ^ as you prefer; the API surface follows semver, enforced by a
committed public-surface snapshot asserted in CI (any rename or removal of an
exported name must land as a reviewed, deliberate diff).
Entry points and their stability tiers
The root entry is canonical. Since v2, everything framework-free is
exported from @kortix/sdk itself — one flat, discoverable surface. The
supported entry points:
| Entry | Tier | Contract |
|---|---|---|
@kortix/sdk | canonical | The full framework-free surface. Runs in browsers, Node ≥ 18, Bun, and edge runtimes. Never imports React or node:*. |
@kortix/sdk/react | supported | The React hooks layer. The only entry allowed to import React. |
@kortix/sdk/server | supported | Node/Bun-only per-request config isolation (node:async_hooks). Never bundle into a browser. |
Legacy subpaths (/projects-client, /turns, /files, …) | deprecated aliases | Still work — every legacy subpath re-exports from the root — but are frozen. Import from the root instead. Removal only in a major. |
Browser store subpaths (/sync-store, /server-store, …) | internal | Plumbing consumed by the Kortix web app. Not on window.Kortix, not designed API — don't build on them. |
These guarantees are enforced mechanically, not by convention: an
import-graph tripwire fails the build if a framework or node:* import ever
reaches the core, and the public-surface snapshot catches accidental renames
before they reach a release.
What's in the tarball
npm pack contains dist/ (compiled ESM + .d.ts + CDN bundles), src/
(readable source for go-to-definition), and the README — nothing else. Repo
docs, examples, tests, and internal tooling never ship to consumers. The
publish pipeline verifies the tarball installs and imports before anything
goes out.