This is part 7 of our full-stack GraphQL + React Tutorial that guides you through creating a messaging application. Each part is self-contained and focuses on a few new topics, so you can jump directly into a part that interests you or do the whole series. Here’s what we have covered so far:



<ul class="wp-block-list"><li><a href="https://dev-blog.apollodata.com/full-stack-react-graphql-tutorial-582ac8d24e3b" target="_blank" rel="noreferrer noopener">Part 1: Setting up a simple client</a></li><li><a href="https://dev-blog.apollodata.com/react-graphql-tutorial-part-2-server-99d0528c7928" target="_blank" rel="noreferrer noopener">Part 2: Setting up a simple server</a></li><li><a href="https://dev-blog.apollodata.com/react-graphql-tutorial-mutations-764d7ec23c15" target="_blank" rel="noreferrer noopener">Part 3: Writing mutations and keeping the client in sync</a></li><li><a href="https://dev-blog.apollodata.com/tutorial-graphql-mutations-optimistic-ui-and-store-updates-f7b6b66bf0e2" target="_blank" rel="noreferrer noopener">Part 4: Optimistic UI and client side store updates</a></li><li><a href="https://dev-blog.apollodata.com/tutorial-graphql-input-types-and-client-caching-f11fa0421cfd" target="_blank" rel="noreferrer noopener">Part 5: Input Types and Custom Resolvers</a></li><li><a href="https://dev-blog.apollodata.com/tutorial-graphql-subscriptions-server-side-e51c32dc2951" target="_blank" rel="noreferrer noopener">Part 6: GraphQL Subscriptions on the Server</a></li><li>Part 7: Client subscriptions (This part!)</li><li><a href="https://dev-blog.apollodata.com/tutorial-pagination-d1c3b3ee2823" target="_blank" rel="noreferrer noopener">Part 8: Pagination</a></li></ul>



<hr class="wp-block-separator"/>



In part 6, we implemented the server-side portion of GraphQL Subscriptions for our message channels. Clients can use these subscriptions to be notified whenever a specific event happens — in this case the creation of a message in a specified channel.&nbsp;In this tutorial, we will add GraphQL Subscriptions to our client so that instances of the client can see live updates to messages in a channel.



<hr class="wp-block-separator"/>



Let’s get started by cloning the Git repo and installing the dependencies:



<pre class="wp-block-preformatted">git clone https://github.com/apollographql/graphql-tutorial.git cd graphql-tutorial git checkout t7-start cd server &amp;&amp; npm install cd ../client &amp;&amp; npm install</pre>



First, let’s make sure everything works by starting the server and client.



In one terminal session we launch the server, which will run on port 4000:



<pre class="wp-block-preformatted">cd server npm start</pre>



And in another session we launch the client, which will run on port 3000:



<pre class="wp-block-preformatted">cd client npm start</pre>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="600" height="531" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_XL1mNBEzqW5-w39t2lsutg.gif" alt="" class="wp-image-1054"/><figcaption>The current state of the application</figcaption></figure>



When you navigate your browser to&nbsp;<a href="http://localhost:3000/" target="_blank" rel="noreferrer noopener">http://localhost:3000</a>, you should enter the homepage of our messaging app, which has a list of channels that the user has created. Click on one of the channels, and you’ll be taken to the detail view that we created in&nbsp;<a href="https://dev-blog.apollodata.com/tutorial-graphql-input-types-and-client-caching-f11fa0421cfd" target="_blank" rel="noreferrer noopener">Part 5</a>, where you can add new messages in the channel. You’ll notice that if you open the same channel in multiple windows, messages added in one window don’t show up in the other. By the end of this tutorial, client syncing will allow multiple users to see each-other’s changes!



<h2 class="wp-block-heading" id="75b8"><a href="#graphql-subscriptions-transport" aria-hidden="true" class="aal_anchor" id="graphql-subscriptions-transport"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>GraphQL Subscriptions Transport</h2>



The first step to adding subscriptions to our client is to set up the WebSocket connection that the client and server will communicate over. Forming and maintaining the WebSocket connection will be the job of the Apollo network interface, defined in&nbsp;<code>client/src/App.js</code>. To add WebSocket support to our existing interface, we will construct a GraphQL Subscription client and merge it with our existing network interface to create a new interface that performs normal GraphQL queries over HTTP and subscription queries over WebSockets.



First, let’s add the necessary imports at the top of&nbsp;<code>client/src/App.js</code>



