Local state management

We've learned how to manage remote data from our GraphQL server with Apollo Client, but what should we do with our local data? We want to be able to access boolean flags and device API results from multiple components in our app, but don't want to maintain a separate Redux or MobX store. Ideally, we would like the Apollo cache to be the single source of truth for all data in our client application.

Apollo Client (>= 2.5) has built-in local state handling capabilities that allow you to store your local data inside the Apollo cache alongside your remote data. To access your local data, just query it with GraphQL. You can even request local and server data within the same query!

In this section, you'll learn how Apollo Client can help simplify local state management in your app. We'll cover how client-side resolvers can help us execute local queries and mutations. You'll also learn how to query and update the cache with the @client directive.

Please note that this documentation is intended to be used to familiarize yourself with Apollo Client's local state management capabilities, and serve as a reference guide. If you're looking for a step by step tutorial outlining how to handle local state with Apollo Client (and leverage other Apollo components to build a fullstack application), please refer to the full-stack quickstart course.

Updating local state

There are two main ways to perform local state mutations. The first way is to directly write to the cache by calling cache.writeData. Direct writes are great for one-off mutations that don't depend on the data that's currently in the cache, such as writing a single value. The second way is by leveraging the useMutation hook with a GraphQL mutation that calls a local client-side resolver. We recommend using resolvers if your mutation depends on existing values in the cache, such as adding an item to a list or toggling a boolean.

Direct writes

Direct writes to the cache do not require a GraphQL mutation or a resolver function. They leverage your Apollo Client instance directly by accessing the client property returned from the useApolloClient hook, made available in the useQuery hook result, or within the render prop function of the ApolloConsumer component. We recommend using this strategy for simple writes, such as writing a string, or one-off writes. It's important to note that direct writes are not implemented as GraphQL mutations under the hood, so you shouldn't include them in your schema. They also do not validate that the data you're writing to the cache is in the shape of valid GraphQL data. If either of these features are important to you, you should opt to use a local resolver instead.

1
import React from "react";
2
import { ApolloConsumer } from "@apollo/react-components";
3

4
import Link from "./Link";
5

6
const FilterLink = ({ filter, children }) => (
7
  <ApolloConsumer>
8
    {client => (
9
      <Link
10
        onClick={() => client.writeData({ data: { visibilityFilter: filter } })}
11
      >
12
        {children}
13
      </Link>
14
    )}
15
  </ApolloConsumer>
16
);

The ApolloConsumer render prop function is called with a single value, the Apollo Client instance. You can think of the ApolloConsumer component as being similar to the Consumer component from the React context API. From the client instance, you can directly call client.writeData and pass in the data you'd like to write to the cache.

What if we want to immediately subscribe to the data we just wrote to the cache? Let's create an active property on the link that marks the link's filter as active if it's the same as the current visibilityFilter in the cache. To immediately subscribe to a client-side mutation, we can use useQuery. The useQuery hook also makes the client instance available in its result object.

1
import React from "react";
2
import { Query } from "@apollo/react-components";
3
import gql from "graphql-tag";
4

5
import Link from "./Link";
6

7
const GET_VISIBILITY_FILTER = gql`
8
  {
9
    visibilityFilter @client
10
  }
11
`;
12

13
const FilterLink = ({ filter, children }) => (
14
  <Query query={GET_VISIBILITY_FILTER}>
15
    {({ data, client }) => (
16
      <Link
17
        onClick={() => client.writeData({ data: { visibilityFilter: filter } })}
18
        active={data.visibilityFilter === filter}
19
      >
20
        {children}
21
      </Link>
22
    )}
23
  </Query>
24
);

You'll notice in our query that we have a @client directive next to our visibilityFilter field. This tells Apollo Client to fetch the field data locally (either from the cache or using a local resolver), instead of sending it to our GraphQL server. Once you call client.writeData, the query result on the render prop function will automatically update. All cache writes and reads are synchronous, so you don't have to worry about loading state.

Local resolvers

