Skip to main content
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
@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.connect();
await client.join();

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

Joining a CollabKit room is a two step process.

​
Step 1: connect()

await client.connect();
// Socket is open, users are loaded, but current user is offline
Establishes the WebSocket connection and authenticates with the server using the JWT token.
After connect() resolves:
  • The socket is open and authenticated
  • User and room data is available via client.users and client.currentRoom
  • You can listen for user events, but the current user is still offline

​
Step 2: join()

await client.join();
// Current user is now online
// Other clients receive a 'userJoined' event
Sets the current user as online in the room and notifies other participants.
After join() resolves:
  • User now has access to all features: Stores, Brodcasts, Presence and more.
  • User is now online and visible to other members connected to the room.

​
Step 3: 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:
ModulePropertyDescription
Usersclient.usersTrack all users in the room
Roomclient.roomRoom operations and connection lifecycle
Presenceclient.presenceEphemeral state (cursors, selections)
Broadcastsclient.notificationsCustom event broadcasting
Storesclient.storesSchema-driven KV stores
Commentsclient.commentsThreaded comments
Storageclient.storageFile upload and management

​
Next Steps

Client SDK Reference

Full API reference for all SDK modules.

Guides & Examples

Build a cursor tracking experience and more.