Merge React Apollo hooks into Apollo Client

docs/gatsby-config.js

@@ -59,14 +59,13 @@ module.exports = {
             'recipes/meteor',
             'recipes/recompose',
           ],
-          'API Reference': [
-            'api/apollo-client',
+          'Apollo Client API': [
+            'api/core',
             'api/react-hooks',
-            'api/react-ssr',
             'api/react-testing',
+            'api/react-ssr',
             'api/react-components',
-            'api/react-hoc',
-            'api/react-common',
+            'api/react-hoc'
           ],
         },
       },

docs/source/advanced/subscriptions.mdx

@@ -120,7 +120,7 @@ Now, queries and mutations will go over HTTP as normal, but subscriptions will b
 
 ## useSubscription Hook
 
-The easiest way to bring live data to your UI is by using React Apollo's `useSubscription` Hook. This lets you render the stream of data from your service directly within your render function of your component! One thing to note, subscriptions are just listeners, they don't request any data when first connected, but only open up a connection to get new data. Binding live data to your UI is as easy as this:
+The easiest way to bring live data to your UI is by using Apollo Client's `useSubscription` Hook. This lets you render the stream of data from your service directly within your render function of your component! One thing to note, subscriptions are just listeners, they don't request any data when first connected, but only open up a connection to get new data. Binding live data to your UI is as easy as this:
 
 <MultiCodeBlock>
 <div data-language="Hooks (JavaScript)">
@@ -199,7 +199,7 @@ With GraphQL subscriptions your client will be alerted on push from the server a
 
 With `subscribeToMore`, you can easily do the latter.
 
