Fastify Server-Sent Events (SSE) Plugin

Common errors

• Error: fastify.sse is not a function

  cause The `fastify-sse-v2` plugin was either not registered correctly, or your Fastify instance is too old for the plugin version used.
  fix Ensure you have called `fastify.register(FastifySSEPlugin);` before attempting to use `reply.sse()`. Also, verify that your Fastify version meets the peer dependency requirement (>=4.0.0 for plugin versions 3.x and above).

• ERR_STREAM_WRITE_AFTER_END

  cause Attempting to write data to an SSE stream that has already been closed, either explicitly by calling `reply.sseContext.source.end()` or due to client disconnection.
  fix Implement checks to ensure the SSE stream is still active before attempting to send new events. For individual events, manage the lifecycle with `reply.sseContext.source.end()`. For `AsyncIterable` or `EventEmitter` sources, ensure your generator or event listener cleans up when the `request.socket.on('close')` event fires.

• ERR_HTTP_HEADERS_SENT: Cannot set headers after they are sent to the client

  cause You are attempting to send HTTP headers (e.g., calling `reply.send()` or similar methods) after the SSE connection has been initiated, which already sends specific headers for SSE.
  fix Once `reply.sse()` is called, the response is committed to an SSE stream. Do not attempt to modify headers or send a different type of response on the same request. Ensure all SSE-related logic is handled within the `reply.sse()` context.

Warnings

• breaking The 'end' event, previously emitted when an SSE stream was closing, has been removed. Dependents on this event for cleanup or notification will need to find alternative mechanisms, such as listening to `request.socket.on('close')`.
  Fix: Migrate any logic dependent on the SSE stream's 'end' event to use `request.socket.on('close')` for client disconnection detection.
• breaking Version 3.0.0 dropped support for Fastify v3. This plugin now exclusively requires Fastify v4 or newer. Attempting to use it with Fastify v3 will result in compatibility issues.
  Fix: Upgrade your Fastify application to version 4 or higher. Alternatively, for Fastify v3, use `fastify-sse-v2@1.x`.
• gotcha When sending individual events using `reply.sse()`, the connection remains open indefinitely. It will only terminate if `reply.sseContext.source.end()` is explicitly called or the client disconnects.
  Fix: Ensure `reply.sseContext.source.end()` is called to properly close the SSE stream when sending individual events, especially if the stream is meant to have a finite duration. For client disconnections, listen to `request.socket.on('close')`.
• gotcha Exceptions thrown after headers have been sent in the SSE context can lead to unexpected behavior or unhandled errors. Version 4.2.2 introduced a fix for this scenario.
  Fix: Upgrade to `fastify-sse-v2@4.2.2` or newer to mitigate issues with exceptions occurring after headers have been sent.
• gotcha Prior to version 4.2.1, newlines within event data were not handled properly, potentially corrupting the SSE stream format. This was addressed in `v4.2.1`.
  Fix: Upgrade to `fastify-sse-v2@4.2.1` or newer to ensure correct handling of newlines within event data payloads.

Install

• npm install fastify-sse-v2 npm
• yarn add fastify-sse-v2 yarn
• pnpm add fastify-sse-v2 pnpm

Imports

• FastifySSEPlugin
  wrong:

  const FastifySSEPlugin = require('fastify-sse-v2');

  correct:

  import { FastifySSEPlugin } from 'fastify-sse-v2';

  This is the main named export for registering the plugin. The package primarily uses ESM.
• sse

  reply.sse({ data: 'hello' });

  The `sse` method is added to the `FastifyReply` instance by the plugin and is not directly imported. It's accessible after plugin registration.
• FastifyReply and SSE types

  import { FastifyInstance, FastifyReply } from 'fastify';
  declare module 'fastify' {
    interface FastifyReply {
      sse: (payload: { id?: string; event?: string; data: string; retry?: number; comment?: string } | AsyncIterable<{ id?: string; event?: string; data: string; retry?: number; comment?: string }>) => void;
      sseContext: { source: { end: () => void } };
    }
  }

  While types are shipped, extending Fastify's interfaces is a common pattern to ensure TypeScript correctly recognizes the added `sse` method and `sseContext` property on `FastifyReply`.

Quickstart

This quickstart demonstrates how to set up a Fastify server with fastify-sse-v2 to stream events using an AsyncIterable source, sending five messages at 1.5-second intervals.

import Fastify from 'fastify';
import { FastifySSEPlugin } from 'fastify-sse-v2';

const fastify = Fastify({ logger: true });

fastify.register(FastifySSEPlugin);

// Helper to simulate async work
const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));

fastify.get('/events', function (request, reply) {
  reply.sse(
    (async function* source() {
      for (let i = 0; i < 5; i++) {
        await sleep(1500);
        const eventData = { id: String(i), data: `Message ${i} at ${new Date().toISOString()}` };
        fastify.log.info(`Sending event: ${JSON.stringify(eventData)}`);
        yield eventData;
      }
      fastify.log.info('SSE stream finished.');
    })()
  );
});

const start = async () => {
  try {
    await fastify.listen({ port: 3000 });
  } catch (err) {
    fastify.log.error(err);
    process.exit(1);
  }
};

start();