Skip to Content
LYNKORIADocs

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

  1. One package per framework (@lynkoria/next, @lynkoria/tanstack). Each would mostly re-export @lynkoria/react and add a token route; versions multiply and drift.
  2. 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.
  3. 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/client stays the framework-independent core: messaging, presence, typing, push registration and calls. It builds on livekit-client, loaded lazily on the first calls.join, and exposes the LiveKit Room (session.room) instead of re-abstracting tracks.
  • @lynkoria/react provides a provider and hooks over the client. For call UI, apps pass session.room to @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/server is 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 exports map has a default condition so require() 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 through devDependencies.

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().

On this page