ADR 022: JavaScript SDK package architecture
- Status: Accepted
- Owner: Eng lead
- Date: 2026-11-13
Context
The JavaScript SDKs must cover vanilla browsers, React, Next.js, TanStack Start and Router, and Node.js backends without reimplementing what LiveKit already maintains. Four packages exist: @lynkoria/contracts, @lynkoria/client, @lynkoria/react and @lynkoria/server. The question was whether to add framework packages (for example @lynkoria/next), wrap LiveKit's server SDK, or ship a dual ESM/CommonJS build.
Options considered
- One package per framework (
@lynkoria/next,@lynkoria/tanstack). Each would mostly re-export@lynkoria/reactand add a token route; versions multiply and drift. - Subpath exports (
@lynkoria/react/next). Smaller, but the framework-specific code is a few lines of the app's own server code (a Route Handler or server function calling@lynkoria/server), which a package cannot own because it holds the app's service key and authorization rules. - Shared core plus documented, tested patterns per framework. No new packages; framework guides show idiomatic server and client code and are backed by an example app with browser tests.
For the server SDK: wrapping livekit-server-sdk was rejected because product backends never hold LiveKit secrets. The Lynkoria API creates rooms and mints LiveKit tokens; the server SDK is a typed client for that API plus webhook verification.
For module format: a dual build risks the dual-package hazard (two copies of module state). Node 22.12 and later load ES modules from require().
Decision
@lynkoria/clientstays the framework-independent core: messaging, presence, typing, push registration and calls. It builds onlivekit-client, loaded lazily on the firstcalls.join, and exposes the LiveKitRoom(session.room) instead of re-abstracting tracks.@lynkoria/reactprovides a provider and hooks over the client. For call UI, apps passsession.roomto@livekit/components-react(RoomContext); Lynkoria does not wrap LiveKit components. The entry is marked"use client"so Next.js Server Components can import from it only through client boundaries.@lynkoria/serveris the Node.js client for the API (rooms, tokens, moderation, conversations, notifications, recordings) and verifies webhooks. It has no browser code and must only run on servers.- Next.js, TanStack Start and TanStack Router get guides and a tested example, not packages (option 3).
- ESM only. Every package's
exportsmap has adefaultcondition sorequire()works on Node 22.12 and later. No dual build. - Peer ranges stay broad (
react ^18.2.0 || ^19.0.0) and are tested against the latest versions throughdevDependencies.
Consequences
- Fewer packages to version; framework guidance can change without a release.
- Framework support is only as good as its example's tests; until the example app exists, the capability matrix lists Next.js and TanStack as planned.
- CommonJS consumers on Node versions older than 22.12 must use dynamic
import().