You are viewing documentation for a previous version of this software.

Switch to the latest stable version.

Integrating with Meteor

Specifics about using Apollo in your Meteor application.

There are two main ways to use Apollo in your Meteor app:

  • meteor add swydo:ddp-apollo provides a network Link that supports Meteor user accounts and subscriptions, all over DDP: Documentation

  • meteor add apollo supports Meteor user accounts over HTTP, with documentation below.

Compatibility

meteor/apolloapollo clientapollo server
3.*2.*2.*
2.*2.*1.*
1.*1.*1.*

Usage

shell
1meteor add apollo
2meteor npm install graphql apollo-server-express apollo-boost

Client

Create your ApolloClient instance:

JavaScript
1import { Accounts } from 'meteor/accounts-base'
2import ApolloClient from 'apollo-boost'
3
4const client = new ApolloClient({
5  uri: '/graphql',
6  request: operation =>
7    operation.setContext(() => ({
8      headers: {
9        authorization: Accounts._storedLoginToken()
10      }
11    }))
12})

Or if you're using apollo-client instead of apollo-boost, use MeteorAccountsLink():

JavaScript
1import { ApolloClient } from 'apollo-client'
2import { InMemoryCache } from 'apollo-cache-inmemory'
3import { ApolloLink } from 'apollo-link'
4import { HttpLink } from 'apollo-link-http'
5import { MeteorAccountsLink } from 'meteor/apollo'
6
7const client = new ApolloClient({
8  link: ApolloLink.from([
9    new MeteorAccountsLink(),
10    new HttpLink({
11      uri: '/graphql'
12    })
13  ]),
14  cache: new InMemoryCache()
15})

If you want to change which header the token is stored in:

JavaScript
1MeteorAccountsLink({ headerName: 'meteor-login-token' })

(The default is authorization.)

Server

Set up the Apollo server:

JavaScript
1import { ApolloServer, gql } from 'apollo-server-express'
2import { WebApp } from 'meteor/webapp'
3import { getUser } from 'meteor/apollo'
4
5import typeDefs from './schema'
6import resolvers from './resolvers'
7
8const server = new ApolloServer({
9  typeDefs,
10  resolvers,
11  context: async ({ req }) => ({
12    user: await getUser(req.headers.authorization)
13  })
14})
15
16server.applyMiddleware({
17  app: WebApp.connectHandlers,
18  path: '/graphql'
19})
20
21WebApp.connectHandlers.use('/graphql', (req, res) => {
22  if (req.method === 'GET') {
23    res.end()
24  }
25})

Now when the client is logged in (ie has an unexpired Meteor login token in localStorage), your resolvers will have a context.user property with the user doc.

IDE

There are two options for using an IDE that will make authenticated GraphQL requests:

  • Apollo devtools GraphiQL:

    • Login to your app

    • Open Apollo devtools to the GraphiQL section

  • GraphQL Playground:

    • Install with brew cask install graphql-playground

    • Login to your app

    • In the browser console, enter localStorage.getItem('Meteor.loginToken')

    • Copy the string returned

    • In Playground:

      • At the top, enter http://localhost:3000/graphql

      • Under HTTP HEADERS, enter { "authorization": "copied string" }

Typings

Your Meteor apps may rely on static typings with TypeScript. If so, it is recommended to use the ambient TypeScript definition for this Atmosphere package.

Accounts

The above solutions assume you're using Meteor's client-side accounts functions like Accounts.createUser and Accounts.loginWith*, which use Meteor DDP messages.

If you want to instead only use GraphQL in your app, you can use nicolaslopezj:apollo-accounts. This package uses the Meteor Accounts methods in GraphQL, and it's compatible with the accounts you have saved in your database (and you could use nicolaslopezj:apollo-accounts and Meteor's DDP accounts at the same time).

If you are relying on the current user in your queries, you'll want to clear the store when the current user state changes. To do so, use client.resetStore() in the Meteor.logout callback:

Text
1// The `client` variable refers to your `ApolloClient` instance.
2// It would be imported in your template,
3// or passed via props thanks to `withApollo` in React for example.
4
5Meteor.logout(function() {
6  return client.resetStore(); // make all active queries re-run when the log-out process completed
7});

SSR

