Subscriptions

A GraphQL subscription initiates an event stream, where each event in the stream is pushed from the server to the client that issued the subscription.

Example use cases for subscriptions are applications that require real-time data such as chat applications or stock trading platforms.

GraphQL Yoga uses server-sent-events for the subscription protocol. You don't need any extra packages to use subscriptions.

💡

Compared to implementing query and mutation resolvers, subscriptions are more complex to implement as they require additional infrastructure for scenarios where you have more than one instance of your GraphQL server running as the event streams must be distributed across all servers.

Quick Start with simple Server-Sent Events (SSE)

Subscriptions can be added by extending your GraphQL schema with a Subscription type.

Subscription countdown implementation

import { createYoga, createSchema } from 'graphql-yoga'
import { createServer } from 'node:http'
 
// Provide your schema
const yoga = createYoga({
  schema: createSchema({
    typeDefs: /* GraphQL */ `
      type Query {
        hello: String
      }
 
      type Subscription {
        countdown(from: Int!): Int!
      }
    `,
    resolvers: {
      Query: {
        hello: () => 'world'
      },
      Subscription: {
        countdown: {
          // This will return the value on every 1 sec until it reaches 0
          subscribe: async function* (_, { from }) {
            for (let i = from; i >= 0; i--) {
              await new Promise((resolve) => setTimeout(resolve, 1000))
              yield { countdown: i }
            }
          }
        }
      }
    }
  })
})
 
const server = createServer(yoga)
server.listen(4000, () => {
  console.info('Server is running on http://localhost:4000/graphql')
})

Start the server, visit http://localhost:4000/graphql and paste the following operation into the left panel.

Subscription countdown operation

subscription {
  countdown(from: 5)
}

Then press the Play (Execute Query) button.

Alternatively, you can also send the subscription operation via curl.

$ curl -N -H "accept:text/event-stream" http://localhost:4000/graphql?query=subscription%20%7B%0A%20%20countdown%28from%3A%205%29%0A%7D
data: {"data":{"countdown":5}}
 
data: {"data":{"countdown":4}}
 
data: {"data":{"countdown":3}}
 
data: {"data":{"countdown":2}}
 
data: {"data":{"countdown":1}}
 
data: {"data":{"countdown":0}}

💡

Watch Episode #52 of graphql.wtf for a quick introduction to using GraphQL Subscriptions with Server Sent Events:

Handling Subscriptions on the Client

WHATWG standard EventSource can be used without any extra packages to handle SSE.

eventsource.ts

const url = new URL('http://localhost:4000/graphql')
 
url.searchParams.append(
  'query',
  /* GraphQL */ `
    subscription Countdown($from: Int!) {
      countdown(from: $from)
    }
  `
)
url.searchParams.append('variables', JSON.stringify({ from: 10 }))
 
const eventsource = new EventSource(url.toString(), {
  withCredentials: true // This is required for cookies
})
 
eventsource.onmessage = function (event) {
  const data = JSON.parse(event.data)
  console.log(data) // This will result something like `{ "data": { "countdown": 0 } }`
}

Client Usage with Apollo

You can either decide to use the pre-built Yoga Apollo Link, or build your own from scratch. The Yoga Apollo Link requires you to install an additional package, while the custom link requires you to write more code. However, by writing the link yourself you get full control over the link and can customize it to your needs.

Install the @graphql-yoga/apollo-link package.

yarn add @graphql-yoga/apollo-link

You can use YogaLink from @graphql-yoga/apollo-link package to use subscriptions together with file uploads and defer/stream in Apollo Client.

YogaLink apollo client usage

import { ApolloClient, InMemoryCache } from '@apollo/client/core'
import { YogaLink } from '@graphql-yoga/apollo-link'
 
const client = new ApolloClient({
  link: new YogaLink({
    endpoint: 'http://localhost:4000/graphql'
  }),
  cache: new InMemoryCache()
})

Client Usage with urql

You can either decide to use the pre-built Yoga Urql Exchange, or build your own from scratch. The Yoga Urql Exchange requires you to install an additional package, while the custom link requires you to write more code. However, by writing the link yourself you get full control over the link and can customize it to your needs.

You need to install @urql/exchange-graphql for GraphQL Yoga, and use yogaExchange from that package.

