GraphQL Subscriptions with Apollo Server and Client blog post

GraphQL Subscriptions with Apollo Server and Client

Zach Silveira

2 Sep, 2019

GraphQL

8 minutes read

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.

Once you've finished reading this post, do you want to learn even more?

javascript

Learn JavaScript for FREE!

We've created the best online course for you to fully master JavaScript using real-world examples and techniques you’ll find nowhere else.

  • ES2015 and beyond
  • Variables and Scoping
  • Strings, Numbers and Booleans
  • Conditional Statements
  • Operators
  • Modules
  • Arrays and Objects
  • Functions and Closures
  • Loops and Iteration
Get course Get javascript Basics

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!

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: { ...book, 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 {
        name,
        twitter,
      };
    },
    deleteBook: (_, { title }) => true,
    changeBookTitle: (_, { input }) => {
      let { id, title } = input;

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

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

      //Return the new book title
      return {
        ...book,
        title,
      };
    },
  },
  // 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'
    );
  },
  wsLink,
  httpLink,
);

export default new ApolloClient({
  cache: new InMemoryCache(),
  link,
});

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.

useSubscription

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 {
      id
      title
      author
    }
  }
`;

export default () => useSubscription(subscription);

Open up Books.js and add the following:

import useBookTitleChanged from "./useBookTitleChanged";

const Books = () => {
  useBookTitleChanged();
  ...

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.title);
  }, [setTitle, book]);
  //end new code

  return (
    
setTitle(e.target.value)} />
); }; 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.

Conclusion

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!

About the author

I've been using React for 5 years, React Native since release, and GraphQL for almost as long. I get excited about new technologies and being the first to figure them out. Serverless, penetration testing, and automating development are the things I am most excited about, other than React hooks! If you want to discuss anything I write here, please tweet me @zachcodes

Love the post? Share it!

Lots of time and effort go into all our blogs, resources and demos,
we'd love it if you'd spare a moment to share them!

Explore our Angular courses

Get started today and join over 60,000 developers.