How to Use Subscriptions in GraphiQL
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:
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.
graphql-server?
What if you don’t useWe 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!