<pre class="wp-block-preformatted">import { SubscriptionClient, addGraphQLSubscriptions } from 'subscriptions-transport-ws';</pre>



Next, we construct the WebSocket-based subscription client and merge it with our existing network interface



<pre class="wp-block-preformatted">const networkInterface = createNetworkInterface({ uri: 'http://localhost:4000/graphql' });networkInterface.use([{ applyMiddleware(req, next) { setTimeout(next, 500); }, }]);const wsClient = new SubscriptionClient(`ws://localhost:4000/subscriptions`, { reconnect: true, });const networkInterfaceWithSubscriptions = addGraphQLSubscriptions( networkInterface, wsClient, );</pre>



Now all we have to do to enable subscriptions throughout our application is use&nbsp;<code>networkInterfaceWithSubscriptions</code>&nbsp;as the Apollo Client’s network interface



<pre class="wp-block-preformatted">const client = new ApolloClient({ networkInterface: networkInterfaceWithSubscriptions, ... });</pre>



If you load up the client and look in the “Network” tab of the developer tools (right-click and “Inspect element”), you should see that the client has established a WebSocket connection to the server.



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="712" height="453" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_LWXJNG7_vqC0uDammFc6kA.png" alt="" class="wp-image-1053" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_LWXJNG7_vqC0uDammFc6kA.png 712w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_LWXJNG7_vqC0uDammFc6kA-300x191.png 300w" sizes="(max-width: 712px) 100vw, 712px" /><figcaption>We can see our subscription connection being established!</figcaption></figure>



<h2 class="wp-block-heading" id="42d0"><a href="#listening-for-messages" aria-hidden="true" class="aal_anchor" id="listening-for-messages"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Listening for Messages</h2>



Now that we can use GraphQL Subscriptions in our client, the next step is to use subscriptions to detect the creation of messages. Our goal here is to use subscriptions to update our React views to see new messages in a channel as they are added.



Before we start, we have to refactor our&nbsp;<code>client/src/components/ChannelDetails.js</code>&nbsp;component to be a full ES6 class component instead of just a function, so that we can use the React lifecycle events to set up the subscription.



First, we update our import statement to include the&nbsp;<code>Component</code>&nbsp;class.



<pre class="wp-block-preformatted">import React, { Component } from 'react';</pre>



Then, we refactor our function component into an ES6 class



<pre class="wp-block-preformatted">class ChannelDetails extends Component { render() { const { data: {loading, error, channel }, match } = this.props; if (loading) { return &lt;ChannelPreview channelId={match.params.channelId}/&gt;; } if (error) { return &lt;p&gt;{error.message}&lt;/p&gt;; } if(channel === null){ return &lt;NotFound /&gt; } return ( &lt;div&gt; &lt;div className="channelName"&gt; {channel.name} &lt;/div&gt; &lt;MessageList messages={channel.messages}/&gt; &lt;/div&gt;); } }</pre>



Now that our component is ready to handle subscriptions, we can write out the subscriptions query:



<pre class="wp-block-preformatted">const messagesSubscription = gql` subscription messageAdded($channelId: ID!) { messageAdded(channelId: $channelId) { id text } } `</pre>



To make the subscription request, we will use Apollo Client’s&nbsp;<code>&lt;a href=&quot;http://dev.apollodata.com/react/subscriptions.html#subscribe-to-more&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;subscribeToMore&lt;/a&gt;</code>&nbsp;function, which lets us update the store when we receive new data. First, we define a&nbsp;<code>componentWillMount</code>&nbsp;in our component, which is where we will start the subscription.



<pre class="wp-block-preformatted">class ChannelDetails extends Component { componentWillMount() { } render() { ... } }</pre>



Inside this React lifecycle function, we set up our subscription to listen for new messages and add them to our local store as they come. Because the&nbsp;<code>updateQuery</code>&nbsp;function is supposed to produce a new instance of a store state based on&nbsp;<code>prev</code>, the previous store state, we use the&nbsp;<code>Object.assign</code>&nbsp;method to create a copy of the store with modifications to add the new message.



Also, because we are manually managing our store of messages, it is possible to have duplicate messages. A message can be added once as the result of performing the mutation and again when we receive the subscription notification. To prevent duplicates, we add an extra check to verify that we did not already add the message to our store with a previous mutation.



