SSE
On this page

Changelog

Every GraphQL over Server-Sent Events release with its changes and the pull requests behind them.

2.6.1 (2026-08-25)

Bug Fixes

2.6.0 (2025-10-22)

Features

  • client: Support dynamic URLs and headers per request for distinct connection mode (#124) (7be7251), closes #110 #113

2.5.4 (2025-01-10)

Bug Fixes

  • client: Conversion to async iterable from Response.body (#114) (f2adc92)

2.5.3 (2024-03-27)

Bug Fixes

  • use/fastify: Include middleware headers (134c1b0), closes #91

2.5.2 (2023-12-20)

Bug Fixes

  • remove package.json workspaces entry in release (c6dc093)

2.5.1 (2023-12-14)

Bug Fixes

  • use/koa: Use parsed body from request (#87) (b290b90)

2.5.0 (2023-12-13)

Features

  • use/koa: expose full Koa context to options (#86) (b37a6f9)

2.4.1 (2023-12-13)

Bug Fixes

2.4.0 (2023-11-29)

Bug Fixes

  • client: Use closures instead of bindings (with this) (8ecdf3c)

Features

  • client: Event listeners for both operation modes (#84) (6274f44)

2.3.0 (2023-09-07)

Features

2.2.3 (2023-08-23)

Bug Fixes

  • use/http,use/http2,use/express,use/fastify: Check writable instead of closed before writing to response (3c71f69), closes #69

2.2.2 (2023-08-22)

Bug Fixes

  • use/http,use/http2,use/express,use/fastify: Handle cases where response’s close event is late (#75) (4457cba), closes #69

2.2.1 (2023-07-31)

Bug Fixes

  • handler: Always include the data field in stream messages (#71) (4643c9a)

2.2.0 (2023-06-22)

Features

  • client: Async iterator for subscriptions (#66) (fb8bf11)

2.1.4 (2023-06-12)

Bug Fixes

  • Request parameters query field can only be a string (16c9600), closes #65

2.1.3 (2023-05-15)

Bug Fixes

  • client: Respect retry attempts when server goes away after connecting in single connection mode (#59) (e895c5b), closes #55
  • handler: Detect ExecutionArgs in onSubscribe return value (a16b921), closes #58

2.1.2 (2023-05-10)

Bug Fixes

  • client: Respect retry attempts when server goes away after connecting (#57) (75c9f17), closes #55

Reverts

  • Revert “Revert “docs: website (#50)"" (0e4f4b5), closes #50

2.1.1 (2023-03-31)

Bug Fixes

  • Add file extensions to imports/exports in ESM type definitions (bbf23b1)

2.1.0 (2023-02-17)

Bug Fixes

  • use/express,use/fastify: Resolve body if previously parsed (6573e94)

Features

  • handler: Export handler options type for each integration (2a2e517)

2.0.0 (2022-12-20)

Features

  • handler: Server and environment agnostic handler (#37) (22cf03d)

BREAKING CHANGES

  • handler: The handler is now server agnostic and can run anywhere
  • Core of graphql-sse is now server agnostic and as such offers a handler that implements a generic request/response model
  • Handler does not await for whole operation to complete anymore. Only the processing part (parsing, validating and executing)
  • GraphQL context is now typed
  • Hook arguments have been changed, they’re not providing the Node native req/res anymore - they instead provide the generic request/response
  • onSubscribe hook can now return an execution result too (useful for caching for example)
  • Throwing in onNext and onComplete hooks will bubble the error to the returned iterator

Migration

Even though the core of graphql-sse is now completely server agnostic, there are adapters to ease the integration with existing solutions. Migrating is actually not a headache!

Beware that the adapters don’t handle internal errors, it’s your responsibility to take care of that and behave accordingly.

http

import http from 'http';
- import { createHandler } from 'graphql-sse';
+ import { createHandler } from 'graphql-sse/lib/use/http';

// Create the GraphQL over SSE handler
const handler = createHandler({ schema });

// Create an HTTP server using the handler on `/graphql/stream`
const server = http.createServer((req, res) => {
  if (req.url.startsWith('/graphql/stream')) {
    return handler(req, res);
  }
  res.writeHead(404).end();
});

server.listen(4000);
console.log('Listening to port 4000');

http2

import fs from 'fs';
import http2 from 'http2';
- import { createHandler } from 'graphql-sse';
+ import { createHandler } from 'graphql-sse/lib/use/http2';

// Create the GraphQL over SSE handler
const handler = createHandler({ schema });

// Create an HTTP server using the handler on `/graphql/stream`
const server = http.createServer((req, res) => {
  if (req.url.startsWith('/graphql/stream')) {
    return handler(req, res);
  }
  res.writeHead(404).end();
});

server.listen(4000);
console.log('Listening to port 4000');

express

import express from 'express'; // yarn add express
- import { createHandler } from 'graphql-sse';
+ import { createHandler } from 'graphql-sse/lib/use/express';

// Create the GraphQL over SSE handler
const handler = createHandler({ schema });

// Create an express app
const app = express();

// Serve all methods on `/graphql/stream`
app.use('/graphql/stream', handler);

server.listen(4000);
console.log('Listening to port 4000');

fastify

import Fastify from 'fastify'; // yarn add fastify
- import { createHandler } from 'graphql-sse';
+ import { createHandler } from 'graphql-sse/lib/use/fastify';

// Create the GraphQL over SSE handler
const handler = createHandler({ schema });

// Create a fastify app
const fastify = Fastify();

// Serve all methods on `/graphql/stream`
fastify.all('/graphql/stream', handler);

fastify.listen({ port: 4000 });
console.log('Listening to port 4000');

1.3.2 (2022-12-06)

Bug Fixes

  • handler: Correct typings and support for http2 (08d6ca3), closes #38

1.3.1 (2022-12-05)

Bug Fixes

  • client: Abort request when reporting error (91057bd)
  • client: Operation requests are of application/json content-type (0084de7)

1.3.0 (2022-07-20)

Features

  • client: Accept referrer and referrerPolicy fetch options (#32) (dbaa90a)

1.2.5 (2022-07-17)

Bug Fixes

  • client: Leverage active streams for reliable network error retries (607b468)

1.2.4 (2022-07-01)

Bug Fixes

  • Add types path to package.json exports (44f95b6)

1.2.3 (2022-06-13)

Bug Fixes

  • client: Retry if connection is closed while having active streams (83a0178), closes #28

1.2.2 (2022-06-09)

Bug Fixes

  • client: Network errors during event emission contain the keyword “stream” in Firefox (054f16b)

1.2.1 (2022-06-09)

Bug Fixes

  • client: Retry network errors even if they occur during event emission (489b1b0), closes #27

Performance Improvements

  • client: Avoid recreating result variables when reading the response stream (16f6a6c)

1.2.0 (2022-04-14)

Bug Fixes

  • client: TypeScript generic for ensuring proper arguments when using “single connection mode” (be2ae7d)

Features

  • client: Inspect incoming messages through ClientOptions.onMessage (496e74b), closes #20

1.1.0 (2022-03-09)

Features

  • client: Add credentials property for requests (79d0266)
  • client: Add lazyCloseTimeout as a close timeout after last operation completes (16e5e31), closes #17

1.0.6 (2021-11-18)

Bug Fixes

  • client: Avoid bundling DOM types, have the implementor supply his own Response type (98780c0)
  • handler: Support generics for requests and responses (9ab10c0)

1.0.5 (2021-11-02)

Bug Fixes

  • client: Should not call complete after subscription error (d8b7634)
  • handler: Use 3rd body argument only if is object or string (2062579)

1.0.4 (2021-09-08)

Bug Fixes

  • Define graphql execution results (89da803)
  • server: Operation result can be async generator or iterable (24b6078)

1.0.3 (2021-08-26)

Bug Fixes

  • Bump graphql version to v16 in package.json (af219f9)

1.0.2 (2021-08-26)

Bug Fixes

  • Add support for graphql@v16 (89367f2)

1.0.1 (2021-08-23)

Bug Fixes

  • Prefer X-GraphQL-Event-Stream-Token header name for clarity (9aaa0a9)

1.0.0 (2021-08-21)

Features