yarn add @graphql-yoga/urql-exchange

import { createClient, defaultExchanges } from 'urql'
import { yogaExchange } from '@graphql-yoga/urql-exchange'
 
const client = createClient({
  url: 'http://localhost:4000/graphql',
  exchanges: [...defaultExchanges, yogaExchange()]
})

Client usage with Relay

Relay Subscription client.

import {
  type RequestParameters,
  type GraphQLResponse,
  Observable,
  Network
} from 'relay-runtime'
import type { Variables } from 'react-relay'
import { executeQueryOrMutation } from './execute-query-or-mutation.js'
 
const executeSubscription = (
  request: RequestParameters,
  variables: Variables
): Observable<GraphQLResponse> => {
  if (!request.text) throw new Error('Missing document.')
  const { text: operation, name } = request
 
  const url = new URL('http://localhost:4000/graphql')
  url.searchParams.append('query', operation)
  if (name) {
    url.searchParams.append('operationName', name)
  }
  if (variables) {
    url.searchParams.append('variables', JSON.stringify(variables))
  }
 
  return Observable.create<GraphQLResponse>((sink) => {
    const source = new EventSource(url.toString())
    source.onmessage = function (event) {
      const data = JSON.parse(event.data)
      sink.next(data)
      if (source.readyState === 2) {
        sink.complete()
      }
    }
    source.onerror = function (ev) {
      console.error(ev)
      sink.error(new Error('Unexpected error.'))
    }
    return () => source.close()
  })
}
 
const network = Network.create(executeQueryOrMutation, executeSubscription)

GraphQL over Server-Sent Events Protocol (via `graphql-sse`)

In case you want the subscriptions to be transported following the GraphQL over Server-Sent Events Protocol, you simply use the @graphql-yoga/plugin-graphql-sse plugin for GraphQL Yoga that exposes an additional endpoint (defaulting to /graphql/stream) used for graphql-sse clients.

The plugin will hijack the request from the onRequest hook and will use all envelop plugins provided.

Also, consider setting the subscriptionsProtocol in GraphiQL options to GRAPHQL_SSE in order to have it use graphql-sse.

yoga-with-graphql-sse.ts

import { createServer } from 'node:http'
import { createYoga } from 'graphql-yoga'
import { useGraphQLSSE } from '@graphql-yoga/plugin-graphql-sse'
 
const yogaApp = createYoga({
  graphiql: {
    // Use graphql-sse in GraphiQL.
    subscriptionsProtocol: 'GRAPHQL_SSE'
  },
  plugins: [
    // Simply install the graphql-sse plugin and you're off!
    useGraphQLSSE()
  ]
})
 
// Get NodeJS Server from Yoga
const httpServer = createServer(yogaApp)
 
httpServer.listen(4000, () => {
  console.log('Server is running on port 4000')
})

💡

Check out our working example for this integration.

Client Integration

Please refer to the graphql-sse client recipes.

GraphQL over WebSocket Protocol (via `graphql-ws`)

Suppose you want to use the graphql-transport-ws protocol with GraphQL Yoga, you can use the graphql-ws library. To have the same execution pipeline in graphql-ws, we can use the Envelop instance from GraphQL Yoga like below in Node.JS. Also, you can set subscriptionsProtocol in GraphiQL options to use WebSockets instead of Server-Sent Events within GraphiQL.

yoga-with-ws.ts

import { createServer } from 'node:http'
import { createYoga } from 'graphql-yoga'
import { WebSocketServer } from 'ws'
import { useServer } from 'graphql-ws/lib/use/ws'
 
const yogaApp = createYoga({
  graphiql: {
    // Use WebSockets in GraphiQL
    subscriptionsProtocol: 'WS'
  }
})
 
// Get NodeJS Server from Yoga
const httpServer = createServer(yogaApp)
// Create WebSocket server instance from our Node server
const wsServer = new WebSocketServer({
  server: httpServer,
  path: yogaApp.graphqlEndpoint
})
 