There are two additional configurations that you need to keep in mind when using React Server Side Rendering with Meteor.

  1. Use isomorphic-fetch to polyfill fetch server-side (used by Apollo Client's network interface).

  2. Connect your express server to Meteor's existing server with WebApp.connectHandlers.use

  3. Do not end the connection with res.send() and res.end() use req.dynamicBody and req.dynamicHead instead and call next(). more info

The idea is that you need to let Meteor to finally render the html you can just provide it extra body and or head for the html and Meteor will append it, otherwise CSS/JS and or other merged html content that Meteor serve by default (including your application main .js file) will be missing.

Here is a full working example using apollo@2.* (outdated):

Text
1meteor add apollo webapp
2meteor npm install --save react react-dom apollo-client redux react-apollo react-router react-helmet express isomorphic-fetch
JavaScript
1import { Meteor } from 'meteor/meteor';
2import { WebApp } from 'meteor/webapp';
3import { meteorClientConfig, createMeteorNetworkInterface } from 'meteor/apollo';
4import React from 'react';
5import ReactDOM from 'react-dom/server';
6import ApolloClient from 'apollo-client';
7import { createStore, combineReducers, applyMiddleware, compose } from 'redux';
8import { ApolloProvider, renderToStringWithData } from 'react-apollo';
9import { match, RouterContext } from 'react-router';
10import Express from 'express';
11// #1 import isomorphic-fetch so the network interface can be created
12import 'isomorphic-fetch';
13import Helmet from 'react-helmet';
14
15import routes from '../both/routes';
16import rootReducer from '../../ui/reducers';
17import Body from '../both/routes/body';
18
19// 1# do not use new
20const app = Express(); // eslint-disable-line new-cap
21
22app.use((req, res, next) => {
23  match({ routes, location: req.originalUrl }, (error, redirectLocation, renderProps) => {
24    if (redirectLocation) {
25      res.redirect(redirectLocation.pathname + redirectLocation.search);
26    } else if (error) {
27      console.error('ROUTER ERROR:', error); // eslint-disable-line no-console
28      res.status(500);
29    } else if (renderProps) {
30      // use createMeteorNetworkInterface to get a preconfigured network interface
31      // #1 network interface can be used server-side thanks to polyfilled `fetch`
32      const networkInterface = createMeteorNetworkInterface({
33        opts: {
34          credentials: 'same-origin',
35          headers: req.headers,
36        },
37        // possible current user login token stored in the cookies thanks to
38        // a third-party package like meteorhacks:fast-render
39        loginToken: req.cookies['meteor-login-token'],
40      });
41
42      // use meteorClientConfig to get a preconfigured Apollo Client options object
43      const client = new ApolloClient(meteorClientConfig({ networkInterface }));
44
45      const store = createStore(
46        combineReducers({
47          ...rootReducer,
48          apollo: client.reducer(),
49        }),
50        {}, // initial state
51        compose(
52          applyMiddleware(client.middleware()),
53        ),
54      );
55
56      const component = (
57        <ApolloProvider store={store} client={client}>
58          <RouterContext {...renderProps} />
59        </ApolloProvider>
60      );
61
62      renderToStringWithData(component).then((content) => {
63        const initialState = client.store.getState()[client.reduxRootKey].data;
64        // the body content we want to append
65        const body = <Body content={content} state={initialState} />;
66        // #3 `req.dynamicBody` will hold that body and meteor will take care of
67        // actually appending it to the end result
68        req.dynamicBody = ReactDOM.renderToStaticMarkup(body);
69        const head = Helmet.rewind();
70        // #3 `req.dynamicHead` in this case we use `react-helmet` to add seo tags
71        req.dynamicHead = `  ${head.title.toString()}
72  ${head.meta.toString()}
73  ${head.link.toString()}
74`;
75        // #3 Important we do not want to return this, we just let meteor handle it
76        next();
77      });
78    } else {
79      console.log('not found'); // eslint-disable-line no-console
80    }
81  });
82});
83// #2 connect your express server with meteor's
84WebApp.connectHandlers.use(Meteor.bindEnvironment(app));

Importing .graphql files

An easy way to work with GraphQL is by importing .graphql files directly using the import syntax.

Bash
1meteor add swydo:graphql

Instead of the /imports/api/schema.js file, create a /imports/api/schema.graphql file with the same content as before:

GraphQL
1type Query {
2  say: String
3}

One of the benefits you'll get right away is good highlighting by GitHub and your IDE!

Now we can import the schema:

JavaScript
1import typeDefs from '/imports/api/schema.graphql';

Use typeDefs as before in the above examples. You can pass it directly to makeExecutableSchema like before.

The import syntax will also work for any other .graphql file besides your main schema. So you'll be able to import query, mutation and subscription files without needing to manually parse them with the graphql-tag.

For more benefits, see the GrahpQL build plugin README.

Blaze

If you are looking to integrate Apollo with Blaze, you can use the swydo:blaze-apollo package:

JavaScript
1import { setup } from 'meteor/swydo:blaze-apollo';
2
3const client = new ApolloClient(meteorClientConfig());
4
5setup({ client });

This gives you reactive GraphQL queries in your templates!

JavaScript
1Template.hello.helpers({
2  hello() {
3    return Template.instance().gqlQuery({
4      query: HELLO_QUERY
5    }).get();
6  }
7});

Subscriptions

This section uses the outdated apollo@2.* API.

You can also use GraphQL subscriptions with your Meteor app if you need to. The following code gives an example of a complete configuration that enables all the features of subscriptions in addition to base GraphQL.

Client

JavaScript
1import { ApolloClient } from 'apollo-client';
2import { SubscriptionClient, addGraphQLSubscriptions } from 'subscriptions-transport-ws';
3import { getMeteorLoginToken, createMeteorNetworkInterface } from 'meteor/apollo';
4
5// "basic" Meteor network interface
6const networkInterface = createMeteorNetworkInterface();
7
8// create a websocket uri based on your app absolute url (ROOT_URL), ex: ws://localhost:3000
9const websocketUri = Meteor.absoluteUrl('subscriptions').replace(/^http/, 'ws');
10
11// create a websocket client
12const wsClient = new SubscriptionClient(websocketUri, {
13  reconnect: true,
14  // pass some extra information to the subscription, like the current user:
15  connectionParams: {
16    // getMeteorLoginToken = get the Meteor current user login token from local storage
17    meteorLoginToken: getMeteorLoginToken(),
18  },
19});
20
21// enhance the interface with graphql subscriptions
22const networkInterfaceWithSubscriptions = addGraphQLSubscriptions(networkInterface, wsClient);
23
24// enjoy graphql subscriptions with Apollo Client
25const client = new ApolloClient({ networkInterface: networkInterfaceWithSubscriptions });

Server

The same context is used for both the resolvers and the GraphQL subscriptions. This also means that authentication in the websocket transport is configured out-of-the-box.

Note that PubSub from graphql-subscriptions is not suitable for production. You should wire your SubscriptionManager with Redis subscriptions or MQTT subscriptions in case you want to use them in production apps.

JavaScript
1import { SubscriptionManager } from 'graphql-subscriptions';
2import { SubscriptionServer } from 'subscriptions-transport-ws';
3import { createApolloServer, addCurrentUserToContext } from 'meteor/apollo';
4
5// your executable schema
6const schema = ...
7
8// any additional context you use for your resolvers, if any
9const context = {};
10
11// the pubsub mechanism of your choice, for instance:
12// - PubSub from graphql-subscriptions (not recommended for production)
13// - RedisPubSub from graphql-redis-subscriptions
14// - MQTTPubSub from graphql-mqtt-subscriptions
15const pubsub = new PubSub();
16
17// subscriptions path which fits witht the one you connect to on the client
18const subscriptionsPath = '/subscriptions';
19
20// start a graphql server with Express handling a possible Meteor current user
21createApolloServer({
22  schema,
23  context
24});
25
26// create the subscription manager thanks to the schema & the pubsub mechanism
27const subscriptionManager = new SubscriptionManager({
28  schema,
29  pubsub,
30});
31
32// start up a subscription server
33new SubscriptionServer(
34  {
35    subscriptionManager,
36    // on connect subscription lifecycle event
37    onConnect: async (connectionParams, webSocket) => {
38      // if a meteor login token is passed to the connection params from the client,
39      // add the current user to the subscription context
40      const subscriptionContext = connectionParams.meteorLoginToken
41        ? await addCurrentUserToContext(context, connectionParams.meteorLoginToken)
42        : context;
43
44      return subscriptionContext;
45    },
46  },
47  {
48    // bind the subscription server to Meteor WebApp
49    server: WebApp.httpServer,
50    path: subscriptionsPath,
51  }
52);
Feedback

Edit on GitHub

Forums