If you'd like to implement your local state update as a GraphQL mutation, then you'll need to specify a function in your local resolver map. The resolver map is an object with resolver functions for each GraphQL object type. To visualize how this all lines up, it's useful to think of a GraphQL query or mutation as a tree of function calls for each field. These function calls resolve to data or another function call. So when a GraphQL query is run through Apollo Client, it looks for a way to essentially run functions for each field in the query. When it finds an @client directive on a field, it turns to its internal resolver map looking for a function it can run for that field.

To help make local resolvers more flexible, the signature of a resolver function is the exact same as resolver functions on the server built with Apollo Server. Let's recap the four parameters of a resolver function:

1
fieldName: (obj, args, context, info) => result;

1. obj: The object containing the result returned from the resolver on the parent field or the ROOT_QUERY object in the case of a top-level query or mutation.
2. args: An object containing all of the arguments passed into the field. For example, if you called a mutation with updateNetworkStatus(isConnected: true), the args object would be { isConnected: true }.
3. context: An object of contextual information shared between your React components and your Apollo Client network stack. In addition to any custom context properties that may be present, local resolvers always receive the following:
   • context.client: The Apollo Client instance.
   • context.cache: The Apollo Cache instance, which can be used to manipulate the cache with context.cache.readQuery, .writeQuery, .readFragment, .writeFragment, and .writeData. You can learn more about these methods in Managing the cache.
   • context.getCacheKey: Get a key from the cache using a __typename and id.
4. info: Information about the execution state of the query. You will probably never have to use this one.

Let's take a look at an example of a resolver where we toggle a todo's completed status:

1
import { ApolloClient } from 'apollo-client';
2
import { InMemoryCache } from 'apollo-cache-inmemory';
3

4
const client = new ApolloClient({
5
  cache: new InMemoryCache(),
6
  resolvers: {
7
    Mutation: {
8
      toggleTodo: (_root, variables, { cache, getCacheKey }) => {
9
        const id = getCacheKey({ __typename: 'TodoItem', id: variables.id })
10
        const fragment = gql`
11
          fragment completeTodo on TodoItem {
12
            completed
13
          }
14
        `;
15
        const todo = cache.readFragment({ fragment, id });
16
        const data = { ...todo, completed: !todo.completed };
17
        cache.writeData({ id, data });
18
        return null;
19
      },
20
    },
21
  },
22
});

In order to toggle the todo's completed status, we first need to query the cache to find out what the todo's current completed status is. We do this by reading a fragment from the cache with cache.readFragment. This function takes a fragment and an id, which corresponds to the todo item's cache key. We get the cache key by calling the getCacheKey that's on the context and passing in the item's __typename and id.

Once we read the fragment, we toggle the todo's completed status and write the updated data back to the cache. Since we don't plan on using the mutation's return result in our UI, we return null since all GraphQL types are nullable by default.

Let's learn how to trigger our toggleTodo mutation from our component:

1
import React from "react";
2
import { Mutation } from "@apollo/react-components";
3
import gql from "graphql-tag";
4

5
const TOGGLE_TODO = gql`
6
  mutation ToggleTodo($id: Int!) {
7
    toggleTodo(id: $id) @client
8
  }
9
`;
10

11
const Todo = ({ id, completed, text }) => (
12
  <Mutation mutation={TOGGLE_TODO} variables={{ id }}>
13
    {toggleTodo => (
14
      <li
15
        onClick={toggleTodo}
16
        style={{
17
          textDecoration: completed ? "line-through" : "none",
18
        }}
19
      >
20
        {text}
21
      </li>
22
    )}
23
  </Mutation>
24
);

First, we create a GraphQL mutation that takes the todo's id we want to toggle as its only argument. We indicate that this is a local mutation by marking the field with a @client directive. This will tell Apollo Client to call our local toggleTodo mutation resolver in order to resolve the field. Then, we create a component with useMutation just as we would for a remote mutation. Finally, pass in your GraphQL mutation to your component and trigger it from within the UI in your render prop function.

Querying local state

Querying for local data is very similar to querying your GraphQL server. The only difference is that you add a @client directive on your local fields to indicate they should be resolved from the Apollo Client cache or a local resolver function. Let's look at an example:

1
import React from "react";
2
import { Query } from "@apollo/react-components";
3
import gql from "graphql-tag";
4

5
import Todo from "./Todo";
6

