Angular Icon Get 73% off the Angular Master bundle

See the bundle then add to cart and your discount is applied.

0 days
00 hours
00 mins
00 secs

Write JavaScript like a pro. Javascript Icon

Follow the ultimate JavaScript roadmap.

GraphQL Subscriptions with Apollo Server and Client

Now that we’ve completed the lifecycle of GraphQL by building out a server and using queries on the frontend, it’s time to do some more interesting things and dive into subscriptions and some websockets.

For those unfamiliar, websockets are a way to instantly update your user interface. For example, Google Analytics has a real-time active users feature, if a new user joins your website then the count will increase and if a user leaves the count will decrease. With websockets, you can send out an update to anyone currently on your application, and change the UI, without a page refresh.

In this post, we’ll be making some GraphQL Subscriptions over websockets. Real-time programming can be a whole lot of fun. With Apollo Server and the GraphQL spec, websockets are easier to work with. If you have an understanding of GraphQL, there’s not much new to learn, other than the required server setup.

Follow this GraphQL Series:

You may remember from our first post where I mentioned that the same query / mutation syntax can be used for writing subscriptions. This is the big selling point, for anyone with websocket experience. Websocket logic typically is handled by a separate library on the frontend. You’d need to make a REST api call, and then pull in a websocket library.

Luckily for us, we’re able to stay inside our GraphQL layer, without having to write different code to support websockets. This is because the GraphQL spec includes subscriptions, and keeps the same query syntax you should now be used to!

Angular Directives In-Depth eBook Cover

Free eBook

Directives, simple right? Wrong! On the outside they look simple, but even skilled Angular devs haven’t grasped every concept in this eBook.

  • Green Tick Icon Observables and Async Pipe
  • Green Tick Icon Identity Checking and Performance
  • Green Tick Icon Web Components <ng-template> syntax
  • Green Tick Icon <ng-container> and Observable Composition
  • Green Tick Icon Advanced Rendering Patterns
  • Green Tick Icon Setters and Getters for Styles and Class Bindings

Server Setup

We’ll start by doing:

I have updated some dependencies and made hot reloading work better. With that out of the way, we can get started.

Let’s create a file called server/src/pubsub.js:

import { PubSub } from 'apollo-server';

const pubsub = new PubSub();

export default pubsub;

This is the module we will call anytime we want to publish some data over our websocket connection. You can think of it this way; anytime an action takes place on your website, and you want to live update anyone currently using your application, we would use this pubsub module.

Next, let’s add our first subscription type. Open up server/src/typeDefs.js and add the following:

