next-sse-handler

Tiny SSE (server sent event) handler for Nextjs

Quick usage

Default GET route (zero config):

// app/api/sse/route.ts
import { GET as sseGET, publish, createMessage } from "next-sse-handler";

export const GET = sseGET; // ready-to-use GET handler

// example test route POST handler
export async function POST(req: Request) {
  const body = await req.json();
  publish(createMessage(body));
  return new Response(JSON.stringify({ ok: true }));
}

Customizing retry and heartbeat

Use createGet to produce a GET handler with custom values:

import { createGet, publish, createMessage } from "next-sse-handler";

// retry: 2000ms, heartbeat: 5s
export const GET = createGet({ retry: 2000, heartbeatInterval: 5000 });

// example test route POST handler
export async function POST(req: Request) {
  const body = await req.json();
  publish(createMessage(body));
  return new Response(JSON.stringify({ ok: true }));
}

Message format

export type SseEvent = {
  id?: string; // automatically generated with nanoid if using createMessage
  event?: string; // optional event name, if none, onmessage will pick these up
  data: string; // data in string format, use JSON.stringify for object data
};

Client example

useEffect(() => {
  // connect to the route handler
  const es = new EventSource("/api/sse");

  // using custom event name "json", otherwise omit or use "message"
  es.addEventListener("json", (e) => {
    try {
      const json = JSON.parse((e as MessageEvent).data);
      console.log("json", json);
    } catch (error) {
      console.error("Error parsing JSON:", error);
    }
  });

  return () => {
    es.close();
  };
}, []);

Server function

"use server";

import { publish } from "next-sse-handler";

export async function sendServerMessage(message: string) {
  publish({ event: "json", data: JSON.stringify({ message }) });
}

API

• GET — Next.js GET handler
• createGet(options?: { retry?: number; heartbeatInterval?: number }) — factory for GET handler
• publish(event: SseEvent) — publish an event to subscribers
• subscribe(fn) — subscribe to events, returns unsubscribe function
• formatSse(event) — helper to format SseEvent
• createMessage(data: string, event?: SseEvent) — create an SseEvent with nanoid

Notes

• This is intended for Node server runtimes (Next server routes). If you need Edge runtime compatibility you'll need to adapt the approach (no global state).