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 app. No frontend framework is required.
Each channel connection automatically joins a segment named default. Access it with channel.defaultSegment(); no explicit subscription is needed for that stream. 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.
Minimum supported versions are Node.js 22.15, Bun 1.3, Deno 2.5, Chrome/Edge 120, Firefox 121, and Safari 17. The client needs native WebSocket, BigInt, TextEncoder/TextDecoder, URL, and AbortController. ESM and CommonJS entry points and TypeScript declarations are provided.
The Quickstart uses Node 24.15+ in the 24.x line and Vite to build a browser app. Install the packages from npm; no SDK repository checkout or build step is required.
Follow the guides
- Quickstart: create every file and exchange your first message.
- Authentication: replace the local demo identity before deployment.
- Connecting 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 local presence events.
- Errors and troubleshooting: handle failures where they are reported.
- 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.
Working 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 so their full 64-bit precision is preserved. Convert those timestamps to decimal strings when writing 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 app |
| 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 |