// Integrate Yoga's Envelop instance and NodeJS server with graphql-ws
useServer(
  {
    execute: (args: any) => args.rootValue.execute(args),
    subscribe: (args: any) => args.rootValue.subscribe(args),
    onSubscribe: async (ctx, msg) => {
      const { schema, execute, subscribe, contextFactory, parse, validate } =
        yogaApp.getEnveloped({
          ...ctx,
          req: ctx.extra.request,
          socket: ctx.extra.socket,
          params: msg.payload
        })
 
      const args = {
        schema,
        operationName: msg.payload.operationName,
        document: parse(msg.payload.query),
        variableValues: msg.payload.variables,
        contextValue: await contextFactory(),
        rootValue: {
          execute,
          subscribe
        }
      }
 
      const errors = validate(args.schema, args.document)
      if (errors.length) return errors
      return args
    }
  },
  wsServer
)
 
httpServer.listen(4000, () => {
  console.log('Server is running on port 4000')
})

💡

Check out our working example for this integration.

Client Integration

Please refer to the graphql-ws client recipes.

SSE vs WebSocket

Advantages of SSE over WebSockets

Transported over simple HTTP instead of a custom protocol
Built in support for re-connection and event-id Simpler protocol
No trouble with corporate firewalls doing packet inspection

Advantages of WebSockets over SSE

Real time, two directional communication.
Lower latency

SSE Gotchas

Maximum open connections limit (when not using http/2). In this case, consider using the graphql-sse integration with "single connection mode".

PubSub

Getting Started

GraphQL Yoga comes with a built-in PubSub (publish/subscribe) bus. This makes it easy to send new events to the client from within your mutation resolvers.

server.ts

import { createServer, createPubSub, createSchema } from 'graphql-yoga'
 
const pubSub = createPubSub()
 
// Provide your schema
const yoga = createYoga({
  schema: createSchema({
    typeDefs: /* GraphQL */ `
      type Query {
        hello: String
      }
 
      type Subscription {
        randomNumber: Float!
      }
 
      type Mutation {
        broadcastRandomNumber: Boolean
      }
    `,
    resolvers: {
      Query: {
        hello: () => 'world'
      },
      Subscription: {
        randomNumber: {
          // subscribe to the randomNumber event
          subscribe: () => pubSub.subscribe('randomNumber'),
          resolve: (payload) => payload
        }
      },
      Mutation: {
        broadcastRandomNumber: (_, args) => {
          // publish a random number
          pubSub.publish('randomNumber', Math.random())
        }
      }
    }
  })
})
 
const server = createServer(yoga)
server.listen(4000, () => {
  console.info('Server is running on http://localhost:4000/graphql')
})

Topics

When using TypeScript it is possible to make the event emitter type-safe by providing a channel configuration via a generic.

const pubSub = createPubSub<{
  randomNumber: [randomNumber: number]
}>()
 
pubsub.subscribe('randomNumber')
 
// This is now type-safe.
pubSub.publish('randomNumber', 1)
 
// This causes a TypeScript error.
pubSub.publish('randomNumber')
 
// This causes a TypeScript error.
pubSub.publish('event does not exist')

You can subscribe to a specific topic using pubSub.subscribe.

const pubSub = createPubSub<{
  randomNumber: [randomNumber: number]
}>()
 
// Usage outside a GraphQL subscribe function
async function subscribe() {
  const eventSource = pubSub.subscribe('randomNumber')
 
  for await (const value of eventSource) {
    console.log(value)
    // dispose subscription after the first event has been published.
    eventSource.return()
  }
}
 
subscribe()
 
pubSub.publish('randomNumber', 3)

You can publish a value using pubSub.publish.

const pubSub = createPubSub<{
  randomNumber: [randomNumber: number]
}>()
 
pubSub.publish('randomNumber', 3)

Topic Configuration Variants

You can declare events with and without a payload.

const pubSub = createPubSub<{
  // event has no payload
  'event:without:payload': []
  // event has payload of type number
  'event:payload:number': [payload: number]
  // event has payload of type { foo: number }
  'event:payload:obj': [payload: { foo: number }]
}>()
 
pubSub.publish('event:without:payload')
pubSub.publish('event:payload:number', 12)
pubSub.publish('event:payload:obj', { foo: 1 })

Topic with Dynamic ID

Sometimes you only want to emit and listen for events for a specific entity (e.g. user or product). You can declare topics scoped to a special identifier.

const pubSub = createPubSub<{
  'user:followerCount': [userId: string, payload: { followerCount: number }]
}>()
 
