|
1 | | -# [React Apollo](http://dev.apollodata.com/react/) [](https://badge.fury.io/js/react-apollo) [](https://spectrum.chat/apollo) |
| 1 | +# <a href="https://www.apollographql.com/"><img src="https://user-images.githubusercontent.com/841294/53402609-b97a2180-39ba-11e9-8100-812bab86357c.png" height="100" alt="React Apollo"></a> |
2 | 2 |
|
3 | | -React Apollo allows you to fetch data from your GraphQL server and use it in building complex and reactive UIs using the React framework. React Apollo may be used in any context that React may be used. In the browser, in React Native, or in Node.js when you want to do server-side rendering. |
4 | | - |
5 | | -React Apollo unlike many other tools in the React ecosystem requires _no_ complex build setup to get up and running. As long as you have a GraphQL server you can get started building out your application with React immediately. React Apollo works out of the box with both [`create-react-app`][] and [React Native][] with a single install and with no extra hassle configuring Babel or other JavaScript tools. |
6 | | - |
7 | | -[`create-react-app`]: https://github.com/facebookincubator/create-react-app |
8 | | -[react native]: http://facebook.github.io/react-native |
9 | | - |
10 | | -React Apollo is: |
11 | | - |
12 | | -1. **Incrementally adoptable**, so that you can drop it into an existing JavaScript app and start using GraphQL for just part of your UI. |
13 | | -2. **Universally compatible**, so that Apollo works with any build setup, any GraphQL server, and any GraphQL schema. |
14 | | -3. **Simple to get started with**, you can start loading data right away and learn about advanced features later. |
15 | | -4. **Inspectable and understandable**, so that you can have great developer tools to understand exactly what is happening in your app. |
16 | | -5. **Built for interactive apps**, so your users can make changes and see them reflected in the UI immediately. |
17 | | -6. **Small and flexible**, so you don't get stuff you don't need. The core is under 25kb compressed. |
18 | | -7. **Community driven**, Apollo is driven by the community and serves a variety of use cases. Everything is planned and developed in the open. |
19 | | - |
20 | | -Get started today on the app you’ve been dreaming of, and let React Apollo take you to the moon! |
21 | | - |
22 | | -## Installation |
23 | | - |
24 | | -It is simple to install React Apollo and related libraries |
25 | | - |
26 | | -```bash |
27 | | -# installing the preset package (apollo-boost) and react integration |
28 | | -npm install apollo-boost react-apollo graphql-tag graphql --save |
29 | | - |
30 | | -# installing each piece independently |
31 | | -npm install apollo-client apollo-cache-inmemory apollo-link-http react-apollo graphql-tag graphql --save |
32 | | -``` |
33 | | - |
34 | | -[apollo-boost](https://github.com/apollographql/apollo-client/tree/master/packages/apollo-boost) is a minimal config way to start using Apollo Client. It includes some sensible defaults, such as `InMemoryCache` and `HttpLink`. |
35 | | - |
36 | | -That’s it! You may now use React Apollo in any of your React environments. |
37 | | - |
38 | | -For an amazing developer experience you may also install the [Apollo Client Developer tools for Chrome][] which will give you inspectability into your React Apollo data. |
39 | | - |
40 | | -[apollo client developer tools for chrome]: https://chrome.google.com/webstore/detail/apollo-client-developer-t/jdkknkkbebbapilgoeccciglkfbmbnfm |
41 | | - |
42 | | -## Usage |
43 | | - |
44 | | -> Looking for apollo 1.x docs? See [here](https://s3.amazonaws.com/apollo-docs-1.x/index.html). |
45 | | -
|
46 | | -To get started you will first want to create an instance of [`ApolloClient`][] and then you will want to provide that client to your React component tree using the [`<ApolloProvider/>`][] component. Finally, we will show you a basic example of connecting your GraphQL data to your React components with the [`<Query>`][] component. |
47 | | - |
48 | | -First we want an instance of [`ApolloClient`][]. We can import the class from `apollo-client`. |
49 | | -To get started, create an ApolloClient instance and point it at your GraphQL server: |
50 | | - |
51 | | -```js |
52 | | -import { ApolloClient } from 'apollo-client'; |
53 | | -import { HttpLink } from 'apollo-link-http'; |
54 | | -import { InMemoryCache } from 'apollo-cache-inmemory'; |
55 | | - |
56 | | -const client = new ApolloClient({ |
57 | | - // By default, this client will send queries to the |
58 | | - // `/graphql` endpoint on the same host |
59 | | - // Pass the configuration option { uri: YOUR_GRAPHQL_API_URL } to the `HttpLink` to connect |
60 | | - // to a different host |
61 | | - link: new HttpLink(), |
62 | | - cache: new InMemoryCache(), |
63 | | -}); |
64 | | -``` |
65 | | - |
66 | | -If you're using [apollo-boost](https://github.com/apollographql/apollo-client/tree/master/packages/apollo-boost), you can create an `ApolloClient` that uses `HttpLink` and `InMemoryCache` like so: |
67 | | - |
68 | | -```js |
69 | | -import ApolloClient from 'apollo-boost'; |
| 3 | +## React Apollo |
70 | 4 |
|
71 | | -const client = new ApolloClient(); |
72 | | -``` |
| 5 | +[](https://badge.fury.io/js/%40react-apollo) |
| 6 | +[](https://circleci.com/gh/apollographql/react-apollo) |
| 7 | +[](https://spectrum.chat/apollo) |
73 | 8 |
|
74 | | -> Migrating from 1.x? See the [2.0 migration guide](https://www.apollographql.com/docs/react/recipes/2.0-migration.html). |
75 | | -
|
76 | | -Next you will want to add a [`<ApolloProvider/>`][] component to the root of your React component tree. This component [provides](https://reactjs.org/docs/context.html) the React Apollo functionality to all the other components in the application without passing it explicitly. To use an [`<ApolloProvider/>`][] with your newly constructed client see the following: |
77 | | - |
78 | | -```js |
79 | | -import { ApolloProvider } from 'react-apollo'; |
80 | | - |
81 | | -ReactDOM.render( |
82 | | - <ApolloProvider client={client}> |
83 | | - <MyRootComponent /> |
84 | | - </ApolloProvider>, |
85 | | - document.getElementById('root'), |
86 | | -); |
87 | | -``` |
88 | | - |
89 | | -Now you may create components in this React tree that are connected to your GraphQL API. |
90 | | - |
91 | | -Finally, to demonstrate the power of React Apollo in building interactive UIs let us connect one of your components to your GraphQL server using the [`<Query>`][] component: |
92 | | - |
93 | | -You'll need install `graphql-tag` to use `gql` module: |
94 | | - |
95 | | -```bash |
96 | | -npm install graphql-tag --save |
97 | | -``` |
98 | | - |
99 | | -```js |
100 | | -import gql from 'graphql-tag'; |
101 | | -import { Query } from 'react-apollo'; |
102 | | - |
103 | | -const GET_DOGS = gql` |
104 | | - { |
105 | | - dogs { |
106 | | - id |
107 | | - breed |
108 | | - } |
109 | | - } |
110 | | -`; |
111 | | - |
112 | | -const Dogs = ({ onDogSelected }) => ( |
113 | | - <Query query={GET_DOGS}> |
114 | | - {({ loading, error, data }) => { |
115 | | - if (loading) return 'Loading...'; |
116 | | - if (error) return `Error! ${error.message}`; |
117 | | - |
118 | | - return ( |
119 | | - <select name="dog" onChange={onDogSelected}> |
120 | | - {data.dogs.map(dog => ( |
121 | | - <option key={dog.id} value={dog.breed}> |
122 | | - {dog.breed} |
123 | | - </option> |
124 | | - ))} |
125 | | - </select> |
126 | | - ); |
127 | | - }} |
128 | | - </Query> |
129 | | -); |
130 | | -``` |
131 | | - |
132 | | -If you render Dogs within your App component, you’ll first see a loading state and then a form with a list of dog breeds once Apollo Client receives the data from the server. |
133 | | - |
134 | | -To learn more about querying with React Apollo be sure to start reading the [documentation article on Queries][]. If you would like to see all of the features React Apollo supports be sure to check out the [complete API reference][]. |
135 | | - |
136 | | -[`apolloclient`]: https://www.apollographql.com/docs/react/api/apollo-client.html#apollo-client |
137 | | -[`<apolloprovider/>`]: https://www.apollographql.com/docs/react/api/react-apollo.html#ApolloProvider |
138 | | -[`<query>`]: https://www.apollographql.com/docs/react/essentials/queries.html |
139 | | -[documentation article on queries]: http://dev.apollodata.com/react/queries.html |
140 | | -[complete api reference]: https://www.apollographql.com/docs/react/api/react-apollo.html |
141 | | - |
142 | | -## Polyfills |
143 | | - |
144 | | -React Apollo makes use of `Object.assign`, which is not supported in certain browsers (most prominently, IE11). If you wish to support legacy browsers, you will need to import a polyfill. As an example, you could use `core-js`'s polyfill like so: |
145 | | - |
146 | | -```js |
147 | | -import 'core-js/fn/object/assign'; |
148 | | -``` |
149 | | - |
150 | | -## Building for production |
151 | | - |
152 | | -The `react-apollo` package is designed to be effectively consumed by bundlers that understand either CommonJS `require` syntax or ECMASCript `import` and `export` syntax, such as [Rollup](https://rollupjs.org), [Webpack](https://webpack.js.org), or [Parcel](https://parceljs.org). If your bundler supports tree-shaking, it should be able to eliminate unused code from the `react-apollo` package, regardless of which module syntax you're using. |
153 | | - |
154 | | -You should (almost) never need to reach into the `react-apollo/...` internals to import specific modules. The only supported exceptions are `react-apollo/test-links`, `react-apollo/test-utils`. |
155 | | - |
156 | | -When minifying your application, you can make the `react-apollo` package noticeably smaller by configuring your minifier to replace the expression `process.env.NODE_ENV` with a string literal (typically `"production"`). Other packages such as [React](https://reactjs.org) use the same convention, so there's a good chance you already have your minifier configured in this way. |
| 9 | +React Apollo allows you to fetch data from your GraphQL server and use it in building complex and reactive UIs using the React framework. React Apollo may be used in any context that React may be used. In the browser, in React Native, or in Node.js when you want to do server-side rendering. |
157 | 10 |
|
158 | 11 | ## Documentation |
159 | 12 |
|
160 | | -For a complete React Apollo API reference visit the documentation website at: [https://www.apollographql.com/docs/react/api/react-apollo.html](https://www.apollographql.com/docs/react/api/react-apollo.html) |
| 13 | +All Apollo Client documentation, including React Apollo usage articles and helpful recipes, lives on [https://www.apollographql.com/docs/react/](https://www.apollographql.com/docs/react/) |
161 | 14 |
|
162 | | -All of the documentation for React Apollo including usage articles and helpful recipes lives on: [https://www.apollographql.com/docs/react/](https://www.apollographql.com/docs/react/) |
| 15 | +For the React Apollo API reference, visit [https://www.apollographql.com/docs/react/api/react-apollo.html](https://www.apollographql.com/docs/react/api/react-apollo.html) |
163 | 16 |
|
164 | 17 | ## Maintainers |
165 | 18 |
|
|
0 commit comments