-`subscribeToMore` is a function available on every query result in React Apollo. It works just like [`fetchMore`](/advanced/caching/#incremental-loading-fetchmore), except that the update function gets called every time the subscription returns, instead of only once.
+`subscribeToMore` is a function available on every query result, made using Apollo Client's React integration. It works just like [`fetchMore`](/advanced/caching/#incremental-loading-fetchmore), except that the update function gets called every time the subscription returns, instead of only once.
 
 Here is a regular query:
 

docs/source/api/apollo-client.mdx → docs/source/api/core.mdx

@@ -1,5 +1,6 @@
 ---
-title: class ApolloClient
+title: Core
+description: Apollo Client core API reference
 order: 11
 ---
 

docs/source/api/react-components.mdx

@@ -1,6 +1,6 @@
 ---
-title: '@apollo/react-components'
-description: API reference
+title: 'React - Components (DEPRECATED)'
+description: Deprecated React Apollo render prop component API
 ---
 
 import QueryOptions from '../../shared/query-options.mdx';
@@ -9,7 +9,8 @@ import MutationOptions from '../../shared/mutation-options.mdx';
 import MutationResult from '../../shared/mutation-result.mdx';
 import SubscriptionOptions from '../../shared/subscription-options.mdx';
 import SubscriptionResult from '../../shared/subscription-result.mdx';
-import ApolloProvider from '../../shared/apollo-provider.mdx';
+
+> **NOTE:** React Apollo's render prop components have been deprecated. They will continue to receive bug fixes until March 2020, after which they will no longer be maintained by Apollo.
 
 ## Installation
 
@@ -56,7 +57,3 @@ The Subscription component accepts the following props. Only `subscription` is *
 The render prop function that you pass to the `children` prop of `Subscription` is called with an object that has the following properties.
 
 <SubscriptionResult />
-
-## `ApolloProvider`
-
-<ApolloProvider />

docs/source/api/react-hoc.mdx

@@ -1,10 +1,12 @@
 ---
-title: '@apollo/react-hoc'
-description: API reference
+title: 'React - HOC (DEPRECATED)'
+description: Deprecated React Apollo HOC API
 ---
 
 import ApolloProvider from '../../shared/apollo-provider.mdx';
 
+> **NOTE:** React Apollo's higher order components have been deprecated. They will continue to receive bug fixes until March 2020, after which they will no longer be maintained by Apollo.
+
 ## Installation
 
 ```
@@ -55,7 +57,7 @@ const TodoAppWithData = withTodoAppQuery(TodoApp);
 export default TodoAppWithData;
 ```
 
-The `graphql()` function will only be able to provide access to your GraphQL data if there is a [`<ApolloProvider/>`](/api/react-common/#apolloprovider) component higher up in your tree to provide an [`ApolloClient`](/api/apollo-client/) instance that will be used to fetch your data.
+The `graphql()` function will only be able to provide access to your GraphQL data if there is a [`<ApolloProvider/>`](/api/react-hooks/#apolloprovider) component higher up in your tree to provide an [`ApolloClient`](/api/core/) instance that will be used to fetch your data.
 
 The behavior of your component enhanced with the `graphql()` function will be different depending on if your GraphQL operation is a [query](/essentials/queries/), a [mutation](/essentials/mutations/), or a [subscription](/advanced/subscriptions/). Go to the appropriate API documentation for more information about the functionality and available options for each type.
 
@@ -1068,11 +1070,11 @@ export default graphql(
 import { withApollo } from '@apollo/react-hoc';
 ```
 
-A simple enhancer which provides direct access to your [`ApolloClient`](/api/apollo-client/) instance. This is useful if you want to do custom logic with Apollo. Such as calling one-off queries. By calling this function with the component you want to enhance, `withApollo()` will create a new component which passes in an instance of `ApolloClient` as a `client` prop.
+A simple enhancer which provides direct access to your [`ApolloClient`](/api/core/) instance. This is useful if you want to do custom logic with Apollo. Such as calling one-off queries. By calling this function with the component you want to enhance, `withApollo()` will create a new component which passes in an instance of `ApolloClient` as a `client` prop.
 
 If you are wondering when to use `withApollo()` and when to use [`graphql()`](#graphqlquery-configcomponent) the answer is that most of the time you will want to use `graphql()`. `graphql()` provides many of the advanced features you need to work with your GraphQL data. You should only use `withApollo()` if you want the GraphQL client without any of the other features.
 
-This will only be able to provide access to your client if there is an [`<ApolloProvider/>`](/api/react-common/#apolloprovider) component higher up in your tree to actually provide the client.
+This will only be able to provide access to your client if there is an [`<ApolloProvider/>`](/api/react-hooks/#apolloprovider) component higher up in your tree to actually provide the client.
 
 **Example:**
 
@@ -1083,7 +1085,3 @@ function MyComponent({ client }) {
 
 export default withApollo(MyComponent);
 ```
-
-### `ApolloProvider`
-
-<ApolloProvider />

docs/source/api/react-hooks.mdx

@@ -1,28 +1,47 @@
 ---
-title: '@apollo/react-hooks'
-description: API reference
+title: React - Hooks
+description: Apollo Client React API reference
 ---
 
+import ApolloProvider from '../../shared/apollo-provider.mdx';
 import QueryOptions from '../../shared/query-options.mdx';
 import QueryResult from '../../shared/query-result.mdx';
 import MutationOptions from '../../shared/mutation-options.mdx';
 import MutationResult from '../../shared/mutation-result.mdx';
 import SubscriptionOptions from '../../shared/subscription-options.mdx';
 import SubscriptionResult from '../../shared/subscription-result.mdx';
-import ApolloProvider from '../../shared/subscription-result.mdx';
 
 ## Installation
 
-```
-npm install @apollo/react-hooks
+Apollo Client >= 3 includes React hooks functionality out of the box. You don't need to install any additional packages.
+
+## `ApolloProvider`
+
+<ApolloProvider />
+
+## `ApolloConsumer`
+
+One way to access the configured Apollo Client instance directly is to create an `ApolloConsumer` component and provide a render prop function as its child. The render prop function will be called with your `ApolloClient` instance as its only argument. You can think of the `ApolloConsumer` component as similar to the `Consumer` component from the [React Context API](https://reactjs.org/docs/context.html).
+
+### Example
+
+```jsx
+import React from 'react';
+import { ApolloConsumer } from '@apollo/client';
+
+const WithApolloClient = () => (
+  <ApolloConsumer>
+    {client => 'We have access to the client!' /* do stuff here */}
+  </ApolloConsumer>
+);
 ```
 
 ## `useQuery`
 
 ### Example
 
 ```jsx
-import { useQuery } from '@apollo/react-hooks';
+import { useQuery } from '@apollo/client';
 import gql from 'graphql-tag';
 
 const GET_GREETING = gql`
@@ -74,7 +93,7 @@ function useQuery<TData = any, TVariables = OperationVariables>(
 ### Example
 
 ```jsx
-import { useLazyQuery } from "@apollo/react-hooks";
+import { useLazyQuery } from "@apollo/client";
 import gql from "graphql-tag";
 
 const GET_GREETING = gql`
@@ -141,7 +160,7 @@ function useLazyQuery<TData = any, TVariables = OperationVariables>(
 ### Example
 
 ```jsx
-import { useMutation } from '@apollo/react-hooks';
+import { useMutation } from '@apollo/client';
 import gql from 'graphql-tag';
 
 const ADD_TODO = gql`
@@ -265,6 +284,8 @@ function useSubscription<TData = any, TVariables = OperationVariables>(
 ### Example
 
 ```jsx
+import { useApolloClient } from '@apollo/client';
+
 function SomeComponent() {
   const client = useApolloClient();
   // `client` is now set to the `ApolloClient` instance being used by the
@@ -283,7 +304,3 @@ function useApolloClient(): ApolloClient<object> {}
 | Param                  | Type                       | Description                                                |
 | ---------------------- | -------------------------- | ---------------------------------------------------------- |
 | Apollo Client instance | ApolloClient&lt;object&gt; | The `ApolloClient` instance being used by the application. |
-
-### `ApolloProvider`
-
-<ApolloProvider />

docs/source/api/react-ssr.md

@@ -1,6 +1,6 @@
 ---
-title: "@apollo/react-ssr"
-description: API reference
+title: React - SSR
+description: Apollo Client React server side rendering API
 ---
 
 ## Installation

docs/source/api/react-testing.md

@@ -1,21 +1,19 @@
 ---
-title: "@apollo/react-testing"
-description: API reference
+title: React - Testing
+description: Apollo Client React testing API
 ---
 
 ## Installation
 
-```
-npm install @apollo/react-testing
-```
+Apollo Client >= 3 includes React testing utilities out of the box. You don't need to install any additional packages.
 
 ## `MockedProvider`
 
 ```js
-import { MockedProvider } from "@apollo/react-testing";
+import { MockedProvider } from "@apollo/client/lib/react/testing";
 ```
 
-The `MockedProvider` is a test-utility that allows you to create a mocked version of the [`ApolloProvider`](/api/react-common/#apolloprovider) that doesn't send out network requests to your API, but rather allows you to specify the exact response payload for a given request.
+The `MockedProvider` is a test-utility that allows you to create a mocked version of the [`ApolloProvider`](/api/react-hooks/#apolloprovider) that doesn't send out network requests to your API, but rather allows you to specify the exact response payload for a given request.
 
 The `<MockedProvider />` component takes the following props:
 

docs/source/essentials/get-started.mdx

@@ -168,4 +168,4 @@ Now that you've learned how to fetch data with Apollo Client, you're ready to di
 
 - [Queries](/essentials/queries/): Learn how to fetch queries with arguments and dive deeper into configuration options. For a full list of options, check out the API reference for `useQuery`.
 - [Mutations](/essentials/mutations/): Learn how to update data with mutations and when you'll need to update the Apollo cache. For a full list of options, check out the API reference for `useMutation` components.
-- [Apollo Client API](/api/apollo-client/): Sometimes, you'll need to access the client directly like we did in our plain JavaScript example above. Visit the API reference for a full list of options.
+- [Apollo Client API](/api/core/): Sometimes, you'll need to access the client directly like we did in our plain JavaScript example above. Visit the API reference for a full list of options.

docs/source/essentials/local-state.mdx

@@ -351,7 +351,7 @@ cache.writeData({
 });
 ```
 
-Sometimes you may need to [reset the store](/api/apollo-client/#ApolloClient.resetStore) in your application, when a user logs out for example. If you call `client.resetStore` anywhere in your application, you will likely want to initialize your cache again. You can do this using the `client.onResetStore` method to register a callback that will call `cache.writeData` again.
+Sometimes you may need to [reset the store](/api/core/#ApolloClient.resetStore) in your application, when a user logs out for example. If you call `client.resetStore` anywhere in your application, you will likely want to initialize your cache again. You can do this using the `client.onResetStore` method to register a callback that will call `cache.writeData` again.
 
 ```js
 import { ApolloClient, InMemoryCache } from '@apollo/client';
@@ -717,15 +717,15 @@ ReactDOM.render(
 </div>
 </MultiCodeBlock>
 
-In the above example, we first prep the cache using `cache.writeData` to store a value for the `isLoggedIn` field. We then run the `IS_LOGGED_IN` query via a React Apollo `useQuery` hook, which includes an `@client` directive. When Apollo Client executes the `IS_LOGGED_IN` query, it first looks for a local resolver that can be used to handle the `@client` field. When it can't find one, it falls back on trying to pull the specified field out of the cache. So in this case, the `data` value returned by the `useQuery` hook has a `isLoggedIn` property available, which includes the `isLoggedIn` result (`!!localStorage.getItem('token')`) pulled directly from the cache.
+In the above example, we first prep the cache using `cache.writeData` to store a value for the `isLoggedIn` field. We then run the `IS_LOGGED_IN` query via an Apollo Client `useQuery` hook, which includes an `@client` directive. When Apollo Client executes the `IS_LOGGED_IN` query, it first looks for a local resolver that can be used to handle the `@client` field. When it can't find one, it falls back on trying to pull the specified field out of the cache. So in this case, the `data` value returned by the `useQuery` hook has a `isLoggedIn` property available, which includes the `isLoggedIn` result (`!!localStorage.getItem('token')`) pulled directly from the cache.
 
 > ⚠️ If you want to use Apollo Client's `@client` support to query the cache without using local resolvers, you must pass an empty object into the `ApolloClient` constructor `resolvers` option. Without this Apollo Client will not enable its integrated `@client` support, which means your `@client` based queries will be passed to the Apollo Client link chain. You can find more details about why this is necessary [here](https://github.com/apollographql/apollo-client/pull/4499).
 
 Pulling `@client` field values directly out of the cache isn't quite as flexible as local resolver functions, since local resolvers can perform extra computations before returning a result. Depending on your application's needs however, loading `@client` fields directly from the cache might be a simpler option. Apollo Client doesn't restrict combining both approaches, so feel free to mix and match. If the need arises, you can pull some `@client` values from the cache, and resolve others with local resolvers, all in the same query.
 
 ### Working with fetch policies
 
-Before Apollo Client executes a query, one of the first things it does is check to see which [`fetchPolicy`](/api/apollo-client/#ApolloClient.query) it has been configured to use. It does this so it knows where it should attempt to resolve the query from first, either the cache or the network. When running a query, Apollo Client treats `@client` based local resolvers just like it does remote resolvers, in that it will adhere to its defined `fetchPolicy` to know where to attempt to pull data from first. When working with local resolvers, it's important to understand how fetch policies impact the running of resolver functions, since by default local resolver functions are not run on every request. This is because the result of running a local resolver is cached with the rest of the query result, and pulled from the cache on the next request. Let's look at an example:
+Before Apollo Client executes a query, one of the first things it does is check to see which [`fetchPolicy`](/api/core/#ApolloClient.query) it has been configured to use. It does this so it knows where it should attempt to resolve the query from first, either the cache or the network. When running a query, Apollo Client treats `@client` based local resolvers just like it does remote resolvers, in that it will adhere to its defined `fetchPolicy` to know where to attempt to pull data from first. When working with local resolvers, it's important to understand how fetch policies impact the running of resolver functions, since by default local resolver functions are not run on every request. This is because the result of running a local resolver is cached with the rest of the query result, and pulled from the cache on the next request. Let's look at an example:
 
 <MultiCodeBlock>
 <div data-language="Hooks (JavaScript)">
@@ -818,7 +818,7 @@ export default function Launch({ launchId }) {
 </div>
 </MultiCodeBlock>
 
-In the above example we're using a React Apollo `useQuery` hook to run the `GET_LAUNCH_DETAILS` query. The `@client` based `isInCart` field is configured to pull its data from the following resolver:
+In the above example we're using an Apollo Client `useQuery` hook to run the `GET_LAUNCH_DETAILS` query. The `@client` based `isInCart` field is configured to pull its data from the following resolver:
 
 ```js
 import { GET_CART_ITEMS } from './pages/cart';

docs/source/essentials/queries.mdx

@@ -48,7 +48,7 @@ const GET_DOGS = gql`
 
 ```tsx:title=index.js
 import gql from 'graphql-tag';
-import { Query } from 'react-apollo';
+import { Query } from '@apollo/react-components';
 
 const GET_DOGS = gql`
   {