const userId1 = '420'
const userId2 = '69'
 
// the userId argument is enforced by the TypeScript compiler.
pubSub.subscribe('user:followerCount', userId1)
pubSub.subscribe('user:followerCount', userId2)
 
pubSub.publish('user:followerCount', userId1, { followerCount: 30 })
pubSub.publish('user:followerCount', userId2, { followerCount: 12 })

Distributed Pub/Sub for Production

If you spin up multiple instances of your GraphQL server each server instance will have their own in-memory pub/sub instance. An event triggered on the one server instance will not be distributed to the other server instances, resulting in subscribers on the other server not receiving any updates.

The createPubSub function allows you to specify a custom EventTarget implementation, which can use an external datastore for distributing the events across all server replicas such as Redis Pub/Sub or Kafka.

The minimal EventTarget implementation is described by the TypedEventTarget interface.

Yoga comes with an EventTarget implementation for Redis Pub/Sub.

yarn add @graphql-yoga/redis-event-target ioredis

import { Redis } from 'ioredis'
import { createPubSub } from 'graphql-yoga'
import { createRedisEventTarget } from '@graphql-yoga/redis-event-target'
 
const publishClient = new Redis()
const subscribeClient = new Redis()
 
const eventTarget = createRedisEventTarget({
  publishClient,
  subscribeClient
})
 
const pubSub = createPubSub({ eventTarget })

Please note that Redis Pub/Sub requires a stable long-running connection and thus is not a suitable solution for serverless or edge function environments.

Please also note that the event payloads must be JSON serializable. If you want to send complex data structures over the wire you can use tools such as superjson.

Advanced

Filter and Map Values

Sometimes it is useful to filter or map events for an individual subscription set up by a client based on subscription field arguments. Yoga has a few utility functions that make this as simple as possible.

Example PubSub event stream transform

import { createServer, createPubSub, pipe, map, filter } from 'graphql-yoga'
 
const pubSub = createPubSub<{
  randomNumber: [randomNumber: number]
}>()
 
const source = pipe(
  pubSub.subscribe('randomNumber'),
  map((publishedNumber) => publishedNumber * 2),
  filter((multipliedNumber) => multipliedNumber < 10)
)
 
;(async () => {
  for await (const value of source) {
    console.log(value)
  }
})()
 
pubSub.publish('randomNumber', 1) // logs 2
pubSub.publish('randomNumber', 2) // logs 4
pubSub.publish('randomNumber', 5) // filtered out
pubSub.publish('randomNumber', 3) // logs 6
source.return()

Example Random number stream transform

import { createPubSub, createYoga, createSchema } from 'graphql-yoga'
import { createServer } from 'node:http'
 
const pubSub = createPubSub()
 
const yoga = createYoga({
  schema: createSchema({
    typeDefs: /* GraphQL */ `
      type Query {
        hello: String
      }
 
      type Subscription {
        randomNumber(multiplyBy: Int!, lessThan: Float!): Float!
      }
 
      type Mutation {
        broadcastRandomNumber: Boolean
      }
    `,
    resolvers: {
      Query: {
        hello: () => 'world'
      },
      Subscription: {
        randomNumber: {
          // subscribe to the randomNumber event
          subscribe: (_, args) =>
            pipe(
              pubSub.subscribe('randomNumber'),
              map((publishedNumber) => publishedNumber * args.multiplyBy),
              filter((multipliedNumber) => multipliedNumber < args.lessThan)
            ),
          resolve: (payload) => payload
        }
      },
      Mutation: {
        broadcastRandomNumber: (_, args) => {
          // publish a random number
          pubSub.publish('randomNumber', Math.random())
        }
      }
    }
  })
})
 
const server = createServer(yoga)
server.listen(4000, () => {
  console.info('Server is running on http://localhost:4000/graphql')
})

Subscriptions with Initial Value

GraphQL subscriptions are primarily designed to send a stream of events to the client. Sometimes it is useful to send an initial value to a client as soon as the GraphQL subscription is set up.

An example for this would be a Subscription.globalCounter field that syncs a counter with all clients by streaming the initial counter value to a client that sets up the subscription and then, furthermore, streams the updated counter value to the clients every time it changes.

GraphQL subscriptions are implemented using Async Iteration, which in itself is a very complex topic with a lot of pitfalls that can cause memory leaks if not treated with caution.

