JavaScript SDK
Learn Celeris step by step with browser and Node examples, then look up the exact client and server APIs.
Start with the Quickstart for a complete two-tab messaging application. You do not need a frontend framework.
Each channel connection automatically joins a segment named default. Access it with channel.defaultSegment(). That stream does not need an explicit subscription. Use additional named segments when you need separate topics. Messaging explains the listener and permission setup.
Two packages
@useceleris/clientmanages connections, messages, subscriptions, and presence in browsers, Node.js, Bun, and Deno.@useceleris/serversigns credentials from your application's access decisions. It runs on trusted servers only.
npm install @useceleris/client
npm install @useceleris/server
Install the server package only in projects with trusted server code. Never import it into a browser entry point. It depends on the client for types only. The client does not include signing facilities.
The current versions are @useceleris/client 1.1.0 and @useceleris/server 1.0.0. The server package accepts any client version in the ^1.0.0 range. See the Changelog.
Minimum supported versions are Node.js 22.15, Bun 1.3, and Deno 2.5. Celeris tests the client in browsers on the Chromium, Firefox, and WebKit engines, and in Chrome and Edge. Celeris does not test Safari releases separately. The client needs native WebSocket, BigInt, TextEncoder/TextDecoder, URL, AbortController, and crypto.getRandomValues. The packages provide ESM and CommonJS entry points and TypeScript declarations.
The Quickstart uses Node 24.15+ in the 24.x line and Vite to build a browser application. Install the packages from npm. You do not need an SDK repository checkout or a build step.
Follow the guides
- Quickstart: create every file and exchange your first message.
- Authentication: replace the local demo identity before deployment.
- Connection and lifecycle: connect, observe state, retry, and clean up.
- Messaging: subscribe, send, receive, and understand delivery.
- Payload formats: text, validated JSON, and custom serializers.
- Presence: list connections and watch presence events.
- Errors and troubleshooting: handle failures where the SDK reports them.
- Server-side usage: publish or receive from a trusted backend.
Read Reconnection and Recovery for the shared explanation of retries, replay, and application reconciliation. Exact signatures live in the Client API and Server API.
Work with SDK values
Use JavaScript numbers for pagination, presence counts, timeouts, and recovery timing. For example, request { page: 1, perPage: 25 } and compare the returned total directly with 0.
Timestamps delivered with messages, notices, and presence are bigint values. The bigint type keeps their full 64-bit precision. Convert those timestamps to decimal strings when you write JSON. Do not convert counts to bigint. Server error resources can contain either numeric type. Payload formats shows serialization, and Presence shows pagination.
Vocabulary
| Term | Meaning |
|---|---|
| Channel reference | Name of a communication space inside your application |
| Channel handle | Owns one connection once connected |
| Segment | Named stream carried over that channel's socket |
| Listener | Your callback for an event. Registration returns a disposer |
| Subscription | Held interest in messages or presence. Release it with cancel() |
| Credential provider | Your function that obtains fresh signed access for each connection attempt |