type Subscription {
  bookTitleChanged: Book

Since we made it possible to change a book title in the UI, we can make this live update in other people’s browsers. In this case, the idea is that anyone looking at your site will immediately see the book title change after someone changes it. A more real-world scenario for this could be blog posts on a popular site. If you are sitting on the homepage, new posts could fade in the moment they are posted.

To make this work, we only have one file left to edit on the server. Open up server/src/resolvers.js.

I have the full resolvers.js below, so that you can confirm you did it correctly.

Add this import to the top:

import pubsub from './pubsub';

Then, inside changeBookTitle add this, below the book:

pubsub.publish("bookTitleChanged", {
  bookTitleChanged: {, title }

And then finally, the subscription itself needs to go after the `Mutation` object:

Subscription: {
  bookTitleChanged: {
    subscribe: () => pubsub.asyncIterator(["bookTitleChanged"]);

That may have been a little confusing if you’re new to JS in general. So here is the fully updated resolvers.js:

import pubsub from './pubsub';

const books = [
    id: 1,
    title: 'Harry Potter and the Chamber of Secrets',
    author: 'J.K. Rowling',
    id: 2,
    title: 'Jurassic Park',
    author: 'Michael Crichton',

export const resolvers = {
  Query: {
    books: () => {
      return books;
    authors: () => {
      return [
        { name: 'Todd', twitter: 'toddmotto' },
        { name: 'React', twitter: 'reactjs' },
  Mutation: {
    addAuthor: (_, { input: { name, twitter } }) => {
      return {
    deleteBook: (_, { title }) => true,
    changeBookTitle: (_, { input }) => {
      let { id, title } = input;

      let book = books.find(book => === id);

      // Publish the book so that the subscription can fire off
      pubsub.publish('bookTitleChanged', {
        bookTitleChanged: {, title },

      //Return the new book title
      return {,
  // Add Subscription at the end of the resolvers object
  Subscription: {
    bookTitleChanged: {
      subscribe: () => pubsub.asyncIterator(['bookTitleChanged']),

The flow is pretty straight forward. Whenever you want a subscription to run, you publish some data to it. In this case, my subscription is listening for bookTitleChanged. Whenever that gets published, any subscribers will receive that data. You can read more about this on the official docs.

I should also mention that it is possible to subscribe to specific things. If you wanted to only get books that changed if the book had a certain id. You could do this. It’s a little out of the scope of this tutorial, but the docs link above goes over Subscription Filters.

Client Setup

With that finished, our server is ready for subscriptions. Now, we get to update our client code to support subscriptions. Open up the web folder and follow along:

First, we need to install the required websocket packages for Apollo Client:

npm install --save apollo-link-ws subscriptions-transport-ws

Inside web/src/apolloSetup.js we create a websocket link:

import { WebSocketLink } from 'apollo-link-ws';

const wsLink = new WebSocketLink({
  uri: `ws://localhost:4000/`,
  options: {
    reconnect: true,

Unfortunately, after that, we have to import some other special things that will tell Apollo to route any subscription requests through the websocket link we just added. This looks a little confusing, so bare with me and replace the contents of apolloSetup.js:

import { split } from 'apollo-link';
import { HttpLink } from 'apollo-link-http';
import { ApolloClient } from 'apollo-client';
import { WebSocketLink } from 'apollo-link-ws';
import { getMainDefinition } from 'apollo-utilities';
import { InMemoryCache } from 'apollo-cache-inmemory';

const wsLink = new WebSocketLink({
  uri: `ws://localhost:4000/graphql`,
  options: {
    reconnect: true,

const httpLink = new HttpLink({
  uri: 'http://localhost:4000/graphql',

const link = split(
  // split based on operation type
  ({ query }) => {
    const definition = getMainDefinition(query);
    return (
      definition.kind === 'OperationDefinition' &&
      definition.operation === 'subscription'

export default new ApolloClient({
  cache: new InMemoryCache(),

This is mostly taken from the official doc if you’re curious. It says, if the operation is a subscription, use the websocket link, otherwise, use the normal httpLink. Websockets work by using a constant connection to the server. This isn’t possible over http, because http requests do not stay open.


With that setup out of the way, we can finally write the request!

Create src/useBookTitleChanged.js:

import gql from 'graphql-tag';
import { useSubscription } from '@apollo/react-hooks';

export const subscription = gql`
  subscription BookTitleChanged {
    bookTitleChanged {

export default () => useSubscription(subscription);

Open up Books.js and add the following:

import useBookTitleChanged from "./useBookTitleChanged";

const Books = () => {

Adding this hook to the top of the component will make everything work as expected. Open up two browser windows, and change the title in one of them.

You’ll see the other window updates the title as well. One problem you may notice however, is that the input field doesn’t update. This is an easy fix. If we open up ChangeTitle.js and add the following, that will update as well:

import React, { useState, useEffect } from 'react';
import useChangeBookTitleMutation from './useChangeBookTitleMutation';

const ChangeTitle = ({ book }) => {
  let changeTitle = useChangeBookTitleMutation();
  let [title, setTitle] = useState(book.title);

  //new code
  useEffect(() => {
  }, [setTitle, book]);
  //end new code

  return (
    setTitle(} />
    changeTitle({ id:, title })}>
    Change it!

export default ChangeTitle;

I will call out one more problem, a user may be in the middle of editing the field, in which case we wouldn’t want the input to be overwritten. You could prevent the update in the useEffect if the input is currently focused, or not worry about this at all since what we created isn’t too real-world of a problem.

I am going off on a bit of a tangent here to show the sorts of problems you could run into if you carelessly updated your api from a websocket.


If you got lost along the way, you can git checkout 4-end to see the final code. I hope this gave you a fun introduction to subscriptions inside GraphQL. After the initial setup, it can be quick and easy to add subscriptions into your app.

In the next post, we will take our current code, and show how easy it is to get automatic TypeScript generation thanks to the GraphQL schema. We’re getting close to the end of the series, and I hope you’re learning a lot. Before the next one, try doing some other things with subscriptions. Maybe a live chart, or user count for who’s currently on the page. I’m sure you can come up with other neat ideas!

Learn JavaScript the right way.

The most complete guide to learning JavaScript ever built.
Trusted by 82,951 students.

Todd Motto

with Todd Motto

Google Developer Expert icon Google Developer Expert

Related blogs 🚀

Free eBooks:

Angular Directives In-Depth eBook Cover

JavaScript Array Methods eBook Cover

NestJS Build a RESTful CRUD API eBook Cover