| name | sse-basics |
| description | Core implementation of Server-Sent Events (SSE) for realtime one-way communication in Next.js. Basic patterns for setup, message format, and client consumption. |
| triggers | ["sse basics","implement sse","sse setup","realtime stream"] |
SSE Basics
Foundation for SSE in social apps: one-way server push for notifications, feeds.
Core Concepts
- Unidirectional: Server → Client only. No client → server communication on same connection.
- Format: Messages use
text/event-stream content type, each message ends with \n\n.
- Auto-reconnect: Built-in browser retry (default 3s). Can be customized with
retry: 5000 message.
- Use cases: Notifications, live feeds, real-time updates from server.
Next.js Implementation
Server (Route Handler)
Create a route handler that streams events using TransformStream or ReadableStream.
import { NextRequest } from 'next/server';
export async function GET(req: NextRequest) {
const stream = new TransformStream();
const writer = stream.writable.getWriter();
const encoder = new TextEncoder();
(async () => {
await writer.write(encoder.encode('data: {"message":"Hello SSE"}\n\n'));
await new Promise(resolve => setTimeout(resolve, 5000));
await writer.write(encoder.encode('data: {"message":"Still connected"}\n\n'));
await writer.close();
})();
return new Response(stream.readable, {
headers: {
'Content-Type': 'text/event-stream',
'Cache-Control': 'no-cache',
'Connection': 'keep-alive',
}
});
}
Client (React Component)
Use EventSource to connect and listen for messages.
'use client';
import { useEffect, useState } from 'react';
export default function SSEClient() {
const [messages, setMessages] = useState<string[]>([]);
useEffect(() => {
const es = new EventSource('/api/sse-basics');
es.onmessage = (event) => {
const data = JSON.parse(event.data);
setMessages(prev => [...prev, data.message]);
};
es.onerror = (error) => {
console.error('SSE error:', error);
es.close();
};
return () => es.close();
}, []);
return (
<div>
<h1>SSE Messages</h1>
<ul>
{messages.map((msg, i) => <li key={i}>{msg}</li>)}
</ul>
</div>
);
}
Message Format
SSE messages follow a specific format:
data: {"key": "value"}\n\n
Multi-line data:
data: line 1\n
data: line 2\n
\n
With event name:
event: custom-event\n
data: {"info": "event data"}\n
\n
Retry Handling
Customize reconnect interval (milliseconds):
retry: 5000\n
data: {"message": "reconnect in 5s"}\n
\n
AI Tip
Use AI to generate SSE endpoints quickly:
Prompt: "Generate a basic SSE endpoint in Next.js for social notifications. Send notifications to a specific user."
Prompt: "Create a React component that connects to an SSE endpoint and displays real-time messages."
Common Patterns
Single message then close
await writer.write(encoder.encode('data: {"status":"ok"}\n\n'));
await writer.close();
Continuous stream
Keep connection open and send messages periodically. Add heartbeat to prevent timeout.
Event types
Use event: <name> to differentiate message types on client:
await writer.write(encoder.encode('event: notification\ndata: {"type":"like"}\n\n'));
Client listens with es.addEventListener('notification', handler).