graphql-sse is a lightweight, zero-dependency (aside from a `graphql` peer dependency) library that enables GraphQL operations, particularly subscriptions, over the Server-Sent Events (SSE) protocol. It provides both server-side handler utilities and a client for consuming SSE streams. The current stable version is 2.6.0, with releases occurring semi-regularly, focusing on bug fixes, feature enhancements like dynamic client URLs, and new framework integrations (e.g., Koa, Fastify, Express adapters). Its key differentiator is its exclusive use of SSE, making it HTTP/1 safe and suitable for environments where WebSockets might be problematic, offering a robust alternative to `graphql-ws` for subscription-heavy applications without requiring a separate WebSocket server infrastructure. It is designed for simplicity and direct integration with existing HTTP servers.
npm install graphql-sseVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates setting up a GraphQL SSE server with Express and then connecting to it with the `graphql-sse` client to run a real-time subscription for a countdown.
Users migrating from v1.x must consult the v2 documentation and examples, as direct migration is not possible. Key changes include how handlers are created and integrated with HTTP frameworks.
Ensure your client expects SSE (e.g., using `createClient` from this library) and your network infrastructure supports SSE. If WebSockets are required for your use case, consider using a library like `graphql-ws` instead.
Ensure your project's installed version of 'graphql' satisfies the peer dependency range. For example, install `graphql@^16` (`npm install graphql@^16` or `yarn add graphql@^16`) to meet the common requirements.
Verify the exact subpath export in `package.json` (e.g., `graphql-sse/use/express`). Ensure your bundler (Webpack, Rollup, Vite) is correctly configured to handle Node.js subpath exports, especially in older versions or non-standard setups.
Double-check server configuration for `createHandler` and the chosen `useServer` adapter. Ensure the response headers include `Content-Type: text/event-stream` and `Cache-Control: no-cache, no-transform`. Verify the client `url` is correct and accessible, and that any proxies allow SSE traffic.
Review the client-side `iterate` call to ensure the query string is valid GraphQL and any necessary variables are correctly passed as the second argument. Confirm that your server's `createHandler` is receiving and parsing the request body correctly (e.g., `express.json()` middleware for Express).