1 | # [Apollo client](http://dev.apollodata.com/) [![npm version](https://badge.fury.io/js/apollo-client.svg)](https://badge.fury.io/js/apollo-client) [![Get on Slack](https://img.shields.io/badge/slack-join-orange.svg)](http://www.apollostack.com/#slack)
|
2 |
|
3 | Apollo Client is a fully-featured caching GraphQL client with integrations for React, Angular, etc. It allows you to easily build UI components that fetch data via GraphQL. To get the most value out of `apollo-client` you should use it with one of its view layer integrations.
|
4 |
|
5 | To get started with the React integration go to our [**React Apollo documentation website**](http://dev.apollodata.com/react/).
|
6 |
|
7 | Apollo Client also has view layer integrations for [all the popular frontend frameworks](#learn-how-to-use-apollo-client-with-your-favorite-framework). For the best experience make sure to use the view integration layer for your frontend framework of choice.
|
8 |
|
9 | Apollo Client can be used in any JavaScript frontend where you want to use data from a GraphQL server. It's:
|
10 |
|
11 | 1. **Incrementally adoptable**, so that you can drop it into an existing JavaScript app and start using GraphQL for just part of your UI.
|
12 | 2. **Universally compatible**, so that Apollo works with any build setup, any GraphQL server, and any GraphQL schema.
|
13 | 2. **Simple to get started with**, you can start loading data right away and learn about advanced features later.
|
14 | 3. **Inspectable and understandable**, so that you can have great developer tools to understand exactly what is happening in your app.
|
15 | 4. **Built for interactive apps**, so your users can make changes and see them reflected in the UI immediately.
|
16 | 4. **Small and flexible**, so you don't get stuff you don't need. The core is under 25kb compressed.
|
17 | 5. **Community driven**, Apollo is driven by the community and serves a variety of use cases. Everything is planned and developed in the open.
|
18 |
|
19 | Get started on the [home page](http://dev.apollodata.com/), which has great examples for a variety of frameworks.
|
20 |
|
21 | ## Installation
|
22 |
|
23 | ```bash
|
24 | npm install apollo-client graphql-tag --save
|
25 | ```
|
26 |
|
27 | To use this client in a web browser or mobile app, you'll need a build system capable of loading NPM packages on the client. Some common choices include Browserify, Webpack, and Meteor 1.3.
|
28 |
|
29 | **NEW:** Install the [Apollo Client Developer tools for Chrome](https://chrome.google.com/webstore/detail/apollo-client-developer-t/jdkknkkbebbapilgoeccciglkfbmbnfm) for a great GraphQL developer experience!
|
30 |
|
31 | ## Usage
|
32 |
|
33 | If you know you want to use the core `apollo-client` package you can get started by constructing an instance of the core class [`ApolloClient`][] with a network interface created by network interface you may call the [`createNetworkInterface`][] function like so:
|
34 |
|
35 | ```js
|
36 | import ApolloClient, { createNetworkInterface } from 'apollo-client';
|
37 | import gql from 'graphql-tag';
|
38 |
|
39 | const client = new ApolloClient({
|
40 | networkInterface: createNetworkInterface({
|
41 | uri: 'https://graphql.example.com',
|
42 | }),
|
43 | });
|
44 | ```
|
45 |
|
46 | Replace `https://graphql.example.com` with your GraphQL APIs URL and you’re off to the moon!
|
47 |
|
48 | To execute a query with your client you may now call the `client.query` method like this:
|
49 |
|
50 | ```js
|
51 | client.query({
|
52 | query: gql`
|
53 | query TodoApp {
|
54 | todos {
|
55 | id
|
56 | text
|
57 | completed
|
58 | }
|
59 | }
|
60 | `,
|
61 | })
|
62 | .then(data => console.log(data))
|
63 | .catch(error => console.error(error));
|
64 | ```
|
65 |
|
66 | Now your client will be primed with some data in its cache. You can continue to make queries, or you can get your `client` instance to perform all sorts of advanced tasks on your GraphQL data. Such as [reactively watching queries with `watchQuery`][], [changing data on your server with `mutate`][], or [reading a fragment from your local cache with `readFragment`][].
|
67 |
|
68 | To learn more about all of the features available to you through the `apollo-client` package be sure to read through the [**`apollo-client` API reference**][].
|
69 |
|
70 | [`ApolloClient`]: http://dev.apollodata.com/core/apollo-client-api.html
|
71 | [`createNetworkInterface`]: http://dev.apollodata.com/core/network.html
|
72 | [reactively watching queries with `watchQuery`]: http://dev.apollodata.com/core/apollo-client-api.html#ApolloClient\.watchQuery
|
73 | [changing data on your server with `mutate`]: http://dev.apollodata.com/core/apollo-client-api.html#ApolloClient\.mutate
|
74 | [reading a fragment from your local cache with `readFragment`]: http://dev.apollodata.com/core/apollo-client-api.html#ApolloClient\.readFragment
|
75 | [**`apollo-client` API reference**]: http://dev.apollodata.com/core/apollo-client-api.html
|
76 |
|
77 | ## Learn how to use Apollo Client with your favorite framework
|
78 |
|
79 | - [React](http://dev.apollodata.com/react/)
|
80 | - [Angular 2](http://dev.apollodata.com/angular2/)
|
81 | - [Vue](https://github.com/Akryum/vue-apollo)
|
82 | - [Ember](https://github.com/bgentry/ember-apollo-client)
|
83 | - [Polymer](https://github.com/aruntk/polymer-apollo)
|
84 | - [Meteor](http://dev.apollodata.com/core/meteor.html)
|
85 | - [Blaze](http://github.com/Swydo/blaze-apollo)
|
86 | - [Vanilla JS](http://dev.apollodata.com/core/)
|
87 | - [Next.js](https://github.com/zeit/next.js/tree/master/examples/with-apollo)
|
88 |
|
89 | ---
|
90 |
|
91 | ## Contributing
|
92 |
|
93 | [![Build status](https://travis-ci.org/apollographql/apollo-client.svg?branch=master)](https://travis-ci.org/apollographql/apollo-client)
|
94 | [![Build status](https://ci.appveyor.com/api/projects/status/ajdf70delshw2ire/branch/master?svg=true)](https://ci.appveyor.com/project/stubailo/apollo-client/branch/master)
|
95 | [![Coverage Status](https://coveralls.io/repos/github/apollographql/apollo-client/badge.svg?branch=master)](https://coveralls.io/github/apollographql/apollo-client?branch=master)
|
96 |
|
97 | [Read the Apollo Contributor Guidelines.](CONTRIBUTING.md)
|
98 |
|
99 | Running tests locally:
|
100 |
|
101 | ```
|
102 | # nvm use node
|
103 | npm install
|
104 | npm test
|
105 | ```
|
106 |
|
107 | This project uses TypeScript for static typing and TSLint for linting. You can get both of these built into your editor with no configuration by opening this project in [Visual Studio Code](https://code.visualstudio.com/), an open source IDE which is available for free on all platforms.
|
108 |
|
109 | #### Important discussions
|
110 |
|
111 | If you're getting booted up as a contributor, here are some discussions you should take a look at:
|
112 |
|
113 | 1. [Static typing and why we went with TypeScript](https://github.com/apollostack/apollo-client/issues/6) also covered in [the Medium post](https://medium.com/apollo-stack/javascript-code-quality-with-free-tools-9a6d80e29f2d#.k32z401au)
|
114 | 1. [Idea for pagination handling](https://github.com/apollostack/apollo-client/issues/26)
|
115 | 1. [Discussion about interaction with Redux and domain vs. client state](https://github.com/apollostack/apollo-client/issues/98)
|
116 | 1. [Long conversation about different client options, before this repo existed](https://github.com/apollostack/apollo/issues/1)
|