Back to Blog
April 11, 2017

How to Use Subscriptions in GraphiQL

Uri Goldshtein

Uri Goldshtein

There has been a lot of buzz about GraphQL Subscriptions in the community recently, and a lot of people are excited about the subscriptions RFC opened by Rob Zhu from Facebook.

If you haven’t tried GraphQL subscriptions yet, check out our docs to learn how to add subscriptions to your existing Node.js GraphQL server. You can also easily try building a React app with them by following Graphcool’s tutorial.

Today, I want to tell you about something else that’s really cool: Did you know that GraphiQL already supports subscriptions today? Don’t believe me? Here’s a demo so you can see for yourself:

Check out the working example of GitHunt with GraphiQL here (and the React frontend here).

How it works

The standard GraphiQL library already supports passing in a fetcher that returns an observable or promise. That means that anyone can configure it with their own transport, even if it supports multiple results. We’ve already done that for you, using a new<a href="https://github.com/apollographql/GraphiQL-Subscriptions-Fetcher" target="_blank" rel="noreferrer noopener">graphql-subscriptions-fetcher</a>, so you don’t have to.

The following steps are all you need to do. (We’re using graphql-server-express for the example.)

First, make sure you have the latest graphql-server-express package:

npm install —-save graphql-server-express

Now, all you need to do is to set a new field we added to graphqlExpress config, called subscriptionsEndpoint, with the Websocket URL subscriptions endpoint (this is the same endpoint you use in your SubscriptionClient). For example:

app.use(‘/graphiql’, graphiqlExpress({
  endpointURL: ‘/graphql’,
  subscriptionsEndpoint: `ws://localhost:3000/subscriptions`,
}));

That’s it! Finally, all you have to do is start your server, open your browser in http://localhost:3000/graphiql, write a GraphQL subscriptions query inside, and the published data from the server will be pushed into your GraphiQL client and displayed in the result screen of GraphiQL.

This example uses GraphQL server with express — but it also works with graphql-server-hapi, Koa, Restify and Lambda. Just add the <em>subscriptionsEndpoint</em> field to your GraphiQL configuration and you are good to go! You can also check out the live GitHunt example here.

What if you don’t use graphql-server?

We added the new GraphiQL subscriptions support to graphql-server by default, but in case you’re not using it, it’s still very easy to add that support to your own server.

GraphiQL is usually served as static HTML (here’s how we do it in graphql-server), so first you need to load <a href="https://github.com/apollographql/subscriptions-transport-ws" target="_blank" rel="noreferrer noopener">subscriptions-transport-ws</a> and <a href="https://github.com/apollographql/GraphiQL-Subscriptions-Fetcher" target="_blank" rel="noreferrer noopener">graphql-subscriptions-fetcher</a> inside the <head> tag. We’ve published the transport client so that it’s easy to use in a script tag from Unpkg:

<script src=”//unpkg.com/subscriptions-transport-ws@0.5.4/browser/client.js”></script><script src="//unpkg.com/graphiql-subscriptions-fetcher@0.0.2/browser/client.js"></script>

Next, you need to create a SubscriptionClient with your subscriptions endpoint:

var subscriptionsClient = new window.SubscriptionsTransportWs.SubscriptionClient(‘YOUR_SUBSCRIPTIONS_ENDPOINT_HERE’, { reconnect: true });var subscriptionsFetcher = window.SubscriptionsTransportWs.graphQLFetcher(subscriptionsClient, graphQLFetcher);

Finally, replace the regular graphqlFetcher you use in GraphiQL with the one that uses the fetcher from <a href="https://github.com/apollographql/GraphiQL-Subscriptions-Fetcher" target="_blank" rel="noreferrer noopener">graphql-subscriptions-fetcher</a> when creating your GraphiQL instance:

ReactDOM.render(
  React.createElement(GraphiQL, {
    fetcher: subscriptionsFetcher,
    onEditQuery: onEditQuery,
    onEditVariables: onEditVariables,
    onEditOperationName: onEditOperationName,
    query: ${safeSerialize(queryString)},
    response: ${safeSerialize(resultString)},
    variables: ${safeSerialize(variablesString)},
    operationName: ${safeSerialize(operationName)},
}), document.body);

Here is a complete example of how it should look.

What’s happening behind the scenes?

<a href="https://github.com/apollographql/subscriptions-transport-ws" target="_blank" rel="noreferrer noopener">subscriptions-transport-ws</a>is a GraphQL subscriptions network transport. Loading it into GraphiQL client and replacing the graphQLFetcher function with <a href="https://github.com/apollographql/GraphiQL-Subscriptions-Fetcher" target="_blank" rel="noreferrer noopener">graphql-subscriptions-fetcher</a>’s fetcher will give you a plug-and-play solution for live-stream subscriptions into your app’s GraphiQL editor!

Note that we are still using the original <em>graphQLFetcher</em> inside the new fetcher. We fall back to the original for GraphQL operations that aren’t subscriptions (queries and mutations).

Try it today!

Even though GraphQL subscriptions are still at the RFC stage, it is already being used by many companies in production, and the libraries and tools have been evolving to support a wide range of use cases. So try GraphQL subscriptions in order to add real time ability to your apps today!

Written by

Uri Goldshtein

Uri Goldshtein

Read more by Uri Goldshtein

Recommended