7
const GET_TODOS = gql`
8
  {
9
    todos @client {
10
      id
11
      completed
12
      text
13
    }
14
    visibilityFilter @client
15
  }
16
`;
17

18
const TodoList = () => (
19
  <Query query={GET_TODOS}>
20
    {({ data: { todos, visibilityFilter } }) => (
21
      <ul>
22
        {getVisibleTodos(todos, visibilityFilter).map(todo => (
23
          <Todo key={todo.id} {...todo} />
24
        ))}
25
      </ul>
26
    )}
27
  </Query>
28
);

Here we create our GraphQL query and add @client directives to todos and visibilityFilter. We then pass the query to the useQuery hook. The @client directives here let useQuery component know that todos and visibilityFilter should be pulled from the Apollo Client cache or resolved using pre-defined local resolvers. The following sections help explain how both options work in more detail.

Initializing the cache

Often, you'll need to write an initial state to the cache so any components querying data before a mutation is triggered don't error out. To accomplish this, you can use cache.writeData to prep the cache with initial values. The shape of your initial state should match how you plan to query it in your application.

1
import { ApolloClient } from 'apollo-client';
2
import { InMemoryCache } from 'apollo-cache-inmemory';
3

4
const cache = new InMemoryCache();
5
const client = new ApolloClient({
6
  cache,
7
  resolvers: { /* ... */ },
8
});
9

10
cache.writeData({
11
  data: {
12
    todos: [],
13
    visibilityFilter: 'SHOW_ALL',
14
    networkStatus: {
15
      __typename: 'NetworkStatus',
16
      isConnected: false,
17
    },
18
  },
19
});

Sometimes you may need to reset the store 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.

1
import { ApolloClient } from 'apollo-client';
2
import { InMemoryCache } from 'apollo-cache-inmemory';
3

4
const cache = new InMemoryCache();
5
const client = new ApolloClient({
6
  cache,
7
  resolvers: { /* ... */ },
8
});
9

10
const data = {
11
  todos: [],
12
  visibilityFilter: 'SHOW_ALL',
13
  networkStatus: {
14
    __typename: 'NetworkStatus',
15
    isConnected: false,
16
  },
17
};
18

19
cache.writeData({ data });
20

21
client.onResetStore(() => cache.writeData({ data }));

Local data query flow

When a query containing @client directives is executed, Apollo Client runs through a few sequential steps to try to find a result for the @client field. Let's use the following query to walk through the local data look up flow:

1
const GET_LAUNCH_DETAILS = gql`
2
  query LaunchDetails($launchId: ID!) {
3
    launch(id: $launchId) {
4
      isInCart @client
5
      site
6
      rocket {
7
        type
8
      }
9
    }
10
  }
11
`;

This query includes a mixture of both remote and local fields. isInCart is the only field marked with an @client directive, so it's the field we'll focus on. When Apollo Client executes this query and tries to find a result for the isInCart field, it runs through the following steps:

1. Has a resolver function been set (either through the ApolloClient constructor resolvers parameter or Apollo Client's setResolvers / addResolvers methods) that is associated with the field name isInCart? If yes, run and return the result from the resolver function.
2. If a matching resolver function can't be found, check the Apollo Client cache to see if a isInCart value can be found directly. If so, return that value.

Let's look at both of these steps more closely.

• Resolving @client data with the help of local resolvers (step 1 above) is explained in Handling @client fields with resolvers.
• Loading @client data from the cache (step 2 above) is explained in Handling @client fields with the cache.

Handling @client fields with resolvers

Local resolvers are very similar to remote resolvers. Instead of sending your GraphQL query to a remote GraphQL endpoint, which then runs resolver functions against your query to populate and return a result set, Apollo Client runs locally defined resolver functions against any fields marked with the @client directive. Let's look at an example:

1
import { ApolloClient } from 'apollo-client';
2
import { InMemoryCache } from 'apollo-cache-inmemory';
3
import { HttpLink } from 'apollo-link-http';
4
import gql from 'graphql-tag';
5

6
const GET_CART_ITEMS = gql`
7
  query GetCartItems {
8
    cartItems @client
9
  }
10
`;
11

12
const cache = new InMemoryCache();
13
cache.writeData({
14
  data: {
15
    cartItems: [],
16
  },
17
});
18

19
const client = new ApolloClient({
20
  cache,
21
  link: new HttpLink({
22
    uri: 'http://localhost:4000/graphql',
23
  }),
24
  resolvers: {
25
    Launch: {
26
      isInCart: (launch, _args, { cache }) => {
27
        const { cartItems } = cache.readQuery({ query: GET_CART_ITEMS });
28
        return cartItems.includes(launch.id);
29
      },
30
    },
31
  },
32
});
33

34
const GET_LAUNCH_DETAILS = gql`
35
  query LaunchDetails($launchId: ID!) {
36
    launch(id: $launchId) {
37
      isInCart @client
38
      site
39
      rocket {
40
        type
41
      }
42
    }
43
  }
44
`;
45

46
// ... run the query using client.query, a <Query /> component, etc.

Here when the GET_LAUNCH_DETAILS query is executed, Apollo Client looks for a local resolver associated with the isInCart field. Since we've defined a local resolver for the isInCart field in the ApolloClient constructor, it finds a resolver it can use. This resolver function is run, then the result is calculated and merged in with the rest of the query result (if a local resolver can't be found, Apollo Client will check the cache for a matching field - see Local data query flow for more details).

Setting resolvers through ApolloClient's constructor resolvers parameter, or through its setResolvers / addResolvers methods, adds resolvers to Apollo Client's internal resolver map (refer to the Local resolvers section for more details concerning the resolver map). In the above example we added a isInCart resolver, for the Launch GraphQL object type, to the resolver map. Let's look at the isInCart resolver function more closely:

1
resolvers: {
2
    Launch: {
3
      isInCart: (launch, _args, { cache }) => {
4
        const { cartItems } = cache.readQuery({ query: GET_CART_ITEMS });
5
        return cartItems.includes(launch.id);
6
      },
7
    },
8
  },

launch holds the data returned from the server for the rest of the query, which means in this case we can use launch to get the current launch id. We aren't using any arguments in this resolver, so we can skip the second resolver parameter. From the context however (the third parameter), we're using the cache reference, to work directly with the cache ourselves. So in this resolver, we're making a call directly to the cache to get all cart items, checking to see if any of those loaded cart items matches the parent launch.id, and returning true / false accordingly. The returned boolean is then incorporated back into the result of running the original query.

Just like resolvers on the server, local resolvers are extremely flexible. They can be used to perform any kind of local computation you want, before returning a result for the specified field. You can manually query (or write to) the cache in different ways, call other helper utilities or libraries to prep/validate/clean data, track statistics, call into other data stores to prep a result, etc.

Integrating @client into remote queries

While Apollo Client’s local state handling features can be used to work with local state exclusively, most Apollo based applications are built to work with remote data sources. To address this, Apollo Client supports mixing @client based local resolvers with remote queries, as well as using @client based fields as arguments to remote queries, in the same request.

The @client directive can be used on any GraphQL selection set or field, to identify that the result of that field should be loaded locally with the help of a local resolver:

1
import { ApolloClient } from 'apollo-client';
2
import { InMemoryCache } from 'apollo-cache-inmemory';
3
import { HttpLink } from 'apollo-link-http';
4
import gql from 'graphql-tag';
5

6
const MEMBER_DETAILS = gql`
7
  query Member {
8
    member {
9
      name
10
      role
11
      isLoggedIn @client
12
    }
13
  }
14
`;
15

16
const client = new ApolloClient({
17
  link: new HttpLink({ uri: 'http://localhost:4000/graphql' }),
18
  cache: new InMemoryCache(),
19
  resolvers: {
20
    Member: {
21
      isLoggedIn() {
22
        return someInternalLoginVerificationFunction();
23
      }
24
    }
25
  },
26
});
27

28
// ... run the query using client.query, the <Query /> component, etc.