<pre class="wp-block-preformatted">componentWillMount() { this.props.data.subscribeToMore({ document: messagesSubscription, variables: { channelId: this.props.match.params.channelId, }, updateQuery: (prev, {subscriptionData}) =&gt; { if (!subscriptionData.data) { return prev; } const newMessage = subscriptionData.data.messageAdded; // don't double add the message if (!prev.channel.messages.find((msg) =&gt; msg.id === newMessage.id)) { return Object.assign({}, prev, { channel: Object.assign({}, prev.channel, { messages: [...prev.channel.messages, newMessage], }) }); } else { return prev; } } }); }</pre>



We’re almost done now! All we have to do is perform the same de-duplication check in the&nbsp;<code>AddMessage</code>&nbsp;component, because when we create a new message we might be notified of creation through the WebSocket before the query returns data. In&nbsp;<code>client/src/components/AddMessage.js</code>&nbsp;, replace&nbsp;<code>data.channel.messages.push(addMessage);</code>&nbsp;with the same statement wrapped in a condition that checks for duplication



<pre class="wp-block-preformatted">if (!data.channel.messages.find((msg) =&gt; msg.id === addMessage.id)) { // Add our Message from the mutation to the end. data.channel.messages.push(addMessage); }</pre>



Now we’re ready to test out our subscription-based live updating messages view! Open two windows of the client and select the same channel in both. When you add a message in one client, you should see the same message show up in the other client!



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="600" height="528" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_3pvDP1HbZlzwffIzfMbdbw.gif" alt="" class="wp-image-1052"/><figcaption>It works! The clients sync with each other!</figcaption></figure>



<h2 class="wp-block-heading" id="7b79"><a href="#conclusion" aria-hidden="true" class="aal_anchor" id="conclusion"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Conclusion</h2>



Congrats! You’ve now wired up the server-side implementation of GraphQL Subscriptions to your client through Apollo so that users can see live updates of message additions from other clients. With a couple more changes such as pagination, covered in the next&nbsp;<a href="https://dev-blog.apollodata.com/tutorial-pagination-d1c3b3ee2823" target="_blank" rel="noreferrer noopener">tutorial</a>, and auth your application will be ready for real use!



If you liked this tutorial and want to keep learning about Apollo and GraphQL, make sure to click the “Follow” button below, and follow us on Twitter at&nbsp;<a href="https://twitter.com/apollographql" target="_blank" rel="noreferrer noopener">@apollographql</a>&nbsp;and the author at&nbsp;<a href="http://twitter.com/shadajl" target="_blank" rel="noreferrer noopener">@ShadajL</a>.



Thanks to my mentor,&nbsp;<a href="https://medium.com/u/39cbd38c57c8?source=post_page-----40e185e4be76----------------------" target="_blank" rel="noreferrer noopener">Jonas Helfer</a>, for his support as I wrote this post!

Tutorial: GraphQL subscriptions with Apollo Client

In the last few months, we’ve implemented a lot of exciting features in&nbsp;<a href="https://github.com/apollostack/apollo-client" target="_blank" rel="noreferrer noopener">Apollo Client</a>, including&nbsp;<a href="https://medium.com/apollo-stack/pagination-and-infinite-scrolling-in-apollo-client-59ff064aac61#.po8zzknao" target="_blank" rel="noreferrer noopener">pagination and infinite scrolling</a>,&nbsp;<a href="https://medium.com/apollo-stack/mutations-and-optimistic-ui-in-apollo-client-517eacee8fb0#.rxmh0bblm" target="_blank" rel="noreferrer noopener">optimistic UI</a>, and&nbsp;<a href="https://medium.com/apollo-stack/query-batching-in-apollo-63acfd859862#.r56u16get" target="_blank" rel="noreferrer noopener">query batching</a>. Today we’re adding another one: GraphQL subscriptions!



In this post, we’ll explain the design and implementation in detail, but if you just want to see the code scroll to the end for links to all of our packages and examples!



GraphQL subscriptions allow developers to introduce new levels of interactivity to their apps with near-realtime updates. You can keep your app updated to the latest changes (that you subscribe to) between different users:



<figure class="wp-block-embed-wordpress wp-block-embed is-type-wp-embed is-provider-gfycat"><div class="wp-block-embed__wrapper">
https://gfycat.com/groundedwarpediberiannase
</div><figcaption>GraphQL Subscriptions live in the <a rel="noreferrer noopener" href="https://github.com/apollostack/GitHunt-React" target="_blank">GitHunt</a> example app.</figcaption></figure>



<h2 class="wp-block-heading" id="4d42"><a href="#the-design" aria-hidden="true" class="aal_anchor" id="the-design"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>The Design</h2>



Our GraphQL subscriptions implementation leverages existing publish-subscribe systems, like the design Facebook uses for their production apps,&nbsp;<a href="https://medium.com/apollo-stack/new-features-in-graphql-batch-defer-stream-live-and-subscribe-7585d0c28b07" target="_blank" rel="noreferrer noopener">according to their conference talks</a>.



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="433" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_UlqbA-unMRv9EFdUcRfzEg-1024x433.png" alt="" class="wp-image-330" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_UlqbA-unMRv9EFdUcRfzEg-1024x433.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_UlqbA-unMRv9EFdUcRfzEg-300x127.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_UlqbA-unMRv9EFdUcRfzEg-768x324.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_UlqbA-unMRv9EFdUcRfzEg.png 1032w" sizes="(max-width: 1024px) 100vw, 1024px" /><figcaption>Subscriptions in GraphQL using a publish-subscribe system, as presented by Laney Kuenzel from Facebook</figcaption></figure>



Clients specify the data they would like to subscribe to by sending a query with the subscription keyword to the server:



<pre class="wp-block-preformatted">subscription comments($repoName: String!) { newComments(repoName: $repoName) { content postedBy { username } postedAt } }</pre>



Based on the subscription field name “newComments” and a mapping from subscription names to channels, the server subscribes to one or more pub/sub channels.&nbsp;When something is published to one of these channels, the server runs the GraphQL query specified in the subscription and sends a full new result to the client.



On the client the developer specifies the name of the subscription and any relevant arguments, and on the server the developer specifies rules for when that subscription should re-run. For instance, on a social media website, a client can subscribe to data changes such as new comments, edited posts, and more.



Subscriptions — unlike queries or mutations — can deliver more than one result, so a long-lived connection is necessary. In our implementation, we use a WebSocket connection to implement a basic subscription protocol. The&nbsp;<a href="https://www.npmjs.com/package/subscriptions-transport-ws" target="_blank" rel="noreferrer noopener">npm package</a>&nbsp;we created for this is completely independent from Apollo Client or&nbsp;<a href="https://github.com/apollostack/apollo-server" target="_blank" rel="noreferrer noopener">Apollo Server</a>, and can be used with any JavaScript client and Node.js server.



<h3 class="wp-block-heading" id="4a73"><a href="#publish-subscribe" aria-hidden="true" class="aal_anchor" id="publish-subscribe"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Publish-subscribe</h3>



GraphQL subscriptions are based on a simple publish-subscribe system. In our server-side subscriptions package, when a client makes a subscription, we simply use a map from one subscription name to one or more channel names to subscribe to the right channels. The subscription query will be re-run every time something is published to one of these channels. We think a common pattern will be to publish mutation results to a channel, so a subscription can send a new result to clients whenever a mutation happens. This is why some people call subscriptions&nbsp;the result of someone else’s mutation.



The diagram below details the life of&nbsp;subscription getNewestComment, and how it is triggered during the&nbsp;submitComment&nbsp;mutation by publishing to the&nbsp;submitComment&nbsp;channel.



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="936" height="765" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_aBp8M-GPgIiRXVVL6fkyjA.png" alt="" class="wp-image-329" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_aBp8M-GPgIiRXVVL6fkyjA.png 936w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_aBp8M-GPgIiRXVVL6fkyjA-300x245.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_aBp8M-GPgIiRXVVL6fkyjA-768x628.png 768w" sizes="(max-width: 936px) 100vw, 936px" /><figcaption>In this case, we are subscribing to an event fired by a mutation, but the event could come from anywhere, like Redis, a database polling system, or a message bus.</figcaption></figure>



<h2 class="wp-block-heading" id="4315"><a href="#the-implementation" aria-hidden="true" class="aal_anchor" id="the-implementation"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>The Implementation</h2>



To demonstrate how to wire our web socket GraphQL subscription package with Apollo Client and a JavaScript GraphQL server, we’ll go through how subscriptions work in&nbsp;<a href="https://github.com/apollostack/GitHunt-React" target="_blank" rel="noreferrer noopener">GitHunt</a>, our example app for Apollo Client. If you want to see the exact changes we made to add subscriptions, check out the pull requests for the&nbsp;<a href="https://github.com/apollostack/GitHunt-React/pull/87" target="_blank" rel="noreferrer noopener">client</a>&nbsp;and the&nbsp;<a href="https://github.com/apollostack/GitHunt-API/pull/15" target="_blank" rel="noreferrer noopener">server</a>.



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow">We now merged and released updated versions of all libraries and docs, to check these out looks at those links:<a href="http://dev.apollodata.com/react/subscriptions.html" target="_blank" rel="noreferrer noopener">Subscriptions with React docs</a><a href="http://dev.apollodata.com/tools/graphql-subscriptions/index.html" target="_blank" rel="noreferrer noopener">Subscriptions on the server docs</a></blockquote>



<h3 class="wp-block-heading" id="7ecf"><a href="#client" aria-hidden="true" class="aal_anchor" id="client"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Client</h3>



To take advantage of subscriptions in Apollo, we made an npm package called&nbsp;<a href="https://github.com/apollostack/subscriptions-transport-ws" target="_blank" rel="noreferrer noopener">subscriptions-transport-ws</a>, which implements a WebSocket subscription protocol. We can use that package to add subscription capabilities when we create the network interface used by Apollo Client:



<pre class="wp-block-preformatted">import { Client, addGraphQLSubscriptions } from 'subscriptions-transport-ws';const wsClient = new Client('ws://localhost:8080');const networkInterface = createNetworkInterface({ uri: '/graphql', opts: { credentials: 'same-origin', }, });const networkInterfaceWithSubscriptions = addGraphQLSubscriptions( networkInterface, wsClient, );const client = new ApolloClient({ networkInterface: networkInterfaceWithSubscriptions, // ... });</pre>



<hr class="wp-block-separator"/>



We will use a subscription called&nbsp;commentAdded&nbsp;as an example. Our subscription listens for new comments on the comments page for a specific repository. On the client, we use the subscription API of Apollo Client to set up the subscription when the CommentsPage component mounts:



<pre class="wp-block-preformatted">componentDidMount() { const repoName = this.props.entry.repository.full_name; const updateQueryFunction = this.props.updateCommentsQuery; this.subscribe(repoName, updateQueryFunction); }subscribe(repoName, updateQuery){ // call the "subscribe" method on Apollo Client this.subscriptionObserver = this.props.client.subscribe({ query: SUBSCRIPTION_QUERY, variables: { repoFullName: repoName }, }).subscribe({ next(data) { // ... call updateQuery to integrate the new comment // into the existing list of comments }, error(err) { console.error('err', err); }, }); }</pre>



ApolloClient.subscribe&nbsp;takes a query and variables, and returns an observable. We then call&nbsp;subscribe&nbsp;on the observable, and give it a&nbsp;next&nbsp;function which will call&nbsp;updateQuery. updateQuery&nbsp;specifies how we want our query result to be updated when given the subscription result. Note that this is very similar to how&nbsp;updateQueries&nbsp;works in Apollo Client’s&nbsp;mutate&nbsp;function, as detailed&nbsp;<a href="https://medium.com/apollo-stack/mutations-and-optimistic-ui-in-apollo-client-517eacee8fb0#.rxmh0bblm" target="_blank" rel="noreferrer noopener">here</a>.



When we’re no longer interested in data, we simply call unsubscribe on the observable, which will stop the subscription.



<h3 class="wp-block-heading" id="3888"><a href="#server" aria-hidden="true" class="aal_anchor" id="server"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Server</h3>



On the server we need to start a WebSocket server that implements the subscriptions protocol from the&nbsp;<a href="https://github.com/apollostack/subscriptions-transport-ws" target="_blank" rel="noreferrer noopener">subscriptions-transport-ws</a>&nbsp;package. To make each part as reusable as possible, we separated the GraphQL and publish-subscribe parts of our implementation from the transport implementation.



The part that actually handles the subscriptions is in a package we called&nbsp;<a href="https://github.com/apollostack/graphql-subscriptions" target="_blank" rel="noreferrer noopener">graphql-subscriptions</a>. From that package, we import SubscriptionManager and pass it to the WebSocket server as an argument:



<pre class="wp-block-preformatted">import { PubSub, SubscriptionManager } from 'graphql-subscriptions'; import schema from './schema';// the default PubSub is based on EventEmitters. It can easily // be replaced with one different one, e.g. Redis const pubsub = new PubSub();const subscriptionManager = new SubscriptionManager({ schema, pubsub, setupFunctions: { commentAdded: (options, args) =&gt; ({ commentAdded: comment =&gt; comment.repository_name === args.repoFullName, }), }, });export { subscriptionManager, pubsub };</pre>



setupFunctionsis a core part of the subscriptions API on the server: it’s a map of subscription names to channel names and filter functions. In our example, the&nbsp;commentAdded&nbsp;subscription subscribes to a channel of the same name, and runs the subscription query whenever the repository name of the new comment is the same and the&nbsp;repoFullName&nbsp;argument is provided to the subscription.



The&nbsp;subscriptionManager&nbsp;can work with any pub-sub package that exposes publish, subscribe and unsubscribe methods. In our example, we built a very simple package based on Node event emitters. If you want to use subscriptions in production, you should use&nbsp;<a href="https://medium.com/u/c544f341ba49?source=post_page-----9a2457f015fb----------------------" target="_blank" rel="noreferrer noopener">David Yahalomi</a>’s excellent&nbsp;<a href="https://github.com/davidyaha/graphql-redis-subscriptions" target="_blank" rel="noreferrer noopener">package based on Redis</a>&nbsp;instead, which he’ll explain in an upcoming post.



Next, we simply need to import the same PubSub instance and publish to the&nbsp;commentAdded&nbsp;channel when we run the&nbsp;submitComment&nbsp;mutation. We use the value returned by the mutation resolver as the payload, which gets passed directly into the subscription query as the GraphQL&nbsp;rootValue. If you follow that convention, a subscription really is the result of somebody else’s mutation!



<pre class="wp-block-preformatted">submitComment: (_, { repoFullName, commentContent }, context) =&gt; { return Promise.resolve() .then(() =&gt; ( // Save comment to DB context.Comments.submitComment( repoFullName, context.user.login, commentContent ) )) .then(([id]) =&gt; // Get new comment to return context.Comments.getCommentById(id) ) .then(comment =&gt; { // Publish subscription notification with the whole comment pubsub.publish('commentAdded', comment); return comment; }); }, }</pre>



<hr class="wp-block-separator"/>



With the subscriptionManager and the publication set up, all we need to do is wire it up to our WebSocket server and start it!



<pre class="wp-block-preformatted">import { createServer } from 'http'; import { Server } from 'subscriptions-transport-ws';const httpServer = createServer((request, response) =&gt; { response.writeHead(404); response.end(); });httpServer.listen(WS_PORT, () =&gt; console.log( `Websocket Server is now running on <a href="http://localhost:$/" target="_blank" rel="noreferrer noopener">http://localhost:$</a>{WS_PORT}` ));const server = new Server({ subscriptionManager }, httpServer);</pre>



That’s it; now our GraphQL subscriptions are all set up to listen to new comments! All in all, it’s just a few new lines on the client and server. You can see exactly what we did in the pull requests&nbsp;<a href="https://github.com/apollostack/GitHunt-React/pull/87" target="_blank" rel="noreferrer noopener">for the client</a>&nbsp;and&nbsp;<a href="https://github.com/apollostack/GitHunt-API/pull/15" target="_blank" rel="noreferrer noopener">for the server</a>.



<hr class="wp-block-separator"/>



Now that you know how it all works, you can jump right in and see if you can build something great with the packages and examples we provide:



<ol class="wp-block-list"><li><a href="https://github.com/apollostack/graphql-subscriptions" target="_blank" rel="noreferrer noopener">graphql-subscriptions</a>: the server side package that connects GraphQL with a publish-subscribe system.</li><li><a href="https://github.com/apollostack/subscriptions-transport-ws" target="_blank" rel="noreferrer noopener">subscriptions-transport-ws</a>: the package implementing a WebSocket transport protocol for subscriptions</li><li><a href="https://github.com/apollostack/GitHunt-React" target="_blank" rel="noreferrer noopener">GitHunt-React</a>: the client of our example app, which now includes subscriptions</li><li><a href="https://github.com/apollostack/GitHunt-API" target="_blank" rel="noreferrer noopener">GitHunt-API</a>: the server of our example app, including subscriptions.</li><li><a href="http://dev.apollodata.com/react/subscriptions.html" target="_blank" rel="noreferrer noopener">Subscriptions React docs</a>: How to handle subscriptions in your React app</li><li><a href="http://dev.apollodata.com/tools/graphql-subscriptions/index.html" target="_blank" rel="noreferrer noopener">Subscriptions GraphQL Server docs</a>: How to add GraphQL Subscriptions to your Node server</li></ol>



We’re only just getting started with subscriptions in GraphQL — there’s still a lot to do and we’re always looking for contributors and ideas. To get started, just try out the examples, build one of your own and let us know about it, or file an issue or PR on one of our repos!

Subscriptions

Tutorial: GraphQL subscriptions with Apollo Client

GraphQL Subscriptions in Apollo Client

Stay in our orbit