SDK Overview

The @collab-kit/client package is a browser SDK. It connects to your server over WebSocket and provides modules for users, rooms, presence, stores, comments, broadcasts, file storage, and CRDT collaboration.

Installation

npm install @collab-kit/client @collab-kit/utils

pnpm add @collab-kit/client @collab-kit/utils

yarn add @collab-kit/client @collab-kit/utils

@collab-kit/utils is a peer dependency that provides shared types and the defineStores() utility. Install it alongside the client.

Initialization

import CollabKitClient from '@collab-kit/client';

const client = new CollabKitClient({
  serverUrl: 'https://api.collab-kit.com',
  authToken: '<jwt-token>', // from POST /users
});

await client.join(); // defaults to { role: 'editor' }

console.log(client.currentUser);  // { id, name, status: 'online', ... }
console.log(client.currentRoom);  // { id, name, state: 'active', ... }

Constructor Options

import CollabKitClient from '@collab-kit/client';
import { defineStores } from '@collab-kit/utils';

const client = new CollabKitClient({
  serverUrl: 'https://api.collab-kit.com',
  authToken: '<jwt-token>',
  stores: defineStores({ /* optional store schemas */ }),
});

serverUrl

string

required

Base HTTP(S) URL of your CollabKit server. The SDK automatically derives the WebSocket URL from this.

authToken

string

required

JWT token returned when creating a user via POST /users. Contains the accountId, userId, and roomId.

stores

[StoresConfig](/types/stores#storesconfig)

(Optional) You must pre-define store schemas with defineStores(). during initialization. Each client instance has access to the stores that are passed to it during initialization.

User Lifecycle

Step 1: `join()`

await client.join();
// Socket opens, the JWT authenticates, the user is set online,
// active editors, comments, and stores are loaded
// Other clients receive a 'userJoined' event only for editors

join() is the single entry point. It opens the WebSocket (if not already open), authenticates with the server using the JWT token, sets the current user as online, loads active editors, comments, and stores, and notifies other participants when this session is an editor.
After join() resolves:

client.users.active is populated with active editors, excluding self
client.users.all remains empty until you call client.users.list(...)
client.currentUser and client.currentRoom are set
Comments and stores are hydrated
Editors can write collaboration state; viewers receive updates and can follow users

Join as a viewer when the user should not collaborate directly:

await client.join({ role: 'viewer' });
await client.updateRole('editor');

Step 2: `disconnect()`

await client.disconnect();
// Other clients receive a 'userLeft' event

Gracefully disconnects. Notifies other participants before closing the socket.

Call disconnect() in the beforeunload event to notify peers when the tab closes:

window.addEventListener('beforeunload', () => {
  void client.disconnect();
});

Modules

The client provides access to collaboration features through modules:

Module	Property	Description
Users	`client.users`	Track active editors and page through all users
Room	`client.room`	Room operations and connection lifecycle
Presence	`client.presence`	Ephemeral state (cursors, selections)
Broadcasts	`client.notifications`	Custom event broadcasting
Stores	`client.stores`	Schema-driven KV stores
Comments	`client.comments`	Threaded comments
Storage	`client.storage`	File upload and management

Overview

Modules

Providers

Changelog

Installation

Initialization

Constructor Options

User Lifecycle

Step 1: `join()`

Step 2: `disconnect()`

Modules

Next Steps

Client SDK Reference

Guides & Examples

​Installation

​Initialization

​Constructor Options

​User Lifecycle

​Step 1: join()

​Step 2: disconnect()

​Modules

​Next Steps

Client SDK Reference

Guides & Examples

Installation

Initialization

Constructor Options

User Lifecycle

Step 1: `join()`

Step 2: `disconnect()`

Modules

Next Steps