Registry / web-framework / graphql-sse

graphql-sse

JSON →
library2.6.0jsnpmunverified

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-sse
INSTALL
IMPORT
SIG · GRAPHQL-SSE
G
graphql-sse
web-frameworkjavascriptv2.6.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

createHandler
import { createHandler } from 'graphql-sse';
const { createHandler } = require('graphql-sse');
While CommonJS `require` is supported via package exports, ESM `import` is the idiomatic choice for modern Node.js and browser applications since Node.js 12+.
createClient
import { createClient } from 'graphql-sse';
const { createClient } = require('graphql-sse');
The client allows consuming SSE streams from a graphql-sse server or any compatible GraphQL over SSE endpoint.
useServer (e.g., for Express)
import { useServer } from 'graphql-sse/use/express';
import { useServer } from 'graphql-sse'; // Incorrect subpath import { useExpress } from 'graphql-sse/use/express'; // Incorrect symbol name
Framework-specific adapters (like `useExpress`, `useFastify`, `useKoa`, `useHttp`) are exposed via subpath exports. Ensure the correct subpath and symbol name are used.

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.

import express from 'express'; import { createHandler } from 'graphql-sse'; import { useServer } from 'graphql-sse/use/express'; // Or use/fastify, use/koa, etc. import { makeExecutableSchema } from '@graphql-tools/schema'; import { createClient } from 'graphql-sse'; // --- Server Setup --- const typeDefs = ` type Query { hello: String } type Subscription { countdown(from: Int!): Int! } `; const resolvers = { Query: { hello: () => 'world', }, Subscription: { countdown: { subscribe: async function* (_, { from }: { from: number }) { for (let i = from; i >= 0; i--) { await new Promise((resolve) => setTimeout(resolve, 1000)); yield { countdown: i }; } }, }, }, }; const schema = makeExecutableSchema({ typeDefs, resolvers }); const handler = createHandler({ schema }); const app = express(); app.use('/graphql/sse', useServer({ handler })); // Mount the SSE handler app.get('/health', (req, res) => res.send('OK')); const PORT = process.env.PORT || 4000; app.listen(PORT, () => { console.log(`Server listening on http://localhost:${PORT}/graphql/sse`); }); // --- Client Setup --- const client = createClient({ url: `http://localhost:${PORT}/graphql/sse` }); async function runSubscription() { const query = ` subscription Countdown($from: Int!) { countdown(from: $from) } `; const input = { from: 5 }; console.log('\nClient: Subscribing to countdown...'); try { for await (const result of client.iterate(query, input)) { console.log('Client: Received:', result.data?.countdown); if (result.data?.countdown === 0) { console.log('Client: Countdown finished.'); break; } } } catch (error) { console.error('Client: Subscription error', error); } } // Start the client subscription after a short delay to allow server to boot setTimeout(runSubscription, 2000);
Debug
Known issues
breakingThe v2.0.0 release of graphql-sse was a complete rewrite introducing significant breaking changes from v1.x. The API for server handler creation and client instantiation was overhauled.
fix
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.
affects: <2.0.0
gotchagraphql-sse exclusively uses Server-Sent Events (SSE) for GraphQL operations, primarily subscriptions. It does not use WebSockets. Do not attempt to integrate with WebSocket clients or expect bidirectional communication typical of WebSocket-based GraphQL libraries.
fix
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.
affects: >=1.0.0
gotchaThe library has a peer dependency on 'graphql' with a specified version range (currently '>=0.11 <=16'). Using an incompatible version of 'graphql' in your project can lead to schema parsing, validation, or execution errors at runtime.
fix
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.
affects: >=1.0.0
Errors
Common errors & fixes
Cannot find module 'graphql-sse/use/express' or its corresponding type declarations.
Incorrect import path for framework adapters or issues with bundler configuration not recognizing subpath exports.
fix
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.
Client receives no events, or connection closes unexpectedly.
Server not correctly configured to send SSE (e.g., missing `Content-Type: text/event-stream` header, incorrect `Cache-Control`), network issue (firewall, proxy dropping long-lived HTTP connections), or incorrect client `url`.
fix
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.
Error: Must provide document and operationName.
This is a common GraphQL execution error indicating the client is sending an invalid or incomplete GraphQL request body to the server.
fix
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).
Upgrade
Version history
2.6.0latest on npm
Audit
Dependencies
graphqlrequiredRequired peer dependency for GraphQL schema definition and execution.
Agent activity
15 hits · last 30 days
node
14
OpenAI (training)
1
Resources
graphql-sse — npm install graphql-sse · libregistry