When the above MEMBER_DETAILS query is fired by Apollo Client (assuming we're talking to a network based GraphQL API), the @client isLoggedIn field is first stripped from the document, and the remaining query is sent over the network to the GraphQL API. After the query has been handled by the remote resolvers and the result is passed back to Apollo Client from the API, the @client parts of the original query are then run against any defined local resolvers, their results are merged with the network results, and the final resulting data is returned as the response to the original operation. So in the above example, isLoggedIn is stripped before the rest of the query is sent and handled by the network API, then when the results come back isLoggedIn is calculated by running the isLoggedIn() function from the resolver map. Local and network results are merged together, and the final response is made available to the application.

The @client directive can be used with entire selection sets as well:

1
import { ApolloClient } from 'apollo-client';
2
import { InMemoryCache } from 'apollo-cache-inmemory';
3
import { HttpLink } from 'apollo-link-http';
4
import gql from 'graphql-tag';
5

6
const MEMBER_DETAILS = gql`
7
  query Member {
8
    member {
9
      name
10
      role
11
      session @client {
12
        isLoggedIn
13
        connectionCount
14
        errors
15
      }
16
    }
17
  }
18
`;
19

20
const client = new ApolloClient({
21
  link: new HttpLink({ uri: 'http://localhost:4000/graphql' }),
22
  cache: new InMemoryCache(),
23
  resolvers: {
24
    Member: {
25
      session() {
26
        return {
27
          __typename: 'Session',
28
          isLoggedIn: someInternalLoginVerificationFunction(),
29
          connectionCount: calculateOpenConnections(),
30
          errors: sessionError(),
31
        };
32
      }
33
    }
34
  },
35
});

Apollo Client supports the merging of local @client results and remote results for Queries, Mutations and Subscriptions.

Async local resolvers

Apollo Client supports asynchronous local resolver functions. These functions can either be async functions or ordinary functions that return a Promise. Asynchronous resolvers are useful when they need to return data from an asynchronous API.

For React Native and most browser APIs, you should set up a listener in a component lifecycle method and pass in your mutation trigger function as the callback instead of using an async resolver. However, an async resolver function is often the most convenient way to consume asynchronous device APIs:

1
import { ApolloClient } from 'apollo-client';
2
import { InMemoryCache } from 'apollo-cache-inmemory';
3
import { CameraRoll } from 'react-native';
4

5
const client = new ApolloClient({
6
  cache: new InMemoryCache(),
7
  resolvers: {
8
    Query: {
9
      async cameraRoll(_, { assetType }) {
10
        try {
11
          const media = await CameraRoll.getPhotos({
12
            first: 20,
13
            assetType,
14
          });
15

16
          return {
17
            ...media,
18
            id: assetType,
19
            __typename: 'CameraRoll',
20
          };
21
        } catch (e) {
22
          console.error(e);
23
          return null;
24
        }
25
      },
26
    },
27
  },
28
});

CameraRoll.getPhotos() returns a Promise resolving to an object with a edges property, which is an array of camera node objects, and a page_info property, which is an object with pagination information. This is a great use case for GraphQL, since we can filter down the return value to only the data that our components consume.

1
import gql from 'graphql-tag';
2

3
const GET_PHOTOS = gql`
4
  query getPhotos($assetType: String!) {
5
    cameraRoll(assetType: $assetType) @client {
6
      id
7
      edges {
8
        node {
9
          image {
10
            uri
11
          }
12
          location {
13
            latitude
14
            longitude
15
          }
16
        }
17
      }
18
    }
19
  }
20
`;

Handling @client fields with the cache

As outlined in Handling @client fields with resolvers, @client fields can be resolved with the help of local resolver functions. However, it's important to note that local resolvers are not always required when using an @client directive. Fields marked with @client can still be resolved locally, by pulling matching values out of the cache directly. For example:

1
import React from "react";
2
import ReactDOM from "react-dom";
3
import { ApolloClient } from "apollo-client";
4
import { InMemoryCache } from "apollo-cache-inmemory";
5
import { HttpLink } from "apollo-link-http";
6
import { ApolloProvider, Query } from "@apollo/react-components";
7
import gql from "graphql-tag";
8

9
import Pages from "./pages";
10
import Login from "./pages/login";
11

12
const cache = new InMemoryCache();
13
const client = new ApolloClient({
14
  cache,
15
  link: new HttpLink({ uri: "http://localhost:4000/graphql" }),
16
  resolvers: {},
17
});
18

19
cache.writeData({
20
  data: {
21
    isLoggedIn: !!localStorage.getItem("token"),
22
  },
23
});
24

25
const IS_LOGGED_IN = gql`
26
  query IsUserLoggedIn {
27
    isLoggedIn @client
28
  }
29
`;
30

31
ReactDOM.render(
32
  <ApolloProvider client={client}>
33
    <Query query={IS_LOGGED_IN}>
34
      {({data}) => (data.isLoggedIn ? <Pages /> : <Login />)}
35
    </Query>
36
  </ApolloProvider>,
37
  document.getElementById("root"),
38
);

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.

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 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:

1
import React, { Fragment } from "react";
2
import { Query } from "@apollo/react-components";
3
import gql from "graphql-tag";
4

5
import { Loading, Header, LaunchDetail } from "../components";
6
import { ActionButton } from "../containers";
7

8
export const GET_LAUNCH_DETAILS = gql`
9
  query LaunchDetails($launchId: ID!) {
10
    launch(id: $launchId) {
11
      isInCart @client
12
      site
13
      rocket {
14
        type
15
      }
16
    }
17
  }
18
`;
19

20
export default function Launch({ launchId }) {
21
  return (
22
    <Query query={GET_LAUNCH_DETAILS} variables={{ launchId }}>
23
      {({ data, loading, error }) => {
24
        if (loading) return <Loading />;
25
        if (error) return <p>ERROR: {error.message}</p>;
26

27
        return (
28
          <Fragment>
29
            <Header image={data.launch.mission.missionPatch}>
30
              {data.launch.mission.name}
31
            </Header>
32
            <LaunchDetail {...data.launch} />
33
            <ActionButton {...data.launch} />
34
          </Fragment>
35
        );
36
      }}
37
    </Query>
38
  );
39
}

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:

1
import { GET_CART_ITEMS } from './pages/cart';
2

3
export const resolvers = {
4
  Launch: {
5
    isInCart: (launch, _, { cache }) => {
6
      const { cartItems } = cache.readQuery({ query: GET_CART_ITEMS });
7
      return cartItems.includes(launch.id);
8
    },
9
  },
10
};

Let's assume we're starting with an empty cache. Since we haven't specified a fetchPolicy prop in our useQuery call, we're using Apollo Client's default cache-first fetchPolicy. This means when the GET_LAUNCH_DETAILS query is run, it checks the cache first to see if it can find a result. It's important to note that when the cache is checked the entire query is run against the cache, but any @client associated local resolvers are skipped (not run). So the cache is queried with the following (it's as if the @client directive was never specified):

1
launch(id: $launchId) {
2
  isInCart
3
  site
4
  rocket {
5
    type
6
  }
7
}

In this case a result can't be extracted from the cache (since our cache is empty), so behind the scenes Apollo Client moves further down the query execution path. At its next step, it essentially splits the original query into two parts - the part that has @client fields and the part that will be fired over the network. Both parts are then executed - results are fetched from the network, and results are calculated by running local resolvers. The results from the local resolvers and from the network are then merged together, and the final result is written to the cache and returned. So after our first run, we now have a result in the cache for the original query, that includes data for both the @client parts and network parts of the query.

When the GET_LAUNCH_DETAILS query is run a second time, again since we're using Apollo Client's default fetchPolicy of cache-first, the cache is checked first for a result. This time a full result can be found for the query, so that result is returned through our useQuery call. Our @client field local resolvers aren't fired since the result we're looking for can already be extracted from the cache.

In a lot of situations treating local resolvers just like remote resolvers, by having them adhere to the same fetchPolicy, makes a lot of sense. Once you have the data you're looking for, which might have been fetched remotely or calculated using a local resolver, you can cache it and avoid recalculating/re-fetching it again on a subsequent request. But what if you're using local resolvers to run calculations that you need fired on every request? There are a few different ways this can be handled. You can switch your query to use a fetchPolicy that forces your entire query to run on each request, like no-cache or network-only. This will make sure your local resolvers fire on every request, but it will also make sure your network based query components fire on every request. Depending on your use case this might be okay, but what if you want the network parts of your query to leverage the cache, and just want your @client parts to run on every request? We'll cover a more flexible option for this in the Forcing resolvers with @client(always: true) section.

Forcing resolvers with @client(always: true)

Apollo Client leverages its cache to help reduce the network overhead required when constantly making requests for the same data. By default, @client based fields leverage the cache in the exact same manner as remote fields. After a local resolver is run, its result is cached alongside any remote results. This way the next time a query is fired that can find its results in the cache, those results are used, and any associated local resolvers are not fired again (until the data is either removed from the cache or the query is updated to use a no-cache or network-only fetchPolicy).

While leveraging the cache for both local and remote results can be super helpful in a lot of cases, it's not always the best fit. We might want to use a local resolver to calculate a dynamic value that needs to be refreshed on every request, while at the same time continue to use the cache for the network based parts of our query. To support this use case, Apollo Client's @client directive accepts an always argument, that when set to true will ensure that the associated local resolver is run on every request. Looking at an example:

1
import { ApolloClient } from 'apollo-client';
2
import { InMemoryCache } from 'apollo-cache-inmemory';
3
import gql from 'graphql-tag';
4

5
const client = new ApolloClient({
6
  cache: new InMemoryCache(),
7
  resolvers: {
8
    Query: {
9
      isLoggedIn() {
10
        return !!localStorage.getItem('token');
11
      },
12
    },
13
  },
14
});
15

16
const IS_LOGGED_IN = gql`
17
  query IsUserLoggedIn {
18
    isLoggedIn @client(always: true)
19
  }
20
`;
21

22
// ... run the query using client.query, a <Query /> component, etc.

The isLoggedIn resolver above is checking to see if an authentication token exists in localStorage. In this example, we want to make sure that every time the IS_LOGGED_IN query is executed, the isLoggedIn local resolver is also fired, so that we have the most up to date login information. To do this, we're using a @client(always: true) directive in the query, for the isLoggedIn field. If we didn't include always: true, then the local resolver would fire based on the queries fetchPolicy, which means we could be getting back a cached value for isLoggedIn. Using @client(always: true) ensures that we're always getting the direct result of running the associated local resolver.

While @client(always: true) ensures that a local resolver is always fired, it's important to note that if a query is using a fetchPolicy that leverages the cache first (cache-first, cache-and-network, cache-only), the query is still attempted to be resolved from the cache first, before the local resolver is fired. This happens because @client(always: true) use could be mixed with normal @client use in the same query, which means we want part of the query to adhere to the defined fetchPolicy. The benefit of this is that anything that can be loaded from the cache first is made available to your @client(always: true) resolver function, as its first parameter. So even though you've used @client(always: true) to identify that you want to always run a specific resolver, within that resolver you can look at the loaded cache values for the query, and decide if you want to proceed with running the resolver.

Using @client fields as variables

Apollo Client provides a way to use an @client field result as a variable for a selection set or field, in the same operation. So instead of running an @client based query first, getting the local result, then running a second query using the loaded local result as a variable, everything can be handled in one request. This is achieved by combining the @client directive with the @export(as: "variableName") directive:

1
import { ApolloClient } from 'apollo-client';
2
import { InMemoryCache } from 'apollo-cache-inmemory';
3
import { HttpLink } from 'apollo-link-http';
4
import gql from 'graphql-tag';
5

6
const query = gql`
7
  query currentAuthorPostCount($authorId: Int!) {
8
    currentAuthorId @client @export(as: "authorId")
9
    postCount(authorId: $authorId)
10
  }
11
`;
12

13
const cache = new InMemoryCache();
14
const client = new ApolloClient({
15
  link: new HttpLink({ uri: 'http://localhost:4000/graphql' }),
16
  cache,
17
  resolvers: {},
18
});
19

20
cache.writeData({
21
  data: {
22
    currentAuthorId: 12345,
23
  },
24
});
25

26
// ... run the query using client.query, the <Query /> component, etc.

In the example above, currentAuthorId is first loaded from the cache, then passed into the subsequent postCount field as the authorId variable (specified by the @export(as: "authorId") directive). The @export directive can also be used on specific fields within a selection set, like:

1
import { ApolloClient } from 'apollo-client';
2
import { InMemoryCache } from 'apollo-cache-inmemory';
3
import { HttpLink } from 'apollo-link-http';
4
import gql from 'graphql-tag';
5

6
const query = gql`
7
  query currentAuthorPostCount($authorId: Int!) {
8
    currentAuthor @client {
9
      name
10
      authorId @export(as: "authorId")
11
    }
12
    postCount(authorId: $authorId)
13
  }
14
`;
15

16
const cache = new InMemoryCache();
17
const client = new ApolloClient({
18
  link: new HttpLink({ uri: 'http://localhost:4000/graphql' }),
19
  cache,
20
  resolvers: {},
21
});
22

23
cache.writeData({
24
  data: {
25
    currentAuthor: {
26
      __typename: 'Author',
27
      name: 'John Smith',
28
      authorId: 12345,
29
    },
30
  },
31
});
32

33
// ... run the query using client.query, the <Query /> component, etc.

Here the authorId variable is set from the authorId field loaded from the cache stored currentAuthor. @export variable use isn't limited to remote queries; it can also be used to define variables for other @client fields or selection sets:

1
import { ApolloClient } from 'apollo-client';
2
import { InMemoryCache } from 'apollo-cache-inmemory';
3
import { HttpLink } from 'apollo-link-http';
4
import gql from 'graphql-tag';
5

6
const query = gql`
7
  query currentAuthorPostCount($authorId: Int!) {
8
    currentAuthorId @client @export(as: "authorId")
9
    postCount(authorId: $authorId) @client
10
  }
11
`;
12

13
const cache = new InMemoryCache();
14
const client = new ApolloClient({
15
  cache,
16
  resolvers: {
17
    Query: {
18
      postCount(_, { authorId }) {
19
        return authorId === 12345 ? 100 : 0;
20
      },
21
    },
22
  },
23
});
24

25
cache.writeData({
26
  data: {
27
    currentAuthorId: 12345,
28
  },
29
});
30

31
// ... run the query using client.query, the <Query /> component, etc.

So here the currentAuthorId is loaded from the cache, then passed into the postCount local resolver as authorId.

A few important notes about @export use:

1. Apollo Client currently only supports using the @export directive to store variables for local data. @export must be used with @client.

2. @client @export use might appear to go against the GraphQL specification, given that the execution order of an operation looks like it could affect the result. From the Normal and Serial Execution section of the GraphQL spec:

   ... the resolution of fields other than top‐level mutation fields must always be side effect‐free and idempotent, the execution order must not affect the result, and hence the server has the freedom to execute the field entries in whatever order it deems optimal.

   Apollo Client currently only supports the use of the @export directive when mixed with the @client directive. It prepares @export variables by first running through an operation that has @client @export directives, extracting the specified @export variables, then attempting to resolve the value of those variables from the local cache or local resolvers. Once a map of variable names to local values is built up, that map is then used to populate the variables passed in when running the server based GraphQL query. The execution order of the server based GraphQL query is not impacted by @export use; the variables are prepped and organized before the server query runs, so the specification is being followed.

3. If you define multiple @export variables that use the same name, in a single operation, the value of the last @export variable will be used as the variable value moving forward. When this happens Apollo Client will log a warning message (dev only).

Managing the cache

When you're using Apollo Client to work with local state, your Apollo cache becomes the single source of truth for all of your local and remote data. The Apollo cache API has several methods that can assist you with updating and retrieving data. Let's walk through the most relevant methods, and explore some common use cases for each one.

writeData

The easiest way to update the cache is with cache.writeData, which allows you to write data directly to the cache without passing in a query. Here's how you use it in your resolver map for a simple update:

1
import { ApolloClient } from 'apollo-client';
2
import { InMemoryCache } from 'apollo-cache-inmemory';
3

4
const client = new ApolloClient({
5
  cache: new InMemoryCache(),
6
  resolvers: {
7
    Mutation: {
8
      updateVisibilityFilter: (_, { visibilityFilter }, { cache }) => {
9
        const data = { visibilityFilter, __typename: 'Filter' };
10
        cache.writeData({ data });
11
      },
12
    },
13
  },
14
};