Server-Sent Events (SSE)

Subgraphs

Subgraphs don't require any special configuration to use SSE. When the router connects to a subgraph for a subscription, it will automatically negotiate SSE if the subgraph supports it. The router prefers multipart first, then falls back to SSE.

Clients

To use SSE, send requests with the following Accept header:

Accept: text/event-stream

The router will respond with a stream of events implementing the "distinct subscriptions mode" of the GraphQL over SSE spec.

The router sends a heartbeat event every 10 seconds to keep the connection alive.

If an error occurs, the router emits an error event and completes the stream. If the requested subscription transport is not supported, the router returns 406 Not Acceptable.

Try It

curl 'http://localhost:4000/graphql' \
  -H 'accept: text/event-stream' \
  --json '{
    "query": "subscription {
      reviewAdded {
        body
        rating
        product {
          name
        }
        author {
          name
        }
      }
    }"
  }'

This command creates an SSE connection and keeps it open to receive new subscription data as server-sent events:

event: next
data: {"data":{"reviewAdded":{"body":"Great product!","rating":5,"product":{"name":"Croissant"},"author":{"name":"Alice"}}}}

event: next
data: {"data":{"reviewAdded":{"body":"Could be better","rating":3,"product":{"name":"Baguette"},"author":{"name":"Bob"}}}}

event: next
data: {"data":{"reviewAdded":{"body":"Excellent quality","rating":5,"product":{"name":"Croissant"},"author":{"name":"Charlie"}}}}

event: complete

This example subscription emits three next events and then sends a complete event to signal the end of the stream. Notice how the product and author fields are automatically resolved from their respective subgraphs.

EventSource

You can easily subscribe over SSE using the browser native EventSource interface. It's as simple as:

const url = new URL("http://localhost:4000/graphql");
url.searchParams.append(
  "query",
  `subscription {
    reviewAdded {
      body
      rating
      product {
        name
      }
      author {
        name
      }
    }
  }`,
);

const source = new EventSource(url);

source.addEventListener("next", ({ data }) => {
  console.log(data);
});

source.addEventListener("error", (e) => {
  console.error(e);
});

source.addEventListener("complete", () => {
  source.close();
});

graphql-sse

We highly recommend using graphql-sse, the zero-dependency, HTTP/1 safe, simple, GraphQL over Server-Sent Events spec client library.

It offers reliable handling of connection management, message parsing, and error handling, as well as silent retries and exponential backoff for improved resilience.

Apollo Client

Please advise the Apollo Client integration recipe.

Relay

Please advise the Relay integration recipe.

urql

Please advise the urql integration recipe.