Type-safe live updates
in minutes

Zero-config SSE. Shared types. Simple client & server helpers.

Test it by liking
on another window!

Features

Type-safe

Define your channels and payload once and share it between client and server.

export interface RealtimeTypes {
  'demo:likes:updated': { count: number }
}

Framework agnostic

Works with any framework.

Zero-config

Implement realtime with ease, and a few lines of code.

subscribe()

push()

Self-hostable broker

Tiny Node service with in-memory broker, no external infra (Redis/Kafka) required to get started.

ghcr.io/impulse-studio/realtime-service

Serverless-friendly

Push via stateless HTTP POST from any environment (serverless, edge, cron), no persistent connections needed server-side.

Let’s get started!

1. Define your channels and payload

export interface RealtimeTypes {
  'message': { content: string }
}

2. Subscribe on your client

First let’s install the package

npm install @impulselab/realtime

And use the `subscribe` function to listen for events on your client.

import { createRealtimeClient } from '@impulselab/realtime'
import type { RealtimeTypes } from './types'

const rc = createRealtimeClient<RealtimeTypes>({
  serviceUrl: 'http://localhost:8080'
})

rc.subscribe('message', (event) => {
  console.log(event.payload.content)
})

3. Push from your server

Then start a local service

npx @impulselab/realtime-service

And use the `push` function to send events to your clients through the service.

import { createServerClient } from '@impulselab/realtime'
import type { RealtimeTypes } from './types'

const sc = createServerClient<RealtimeTypes>({
  serviceUrl: 'http://localhost:8080',
  token: 'secret'
})

await sc.push('message', { content: 'Hello, world!' })

4. You’re done

Perfect! You’re now free to add more events to your app.

You may want more customizations, like authentication or topics.
Follow the Deep dive! section below to learn more.

Deep dive!

In order to authenticate your events you can use the token option in the subscribe function.
You can also target a specific topic by using the topic option, these basically act as rooms or groups.

// Subscribe to a message with a secret
rc.subscribe('message', (event) => {}, { token: 'secret' })

// Or from a specific topic
rc.subscribe('message', (event) => {}, { topic: 'room-42' })

// And combine both of them
rc.subscribe('message', (event) => {}, { token: 'secret', topic: 'room-42' })

On the server side, you can use the same topic option to send events to all clients subscribed to that topic.
For the authentication part

// Push a message with a secret
await sc.push('message', { content: 'Hello, world!' }, { tokens: 'secret' })

// You can also allow multiple tokens
await sc.push('message', { content: 'Hello, world!' }, { tokens: ['secret', 'other'] })

// Or target a topic
await sc.push('message', { content: 'Hello, world!' }, { topic: 'room-42' })

// And all of the above
await sc.push('message', { content: 'Hello, world!' }, { tokens: ['secret', 'other'], topic: 'room-42' })

You can customize the service by passing options to the CLI.

--port <number>

The port to listen on.

--secret <string>

The secret to authenticate your server (must be the same as the token option in the createServerClient function).

Comprehensive documentation designed specifically for AI assistants and IDE copilots is available in our llms.txt resource. This guide includes detailed onboarding, setup instructions, usage patterns, troubleshooting, and security best practices.

Perfect for AI agents helping with installation, client/server integration, authentication, deployment, testing, and debugging realtime features.

https://realtime.impulselab.ai/llms.txt

You can deploy the service with Docker by running the following command:

docker run -p 8080:8080 -e REALTIME_SECRET="secret" ghcr.io/impulse-studio/realtime-service

Feel free to change the port and secret to your liking.

Missing something?

If you’re missing something,
feel free to open an issue on the GitHub repository or discuss it on the Discord server.

Open in GitHub
Open in Discord