Server-Sent Events
SSE is the simplest real-time primitive. One-way, server-to-client, built on HTTP. No upgrade handshake, no special protocol, no Durable Objects. A Responsewith a ReadableStream body and Content-Type: text/event-stream.
When to Use SSE
Use SSE when data flows in one direction: server to client. Notifications, live feeds, progress updates, AI token streaming, dashboard tickers. If you also need the client to send data back over the same connection, use WebSockets.
The Helper
Juice ships eventStream() -- a small function that handles SSE wire format, client disconnect cleanup, and keep-alive. It returns a Response, so it composes naturally with Route-as-API.
import { eventStream } from '@cmj/juice/runtime';Two forms, same function:
- Callback -- for event-driven sources (pub/sub, database listeners). You call
send()when events arrive. - AsyncIterable -- for sequential streams (AI tokens, polling loops). You
yieldevents.
Basic Example: Callback Form
A Route-as-API GET handler that pushes notifications to the client. The callback receives a send function and returns a cleanup function that runs when the client disconnects.
// app/routes/api/notifications.ts
import { eventStream } from '@cmj/juice/runtime';
import type { ActionContext } from '@cmj/juice/runtime';
import { notifications } from '../../lib/notifications.js';
export function GET(req: Request, ctx: ActionContext) {
return eventStream(req.signal, (send) => {
// Subscribe to a notification source
const unsubscribe = notifications.subscribe((notification) => {
send({
event: 'notification',
data: notification, // objects are auto-JSON'd
id: notification.id, // enables client resumption
});
});
// Cleanup runs on client disconnect
return () => unsubscribe();
});
}The first argument is req.signal -- the AbortSignal from the incoming request. When the client closes the connection (navigates away, calls EventSource.close(), or loses network), the signal aborts, the stream closes, and your cleanup function runs. No leaked subscriptions.
AsyncIterable Form
When events arrive in sequence rather than from a subscription, an async generator is more natural. This is common for AI token streaming:
// app/routes/api/ai-stream.ts
import { eventStream } from '@cmj/juice/runtime';
export function GET(req: Request) {
return eventStream(req.signal, async function* () {
const stream = ai.chat({
model: 'claude-sonnet-4-5-20250514',
prompt: new URL(req.url).searchParams.get('q') ?? '',
});
for await (const chunk of stream) {
yield { data: chunk.text };
}
yield { event: 'done', data: '' };
});
}The generator runs until it returns or the signal aborts -- whichever comes first. If the client disconnects mid-stream, the for await loop breaks and the generator is cleaned up automatically.
Event Fields
Each SSEEvent maps directly to the SSE wire format fields:
| Field | Wire Format | Purpose |
|---|---|---|
data | data: ... | The payload. Strings are sent as-is. Objects are JSON.stringify()'d. Multi-line strings are split into multiple data: lines per the SSE spec. |
event | event: ... | Named event type. Without it, the client receives the event on onmessage. With it, the client listens via addEventListener('notification', ...). |
id | id: ... | Sets the client's lastEventId. On reconnection, EventSourcesends this back as the Last-Event-ID header. Use it to resume from where the client left off. |
retry | retry: ... | Overrides the client's reconnection interval in milliseconds. Useful for backoff: send retry: 5000 when the server is under load. |
Client Disconnect and Cleanup
SSE connections are long-lived. Resources attached to the connection (database cursors, pub/sub subscriptions, timers) must be freed when the client disconnects.
eventStream() wires req.signal to the stream lifecycle. When the signal aborts:
- The keep-alive timer is cleared.
- Your cleanup function runs (callback form) or the async iterator returns (iterable form).
- The
ReadableStreamcloses.
You do not need to check signal.aborted manually in most cases. The framework handles it. But if you have a long-running computation between sends, check the signal to bail early:
return eventStream(req.signal, async function* () {
for (const batch of batches) {
if (req.signal.aborted) return; // bail early
const result = await expensiveComputation(batch);
yield { data: result };
}
});Keep-Alive
By default, eventStream() sends a : keep-alive comment every 25 seconds. This is invisible to EventSource (comments are ignored by the SSE parser) but keeps the connection alive on platforms that kill idle connections.
Cloudflare Workers terminate connections with no data after 30 seconds. The 25-second default stays safely under that threshold. On Bun, Deno, and Node.js there is no idle timeout by default, but keep-alive is still useful for detecting dead connections through intermediary proxies and load balancers.
// Disable keep-alive (if you send events frequently enough)
eventStream(req.signal, source, { keepAlive: false });
// Custom interval (10 seconds)
eventStream(req.signal, source, { keepAlive: 10_000 });Shared Sources: createChannel()
A live page usually has many clients watching the same thing: every viewer of a build polls the same build, every member of a room listens to the same room. With the examples above, each connection runs its own poller or subscription. createChannel()runs one source per key, starts it for the first subscriber of that key, shares it with everyone who subscribes to the same key, and stops it (runs the cleanup your source returned) when the last subscriber leaves.
// app/routes/api/builds/[id]/events.ts
import { createChannel, eventStream } from '@cmj/juice/runtime';
import type { ActionContext } from '@cmj/juice/runtime';
import { db } from '../../../lib/db.js';
// Module level, like cache(fn, { key }): the channel outlives requests.
const builds = createChannel((publish, buildId) => {
const timer = setInterval(async () => {
const build = await db.builds.find(buildId);
publish({ id: String(build.version), event: 'status', data: build });
}, 1000);
return () => clearInterval(timer); // runs when the last viewer leaves
}, { buffer: 20 });
export function GET(req: Request, ctx: ActionContext) {
return eventStream(req.signal, builds.subscribe(ctx.params.id, req.headers.get('Last-Event-ID')));
}The source receives publish and the key. It can be a poller, a database LISTEN, an upstream SSE or WebSocket connection, anything that calls publish(event); it may be async and may return an async cleanup. channel.subscribe(key, lastEventId?) returns a callback source for eventStream(): it registers the connection's send and returns the unsubscribe function, which eventStream() runs when the client disconnects. Ten viewers of one build cost one poller; when the tenth closes the tab, the poller stops.
channel.events(key, lastEventId?) is the same subscription as an AsyncIterable, for eventStream(req.signal, builds.events(id)). Pass it to eventStream() directly: inside your own async generator, a disconnect only reaches the loop at its next event, because return() cannot interrupt a pending await. To filter or reshape events, wrap send in the callback form instead:
return eventStream(req.signal, (send) =>
builds.subscribe(id)((event) => {
if (event.event === 'status') send({ ...event, data: summarize(event.data) });
}),
);Publishing from elsewhere
A channel without a source is plain pub/sub. channel.publish(key, event) delivers to every subscriber of the key, from a server action, a webhook route or a background job:
// app/lib/notifications.ts
import { createChannel } from '@cmj/juice/runtime';
export const notifications = createChannel({ buffer: 50 });
// app/routes/api/notifications.ts
export function GET(req: Request, ctx: ActionContext) {
return eventStream(req.signal, notifications.subscribe(ctx.params.userId, req.headers.get('Last-Event-ID')));
}
// app/actions/orders.ts
'use server';
export async function shipOrder(formData: FormData, ctx: ActionContext) {
const order = await db.orders.ship(formData.get('id'));
await notifications.publish(order.userId, { id: order.eventId, event: 'shipped', data: order });
}Replaying missed events with buffer
When the connection drops, EventSource reconnects on its own and sends the last id: it received as the Last-Event-ID header. On its own, the runtime does nothing with that header: eventStream() writes the id you give it, and a reconnect is an ordinary new GET that starts from the current position. The channel's buffer option is the one resume behaviour Juice provides: it keeps the last n events per key, and a subscriber that passes a lastEventId is first sent the events after that id (or the whole buffer, when the id is no longer in it), then goes live. Give events a monotonic id for this to mean anything.
The buffer is in memory and belongs to the running source, so it is dropped when the last subscriber leaves. A single viewer who reconnects would find nothing to replay; set linger (milliseconds) to keep the source and buffer alive across quick reconnects. For anything that must survive restarts or a different server instance, read the header in your handler and replay from your own history before going live.
const builds = createChannel(pollBuild, {
buffer: 20, // replay up to 20 missed events
linger: 10_000, // keep polling 10s after the last viewer leaves
});Several server instances
Each instance runs its own copy of a source for the keys its clients watch, so a poller runs once per instance, not once per client. channel.publish() travels through a broadcast adapter so a publish on one instance reaches the subscribers on all of them. The default, memoryChannel(), stays in-process. redisChannel(client) uses Redis pub/sub and accepts node-redis, Bun.redis or any client with publish, subscribe, unsubscribe and duplicate. Nothing is installed for you: pass the client you already have.
import { createChannel, redisChannel } from '@cmj/juice/runtime';
import { createClient } from 'redis'; // or: import { redis } from 'bun';
const redis = await createClient({ url: process.env.REDIS_URL }).connect();
export const notifications = createChannel({
buffer: 50,
broadcast: redisChannel(redis, { prefix: 'myapp:' }), // channel name = prefix + key
});The adapter calls duplicate() once for a connection that only listens (Redis puts a subscribed connection in subscriber mode) and publishes on the client you pass. Events cross the wire as JSON, so data must be serializable. The replay buffer stays per instance. To write your own adapter (Postgres NOTIFY, a Durable Object, NATS), implement BroadcastAdapter: publish(key, event) and subscribe(key, onEvent) returning an unsubscribe function, both sync or async.
Per-Runtime Notes
- Cloudflare Workers: SSE works without Durable Objects (unlike WebSockets). Keep-alive is critical -- 30-second idle kill is enforced. CPU time limits still apply: you get billed per millisecond of active computation, but idle time between events is free.
- Bun: Full SSE support. No special handling needed.
- Deno: Full SSE support. No special handling needed.
- Node.js: Works through the existing Juice adapter that streams
Response.bodyviagetReader()andres.write().
Client-Side Patterns
EventSource (simplest)
EventSource is a browser built-in. It handles reconnection automatically, sends Last-Event-ID on reconnect, and parses the SSE wire format for you. The tradeoff: GET-only, no custom headers, no POST body.
// Browser client
const source = new EventSource('/api/notifications');
source.addEventListener('notification', (e) => {
const notification = JSON.parse(e.data);
console.log(notification);
});
source.onerror = () => {
// EventSource auto-reconnects. This fires on each retry.
console.log('Connection lost, reconnecting...');
};
// Cleanup
source.close();fetch + getReader (flexible)
When you need POST requests, custom headers, or finer control over reconnection, use fetch() with a streaming reader. You parse the SSE format yourself.
async function streamEvents(url: string, onEvent: (data: string) => void) {
const res = await fetch(url, {
headers: { Accept: 'text/event-stream' },
});
const reader = res.body!.getReader();
const decoder = new TextDecoder();
let buffer = '';
while (true) {
const { done, value } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
const events = buffer.split('\n\n');
buffer = events.pop()!; // incomplete event stays in buffer
for (const event of events) {
const dataLine = event.split('\n')
.filter(line => line.startsWith('data: '))
.map(line => line.slice(6))
.join('\n');
if (dataLine) onEvent(dataLine);
}
}
}React Hook Pattern
Juice intentionally does not export a client-side hook -- the right state management approach varies by application. Here is a pattern you can adapt:
'use client'
import { useState, useEffect } from 'react';
function useEventSource<T>(url: string, eventName = 'message') {
const [data, setData] = useState<T | null>(null);
const [error, setError] = useState<Event | null>(null);
useEffect(() => {
const source = new EventSource(url);
const handler = (e: MessageEvent) => {
try {
setData(JSON.parse(e.data));
} catch {
setData(e.data as T);
}
};
source.addEventListener(eventName, handler);
source.onerror = setError;
return () => source.close();
}, [url, eventName]);
return { data, error };
}
// Usage in a component
export default function Dashboard() {
const { data: stats } = useEventSource<Stats>('/api/live-stats', 'stats');
if (!stats) return <div>Connecting...</div>;
return <div>Active users: {stats.activeUsers}</div>;
}SSE vs WebSockets vs Polling
| SSE | WebSockets | Polling | |
|---|---|---|---|
| Direction | Server to client | Bidirectional | Client to server (pull) |
| Protocol | HTTP | WS (upgrade from HTTP) | HTTP |
| Reconnection | Built-in (EventSource) | Manual | N/A (each request is independent) |
| Resumption | Last-Event-ID header | Manual | Cursor / offset parameter |
| Cloudflare Workers | Works (no Durable Objects) | Requires Durable Objects | Works |
| Complexity | Low | High | Lowest |
| Best for | Notifications, live feeds, AI streaming | Chat, collaboration, gaming | Infrequent updates (< 1/min) |
Full Example: Live Dashboard
A server that pushes system metrics every second, with client resumption support:
// app/routes/api/metrics.ts
import { eventStream } from '@cmj/juice/runtime';
let counter = 0;
export function GET(req: Request) {
// Resume from where the client left off
const lastId = Number(req.headers.get('Last-Event-ID') ?? '0');
counter = Math.max(counter, lastId);
return eventStream(req.signal, (send) => {
const interval = setInterval(() => {
counter++;
send({
id: String(counter),
event: 'metrics',
data: {
cpu: Math.random() * 100,
memory: Math.random() * 16_000,
requests: counter,
timestamp: Date.now(),
},
});
}, 1000);
return () => clearInterval(interval);
});
}// app/routes/dashboard.tsx (client component)
'use client'
import { useState, useEffect } from 'react';
export default function MetricsDashboard() {
const [metrics, setMetrics] = useState(null);
const [connected, setConnected] = useState(false);
useEffect(() => {
const source = new EventSource('/api/metrics');
source.addEventListener('metrics', (e) => {
setMetrics(JSON.parse(e.data));
setConnected(true);
});
source.onerror = () => setConnected(false);
return () => source.close();
}, []);
if (!metrics) return <p>Connecting to metrics stream...</p>;
return (
<div>
<p>{connected ? 'Live' : 'Reconnecting...'}</p>
<dl>
<dt>CPU</dt><dd>{metrics.cpu.toFixed(1)}%</dd>
<dt>Memory</dt><dd>{(metrics.memory / 1000).toFixed(1)} GB</dd>
<dt>Requests</dt><dd>{metrics.requests}</dd>
</dl>
</div>
);
}