Realtime Updates with GraphQL Subscriptions

This section is all about bringing realtime functionality into the app by using GraphQL subscriptions.

What are GraphQL Subscriptions?

Subscriptions are a GraphQL feature that allows the server to send data to the clients when a specific event happens on the backend. Subscriptions are usually implemented with WebSockets, where the server holds a steady connection to the client. That is, the Request-Response-Cycle that we used for all previous interactions with the API is not used for subscriptions. Instead, the client initially opens up a steady connection to the server by specifying which event it is interested in. Every time this particular event happens, the server uses the connection to push the data that’s related to the event to the client.

Subscriptions with Apollo

When using Apollo, you need to configure your ApolloClient with information about the subscriptions endpoint. This is done by using functionality from the subscriptions-transport-ws npm module.

Go ahead and add this dependency to your app first.

Next, make sure your ApolloClient instance knows about the subscription server.

You’re instantiating a SubscriptionClient that knows the endpoint for the Subscriptions API. Notice that you’re also authenticating the websocket connection with the user’s token that you retrieve from localStorage.

Now you need to replace the placeholder __SUBSCRIPTION_API_ENDPOINT__ with the endpoint for the subscriptions API.

The endpoints for the Subscription API generally are of the form: wss://subscriptions.graph.cool/v1/<project-id>.

Notice that if your project is not running in the “default” Graphcool region, you need to add the your project’s region to the endpoint like so: wss://subscriptions.ap-northeast-1.graph.cool/v1/<project-id> (for regoin Asia Pacific) or wss://subscriptions.us-west-2.graph.cool/v1/<project-id> (for US West).

Subscribing to new Links

For the app to update in realtime when new links are created, you need to subscribe to events that are happening on the Link type. There generally are three kinds of events you can subscribe to:

• a new Link is created
• an existing Link is updated
• an existing Link is deleted

First, you need to add a subscription to src/constants/graphql.js:

You’ll implement this subscription in the LinkList component since that’s where all the links are rendered.

Let’s understand what’s going on here! You’re using the allLinks query that you have access to call subscribeToMore. This call opens up a websocket connection to the subscription server.

You’re passing an array to subscribeToMore:

1. Each object within the array contains a document property: This represents the subscription itself. In your case, the subscription will fire for CREATED events on the Link type, i.e. every time a new link is created.
2. The other property is updateQuery: Similar to update, this function allows you to determine how the store should be updated with the information that was sent by the server.

Go ahead and implement updateQuery next. This function works slightly differently than update. In fact, it follows exactly the same principle as a Redux reducer: It takes as arguments the previous state (of the query that subscribeToMore was called on) and the subscription data that’s sent by the server. You can then determine how to merge the subscription data into the existing state and return the updated version.

Let’s see what this looks like in action!

All you do here is retrieve the new link from the subscription data (subscriptionData.data.Link.node), merge it into the existing list of links and return the result of this operation.

Awesome, that’s it! You can test your implementation by opening two browser windows. In the first window, you have your application running on http://localhost:8080/. The second window you use to open a Playground and send a createLink mutation. When you’re sending the mutation, you’ll see the app update in realtime! ⚡️

Subscribing to new Votes

Next you’ll subscribe to new votes that are emitted by other users as well so that the latest vote count is always visible in the app.

First, you need to add another subscription to src/constants/graphql.js:

You’ll also implement this subscription in the LinkList component since that’s where all the links are rendered.

Similar to before, you’re calling subscribeToMore on the allLinks query. This time you’re passing in a subscription that asks for newly created votes. In updateQuery, you’re then adding the information about the new vote to the cache by first looking for the Link that was just voted on and then updating its votes with the Vote element that was sent from the server.

Fantastic! Your app is now ready for realtime and will immediately update links and votes whenever they’re created by other users.