Yoga uses and re-exports Repeater.js ("The missing constructor for creating safe async iterators") for providing a friendly developer experience.

import {
  createYoga,
  createSchema,
  createPubSub,
  Repeater,
  pipe,
  map
} from 'graphql-yoga'
import { createServer } from 'node:http'
 
let globalCounter = 0
const pubSub = createPubSub()
 
const yoga = createYoga({
  schema: createServer({
    typeDefs: /* GraphQL */ `
      type Query {
        hello: String
      }
 
      type Subscription {
        globalCounter: Int!
      }
 
      type Mutation {
        incrementGlobalCounter: Int!
      }
    `,
    resolvers: {
      Query: {
        hello: () => 'world'
      },
      Subscription: {
        globalCounter: {
          // Merge initial value with source stream of new values
          subscribe: () =>
            pipe(
              Repeater.merge([
                // cause an initial event so the
                // globalCounter is streamed to the client
                // upon initiating the subscription
                undefined,
                // event stream for future updates
                pubSub.subscribe('globalCounter:change')
              ]),
              // map all stream values to the latest globalCounter
              map(() => globalCounter)
            ),
          resolve: (payload) => payload
        }
      },
      Mutation: {
        incrementGlobalCounter: () => {
          globalCounter = globalCounter + 1
          // publish a global counter increment event
          pubSub.publish('globalCounter:change')
          return globalCounter
        }
      }
    }
  })
})
 
const server = createServer(yoga)
server.listen(4000, () => {
  console.info('Server is running on http://localhost:4000/graphql')
})

Listen to Multiple Pub/Sub Topics

Sometimes it is handy to subscribe to multiple PubSub topics instead of a single one.

import { createYoga, createSchema, createPubSub, Repeater } from 'graphql-yoga'
import { createServer } from 'node:http'
 
type User = {
  id: string
  login: string
}
 
let user: User | null = {
  id: '1',
  login: 'Laurin'
}
 
const pubSub = createPubSub<{
  userLoginChanged: []
  userDeleted: []
}>()
 
const yoga = createYoga({
  schema: createSchema({
    typeDefs: /* GraphQL */ `
      type Query {
        hello: String
      }
 
      type User {
        id: ID!
        login: String
      }
 
      type Subscription {
        user: User
      }
 
      type Mutation {
        deleteUser: Boolean
        updateUserLogin(newLogin: String!): Boolean
      }
    `,
    resolvers: {
      Query: {
        hello: () => 'world'
      },
      Subscription: {
        user: {
          // Merge initial value with source streams of new values
          subscribe: () =>
            pipe(
              Repeater.merge([
                undefined,
                pubSub.subscribe('userLoginChanged'),
                pubSub.subscribe('userDeleted')
              ]),
              // map all stream values to the latest user
              map(() => user)
            ),
          resolve: (payload) => payload
        }
      },
      Mutation: {
        deleteUser() {
          user = null
          pubSub.publish('userDeleted')
          return true
        },
        updateUserLogin(_, args) {
          if (!user) {
            return false
          }
          user.login = args.newLogin
          pubSub.publish('userLoginChanged')
          return true
        }
      }
    }
  })
})
 
const server = createServer(yoga)
server.listen(4000, () => {
  console.info('Server is running on http://localhost:4000/graphql')
})

Last updated on January 18, 2023

Introspection File Uploads

Subscriptions

Quick Start with simple Server-Sent Events (SSE)

Handling Subscriptions on the Client

Client Usage with Apollo

Client Usage with urql

Client usage with Relay

GraphQL over Server-Sent Events Protocol (via graphql-sse)

Client Integration

GraphQL over WebSocket Protocol (via graphql-ws)

Client Integration

SSE vs WebSocket

Advantages of SSE over WebSockets

Advantages of WebSockets over SSE

SSE Gotchas

PubSub

Getting Started

Topics

Topic Configuration Variants

Topic with Dynamic ID

Distributed Pub/Sub for Production

Advanced

Filter and Map Values

Subscriptions with Initial Value

Listen to Multiple Pub/Sub Topics

GraphQL over Server-Sent Events Protocol (via `graphql-sse`)

GraphQL over WebSocket Protocol (via `graphql-ws`)