> ## Documentation Index
> Fetch the complete documentation index at: https://docs.collab-kit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Overview

> Install and initialize the CollabKit browser SDK.

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

<CodeGroup>
  ```bash npm theme={null}
  npm install @collab-kit/client @collab-kit/utils
  ```

  ```bash pnpm theme={null}
  pnpm add @collab-kit/client @collab-kit/utils
  ```

  ```bash yarn theme={null}
  yarn add @collab-kit/client @collab-kit/utils
  ```
</CodeGroup>

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

## Initialization

```typescript theme={null}
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

```typescript theme={null}
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 */ }),
});
```

<ParamField body="serverUrl" type="string" required>
  Base HTTP(S) URL of your CollabKit server. The SDK automatically derives the WebSocket URL from this.
</ParamField>

<ParamField body="authToken" type="string" required>
  JWT token returned when [creating a user](/api-reference/users/create-user) via `POST /users`. Contains the `accountId`, `userId`, and `roomId`.
</ParamField>

<ParamField body="stores" type="[StoresConfig](/types/stores#storesconfig)">
  (Optional) You must pre-define store schemas with [`defineStores()`](/sdk/stores#schema-definition). during initialization. Each client instance has access to the stores that are passed to it during initialization.
</ParamField>

## User Lifecycle

### Step 1: `join()`

```typescript theme={null}
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. <br />
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:

```typescript theme={null}
await client.join({ role: 'viewer' });
await client.updateRole('editor');
```

### Step 2: `disconnect()`

```typescript theme={null}
await client.disconnect();
// Other clients receive a 'userLeft' event
```

Gracefully disconnects. Notifies other participants before closing the socket.

<Tip>
  Call `disconnect()` in the `beforeunload` event to notify peers when the tab closes:

  ```typescript theme={null}
  window.addEventListener('beforeunload', () => {
    void client.disconnect();
  });
  ```
</Tip>

## Modules

The client provides access to collaboration features through modules:

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Client SDK Reference" icon="code" href="/sdk/overview">
    Full API reference for all SDK modules.
  </Card>

  <Card title="Guides & Examples" icon="book-open" href="/guides/cursor-tracking">
    Build a cursor tracking experience and more.
  </Card>
</CardGroup>