🚀 An ember-cli addon for Apollo Client and GraphQL
Clone or download
Latest commit a0bae6d Oct 18, 2018
Permalink
Failed to load latest commit information.
addon replace deprecated use of merge with assign Oct 1, 2018
app remove initializer, get config from environment Sep 26, 2017
blueprints/ember-apollo-client Replacing custom webpack broccoli plugin with e-auto-import Aug 30, 2018
config Fix ESLint issues after Prettier integration Jul 7, 2018
tests Merge pull request #170 from lennyburdette/watchQuery-resultKey Sep 19, 2018
vendor Initial Commit from Ember CLI v2.10.0 Jan 9, 2017
.editorconfig Initial Commit from Ember CLI v2.10.0 Jan 9, 2017
.ember-cli disable analytics Jan 9, 2017
.eslintignore ember-cli-update to v3.2.0 (#149) Jul 16, 2018
.eslintrc.js ember-cli-update to v3.2.0 (#149) Jul 16, 2018
.gitignore ember-cli-update to v3.2.0 (#149) Jul 16, 2018
.gqlconfig get vscode gql integration working, fix broken queries Apr 12, 2018
.npmignore ember-cli-update to v3.2.0 (#149) Jul 16, 2018
.prettierrc.js Fix ESLint issues after Prettier integration Jul 7, 2018
.travis.yml update node Mar 28, 2018
.watchmanconfig Initial Commit from Ember CLI v2.10.0 Jan 9, 2017
CHANGELOG.md add changelog for v2.0.0-beta.1 Sep 19, 2018
LICENSE.md ember v2.18 Jan 14, 2018
README.md tweak readme intro Oct 18, 2018
ember-cli-build.js Fix ESLint issues after Prettier integration Jul 7, 2018
index.js Replacing custom webpack broccoli plugin with e-auto-import Aug 30, 2018
package.json v2.0.0-beta.1 Sep 19, 2018
testem.js ember-cli-update to v3.2.0 (#149) Jul 16, 2018
yarn.lock Replacing custom webpack broccoli plugin with e-auto-import Aug 30, 2018

README.md

ember-apollo-client

Use apollo-client and GraphQL from your Ember app.

Download count all time npm version Travis CI Build Status Ember Observer Score

This addon exposes the following dependencies to an ember application:

You may want to install these optional dependencies as well:

This addon is battle tested: it has been used to build several large apps. As such, we've solved real-world problems such as reliable testing and preventing resource leaks by unsubscribing from watch queries.

Installation

ember install ember-apollo-client

This should also automatically install ember-fetch.

Install the Apollo Client Developer tools for Chrome for a great GraphQL developer experience!

Compatibility

This addon works and is fully tested with:

  • Ember.js 2.12+
  • FastBoot 1.0+

Example App

If you are looking for a full tutorial using ember-apollo-client check out the tutorial on How To GraphQL, written by DevanB.

The application built in the tutorial is also available on the How To GraphQL repository.

Configuration

In your app's config/environment.js, configure the URL for the GraphQL API.

let ENV = {
  ...
  apollo: {
    apiURL: 'https://test.example/graphql',
    // Optionally, set the credentials property of the Fetch Request interface
    // to control when a cookie is sent:
    // requestCredentials: 'same-origin', // other choices: 'include', 'omit'
  },
  ...
}

Additional configuration of the ApolloClient can be done by extending the Apollo service and overriding the clientOptions property. See the Apollo Service API for more info.

Dependencies

This addon uses ember-auto-import to import dependencies.

If you desire any additional graphql dependencies, install them with npm/yarn and import as desired.

Usage

Fetching data

GraphQL queries should be placed in external files, which are automatically made available for import:

app/gql/queries/human.graphql

query human($id: String!) {
  human(id: $id) {
    name
  }
}

Though it is not recommended, you can also use the graphql-tag package to write your queries within your JS file:

import gql from "graphql-tag";

const query = gql`
  query human($id: String!) {
    human(id: $id) {
      name
    }
  }
`;

Within your routes, you can query for data using the RouteQueryManager mixin and watchQuery:

app/routes/some-route.js

import Route from "@ember/routing/route";
import { RouteQueryManager } from "ember-apollo-client";
import query from "my-app/gql/queries/human";

export default Route.extend(RouteQueryManager, {
  model(params) {
    let variables = { id: params.id };
    return this.get('apollo').watchQuery({ query, variables }, "human");
  }
});

This performs a watchQuery on the ApolloClient. The resulting object is an Ember.Object and therefore has full support for computed properties, observers, etc.

If a subsequent query (such as a mutation) happens to fetch the same data while this query's subscription is still active, the object will immediately receive the latest attributes (just like ember-data).

Please note that when using watchQuery, you must unsubscribe when you're done with the query data. You should only have to worry about this if you're using the Apollo service directly. If you use the RouteQueryManager mixin in your routes, or the ComponentQueryManager in your data-loading components, or the ObjectQueryManager in your data-loading on service or class that extend Ember.Object, all active watch queries are tracked and unsubscribed when the route is exited or the component and Ember.Object is destroyed. These mixins work by injecting a query manager named apollo that functions as a proxy to the apollo service.

You can instead use query if you just want a single query with a POJO response and no watch updates.

If you need to access the Apollo Client ObservableQuery, such as for pagination, you can retrieve it from a watchQuery result using getObservable:

import Route from "@ember/routing/route";
import { getObservable } from "ember-apollo-client";

export default Route.extend(RouteQueryManager, {
  model() {
    let result = this.get('apollo').watchQuery(...);
    let observable = getObservable(result);
    observable.fetchMore(...) // utilize the ObservableQuery
    ...
  }
});

See the detailed query manager docs for more details on usage, or the Apollo service API if you need to use the service directly.

Mutations and Fragments

You can perform a mutation using the mutate method. You can also use GraphQL fragments in your queries. This is especially useful if you want to ensure that you refetch the same attributes in a subsequent query or mutation involving the same model(s).

The following example shows both mutations and fragments in action:

app/gql/fragments/review-fragment.graphql

fragment ReviewFragment on Human {
  stars
  commentary
}

app/gql/mutations/create-review.graphql

#import 'my-app/gql/fragments/review-fragment'

mutation createReview($ep: Episode!, $review: ReviewInput!) {
  createReview(episode: $ep, review: $review) {
    review {
      ...ReviewFragment
    }
  }
}

app/routes/my-route.js

import Route from "@ember/routing/route";
import { inject as service } from "@ember/service";
import EmberObject from "@ember/object";
import mutation from "my-app/gql/mutations/create-review";

export default Route.extend({
  apollo: service(),

  model() {
    return EmberObject.create({});
  },

  actions: {
    createReview(ep, review) {
      let variables = { ep, review };
      return this.get("apollo").mutate({ mutation, variables }, "review");
    }
  }
});

Query manager API

  • watchQuery(options, resultKey): This calls the ApolloClient.watchQuery method. It returns a promise that resolves with an Ember.Object. That object will be updated whenever the watchQuery subscription resolves with new data. As before, the resultKey can be used to resolve beneath the root.

    The query manager will automatically unsubscribe from this object.

  • query(options, resultKey): This calls the ApolloClient.query method. It returns a promise that resolves with the raw POJO data that the query returns. If you provide a resultKey, the resolved data is grabbed from that key in the result.

  • mutate(options, resultKey): This calls the ApolloClient.mutate method. It returns a promise that resolves with the raw POJO data that the mutation returns. As with the query methods, the resultKey can be used to resolve beneath the root.

Apollo service API

You should not need to use the Apollo service directly for most regular usage, instead utilizing the RouteQueryManager, ObjectQueryManager and ComponentQueryManager mixins. However, you will probably need to customize options on the apollo service, and might need to query it directly for some use cases (such as loading data from a service rather than a route or component).

The apollo service has the following public API:

  • clientOptions: This computed property should return the options hash that will be passed to the ApolloClient constructor. You can override this property to configure the client this service uses:

    const OverriddenService = ApolloService.extend({
      clientOptions: computed(function() {
        return {
          link: this.get("link"),
          cache: this.get("cache")
        };
      })
    });
  • link: This computed property provides a list of middlewares and afterwares to the Apollo Link the interface for fetching and modifying control flow of GraphQL requests. To create your middlewares/afterwares:

      link: computed(function() {
        let httpLink = this._super(...arguments);
    
        // Middleware
        let authMiddleware = setContext(async request => {
          if (!token) {
            token = await localStorage.getItem('token') || null;
          }
          return {
            headers: {
              authorization: token
            }
          };
        });
    
        // Afterware
        const resetToken = onError(({ networkError }) => {
          if (networkError && networkError.statusCode === 401) {
            // remove cached token on 401 from the server
            token = undefined;
          }
        });
    
        const authFlowLink = authMiddleware.concat(resetToken);
    
        return authFlowLink.concat(httpLink);
      }),

    Example with ember-simple-auth:

    import { computed } from "@ember/object";
    import { inject as service } from "@ember/service";
    import ApolloService from "ember-apollo-client/services/apollo";
    import { setContext } from "apollo-link-context";
    import { Promise as RSVPPromise } from "rsvp";
    
    const OverriddenService = ApolloService.extend({
      session: service(),
    
      link: computed(function() {
        let httpLink = this._super(...arguments);
    
        let authLink = setContext((request, context) => {
          return this._runAuthorize(request, context);
        });
        return authLink.concat(httpLink);
      }),
    
      _runAuthorize() {
        if (!this.get("session.isAuthenticated")) {
          return {};
        }
        return new RSVPPromise(success => {
          this.get("session").authorize(
            "authorizer:oauth2",
            (headerName, headerContent) => {
              let headers = {};
              headers[headerName] = headerContent;
              success({ headers });
            }
          );
        });
      }
    });
  • watchQuery(options, resultKey): This calls the ApolloClient.watchQuery method. It returns a promise that resolves with an Ember.Object. That object will be updated whenever the watchQuery subscription resolves with new data. As before, the resultKey can be used to resolve beneath the root.

    When using this method, it is important to unsubscribe from the query when you're done with it.

  • query(options, resultKey): This calls the ApolloClient.query method. It returns a promise that resolves with the raw POJO data that the query returns. If you provide a resultKey, the resolved data is grabbed from that key in the result.

  • mutate(options, resultKey): This calls the ApolloClient.mutate method. It returns a promise that resolves with the raw POJO data that the mutation returns. As with the query methods, the resultKey can be used to resolve beneath the root.

Unsubscribing from watch queries

Apollo Client's watchQuery will continue to update the query with new data whenever the store is updated with new data about the resolved objects. This happens until you explicitly unsubscribe from it.

In ember-apollo-client, most unsubscriptions are handled automatically by the RouteQueryManager, ObjectQueryManager and ComponentQueryManager mixins, so long as you use them.

If you're fetching data elsewhere, such as in an Ember Service, or if you use the Apollo service directly, you are responsible for unsubscribing from watchQuery results when you're done with them. This is exposed on the result of query via a method _apolloUnsubscribe.

Injecting the RouteQueryManager mixin into all routes

ember-apollo-client does not automatically inject any dependencies into your routes. If you want to inject this mixin into all routes, you should utilize a base route class:

app/routes/base.js

import Route from "@ember/routing/route";
import { RouteQueryManager } from "ember-apollo-client";

export default Route.extend(RouteQueryManager);

Then extend from that in your other routes:

app/routes/a-real-route.js

import Base from "my-app/routes/base";

export default Base.extend(
  ...
)

Use with Fastboot

Ember Apollo Client works with FastBoot out of the box as long that SSR is enabled. In order to enable SSR, define it on apollo service:

Example:

const OverriddenService = ApolloService.extend({
  clientOptions: computed(function() {
    return {
      ssrMode: true,
      link: this.get("link"),
      cache: this.get("cache")
    };
  })
});

Since you only want to fetch each query result once, pass the ssrMode: true option to the Apollo Client constructor to avoid repeated force-fetching.

Skipping queries for SSR

If you want to intentionally skip a query during SSR, you can pass ssr: false in the query options. Typically, this will mean the component will get rendered in its loading state on the server. For example:

actions: {
  refetchModel() {
    this.get('apollo').query({
      query,
      variables,
      // Don't run this query on the server
      ssr: false
    });
  }
}

Testing

This addon is test-ready! All promises from the apollo service are tracked with Ember.Test.registerWaiter, so your tests should be completely deterministic.

The dummy app contains example routes for mutations and queries:

The tests also contain a sample Star Wars GraphQL schema with an ember-cli-pretender setup for mock data.

Development

Installation

  • git clone https://github.com/bgentry/ember-apollo-client this repository
  • cd ember-apollo-client
  • yarn install

Linting

  • yarn run lint:js
  • yarn run lint:js -- --fix

Running tests

  • ember test – Runs the test suite on the current Ember version
  • ember test --server – Runs the test suite in "watch mode"
  • ember try:each – Runs the test suite against multiple Ember versions

Running the dummy application

For more information on using ember-cli, visit https://ember-cli.com/.

Contributors

A special thanks to the following contributors:

License

This project is licensed under the MIT License.