Subscriptions

In addition to fetching data using queries and modifying data using mutations, the GraphQL spec also has a third operation type, called subscription.

GraphQL Subscriptions is a way to push data from the server to the clients that choose to listen to real time messages from the server.

Subscriptions are similar to queries in that they specify the selection set (list of fields) that the client is requesting, but instead of immediately returning a single answer, a result is sent every time a specified event happens on the server.

A common use-case for subscriptions is notifying the client side of changes based on events, for example the creation of a new object, updated fields and so on.

GraphQL subscriptions have to be defined in the schema:

1
2
3
type Subscription {
commentAdded(repoFullName: String!): Comment
}

A client can subscribe by sending a subscription query:

1
2
3
4
5
6
subscription onCommentAdded($repoFullName: String!){
commentAdded(repoFullName: $repoFullName){
id
content
}
}

The response sent to the client looks as follows:

1
2
3
4
5
6
7
8
{
"data": {
"commentAdded": {
"id": "123",
"content": "Hello!"
}
}
}

In the above example, the subscription is expected to send a new result every time a comment is added on GitHunt for a specific repository. Note that the code above only defines the GraphQL subscription in the schema. Read setting up subscriptions on the client and setting up GraphQL subscriptions for the server to learn how to add subscriptions to your app.

Subscriptions are a good alternative to polling when the initial state is large, but the incremental change sets are small. The starting state can be fetched with a query and subsequently updated through a subscription.

Setting up subscriptions on the client

To start using GraphQL subscriptions on the client with a Websocket transport, install subscriptions-transport-ws from npm:

1
npm install --save subscriptions-transport-ws

subscriptions-transport-ws is an transport implementation for subscriptions that works with any server or client, not only Apollo.

Read here on how to setup GraphQL subscriptions on your server.

Then, create a GraphQL subscriptions transport client (SubscriptionClient):

1
2
3
4
5
import { SubscriptionClient } from 'subscriptions-transport-ws';
const wsClient = new SubscriptionClient(`http://localhost:5000/`, {
reconnect: true
});

Then, extend your existing Apollo-Client network interface using the addGraphQLSubscriptions function:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import { SubscriptionClient, addGraphQLSubscriptions } from 'subscriptions-transport-ws';
// Create a normal network interface:
const networkInterface = createNetworkInterface({
uri: 'http://localhost:3000'
});
// Extend the network interface with the WebSocket
const networkInterfaceWithSubscriptions = addGraphQLSubscriptions(
networkInterface,
wsClient
);
// Finally, create your ApolloClient instance with the modified network interface
const apolloClient = new ApolloClient({
networkInterface: networkInterfaceWithSubscriptions
});

subscribeToMore

With GraphQL subscriptions your client will be alerted on push from the server and you should choose the pattern that fits your application the most:

  • Use it as a notification and run any logic you want when it fires, for example alerting the user or refetching data
  • Use the data sent along with the notification and merge it directly into the store (existing queries are automatically notified)

With subscribeToMore, you can easily do the latter.

subscribeToMore is a function available on every query result in react-apollo. It works just like fetchMore, except that the update function gets called every time the subscription returns, instead of only once.

Here is a regular query:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import { CommentsPage } from './comments-page.js';
import { graphql } from 'react-apollo';
import gql from 'graphql-tag';
const COMMENT_QUERY = gql`
query Comment($repoName: String!) {
entry(repoFullName: $repoName) {
comments {
id
content
}
}
}
`;
const withData = graphql(COMMENT_QUERY, {
name: 'comments',
options: ({ params }) => ({
variables: {
repoName: `${params.org}/${params.repoName}`
},
})
});
export const CommentsPageWithData = withData(CommentsPage);

Now, let’s add the subscription.

Add a function called subscribeToNewComments that will subscribe using subscribeToMore and update the query’s store with the new data using updateQuery:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
const COMMENTS_SUBSCRIPTION = gql`
subscription onCommentAdded($repoFullName: String!){
commentAdded(repoFullName: $repoFullName){
id
content
}
}
`;
const withData = graphql(COMMENT_QUERY, {
name: 'comments',
options: ({ params }) => ({
variables: {
repoName: `${params.org}/${params.repoName}`
},
}),
props: props => {
return {
subscribeToNewComments: params => {
return props.comments.subscribeToMore({
document: COMMENTS_SUBSCRIPTION,
variables: {
repoName: params.repoFullName,
},
updateQuery: (prev, {subscriptionData}) => {
if (!subscriptionData.data) {
return prev;
}
const newFeedItem = subscriptionData.data.commentAdded;
return Object.assign({}, prev, {
entry: {
comments: [newFeedItem, ...prev.entry.activities]
}
});
}
});
}
};
},
});

and start the actual subscription by calling the subscribeToNewComments function with the subscription variables:

1
2
3
4
5
6
7
8
9
10
11
12
export class CommentsPage extends Component {
static propTypes = {
repoFullName: PropTypes.string.isRequired,
subscribeToNewComments: PropTypes.func.isRequired,
}
componentWillMount() {
this.props.subscribeToNewComments({
repoFullName: this.props.repoFullName,
});
}
}

Authentication over WebSocket

In many cases it is necessary to authenticate clients before allowing them to receive subscription results. To do this, the SubscriptionClient constructor accepts a connectionParams field, which passes a custom object that the server can use to validate the connection before setting up any subscriptions.

1
2
3
4
5
6
7
8
import {SubscriptionClient} from 'subscriptions-transport-ws';
const wsClient = new SubscriptionClient(`http://localhost:5000/`, {
reconnect: true,
connectionParams: {
authToken: user.authToken,
},
});

You can use connectionParams for anything else you might need, not only authentication, and check its payload on the server side with SubscriptionsServer.

Edit on GitHub