Start

Quickstart

From a secret key to a live event in a few minutes.

You need a project and its secret key: sign in and create both from the dashboard. Each project's Quickstart tab shows these steps with its own id filled in.

1. Install

One package: the server SDK, the browser client, and React hooks and components under /react and /ui.

Terminal
bash
npm install @anishroy/pulse

2. Keep the secret key on your server

The SDK reads both from the environment. Never ship the key to a browser: it signs tokens and publishes.

.env
bash
PULSE_SECRET_KEY=sk_<project>_<your secret key>PULSE_URL=https://api.pulse.anishroy.com

3. Hand the browser a token

One route, from your own session. Tokens list the channels a user may join, here only their own orders channel, and expire after 10 minutes; the client fetches a new one.

app/api/pulse/token/route.ts
typescript
import { createTokenRoute } from "@anishroy/pulse/server"
export const POST = createTokenRoute({ authorize: async () => { const user = await currentUser() // your session return user ? { user: { id: user.id, name: user.name }, channels: [`orders:${user.id}`] } : null },})

4. Wrap the app

Safe with server rendering: nothing touches the network during render.

app/layout.tsx
tsx
import { PulseProvider } from "@anishroy/pulse/react"
export default function Layout({ children }) { return ( <PulseProvider url="https://api.pulse.anishroy.com" auth="/api/pulse/token"> {children} </PulseProvider> )}

5. Publish from your server, read in the browser

Publish to the user's own channel, the one their token allows, and their open tabs get it live. Every event gets a sequence number and is stored before it is sent, so a reconnecting tab gets exactly what it missed.

server.ts · order.tsx
tsx
import { Pulse } from "@anishroy/pulse/server"const rt = new Pulse() // PULSE_SECRET_KEY, PULSE_URL
// When the user's order shipsawait rt.publish(`orders:${user.id}`, "order.status", { status: "shipped" })
// In a component, for the signed-in userconst status = useEvent(`orders:${user.id}`, "order.status")

6. Or publish over HTTP

From anything that can send a request, to the same channel.

Terminal
bash
# USER_ID: the user's id, as your token route signs it (user.id)curl -X POST https://api.pulse.anishroy.com/v1/channels/orders:$USER_ID/events \  -H "Authorization: Bearer $PULSE_SECRET_KEY" \  -H "Content-Type: application/json" \  -d '{ "name": "order.status", "data": { "status": "shipped" } }'

Next

Read how tokens decide who may join what, then the page for the primitive you need: Events, Presence or AI streams.