Using GraphQL directives in Apollo Client

A directive decorates part of a GraphQL schema or operation with additional configuration. Tools like Apollo Client can read a GraphQL document's directives and perform custom logic as appropriate.

Directives are preceded by the @ character, like so:

1
query myQuery($someTest: Boolean) {
2
  experimentalField @skip(if: $someTest)
3
}

This example shows the @skip directive, which is a built-in directive (i.e., it's part of the GraphQL specification). It demonstrates the following about directives:

• Directives can take arguments of their own (if in this case).
• Directives appear after the declaration of what they decorate (the experimentalField field in this case).

@client

The @client directive allows you to resolve client-only data alongside your server data. These fields are not sent to the GraphQL server.

1
query LaunchDetails($launchId: ID!) {
2
  launch(id: $launchId) {
3
    site
4
    rocket {
5
      type
6
      # resolved locally on the client,
7
      # removed from the request to the server
8
      description @client
9
    }
10
  }
11
}

For more information about the @client directive, see this section on local-only fields. The @client directive is also useful for client schema mocking before a given field is supported in the GraphQL API your application is consuming.

@connection

The @connection directive allows you to specify a custom cache key for paginated results. For more information, see this section on the @connection directive.

1
query Feed($offset: Int, $limit: Int) {
2
  feed(offset: $offset, limit: $limit) @connection(key: "feed") {
3
    ...FeedFields
4
  }
5
}

@defer

Beginning with version 3.7.0, Apollo Client provides preview support for the @defer directive. This directive enables your queries to receive data for specific fields incrementally, instead of receiving all field data at the same time. This is helpful whenever some fields in a query take much longer to resolve than others.

To use the @defer directive, we apply it to an inline or named fragment that contains all slow-resolving fields:

1
query PersonQuery($personId: ID!) {
2
  person(id: $personId) {
3
    # Basic fields (fast)
4
    id
5
    firstName
6
    lastName
7

8
    # Friend fields (slower)
9
    ... @defer {
10
      friends {
11
        id
12
      }
13
    }
14
  }
15
}

For more information about the @defer directive, check out the @defer docs.

@export

If your GraphQL query uses variables, the local-only fields of that query can provide the values of those variables.

To do so, you apply the @export(as: "variableName") directive, like so:

1
const GET_CURRENT_AUTHOR_POST_COUNT = gql`
2
  query CurrentAuthorPostCount($authorId: Int!) {
3
    currentAuthorId @client @export(as: "authorId")
4
    postCount(authorId: $authorId)
5
  }
6
`;

In the query above, the result of the local-only field currentAuthorId is used as the value of the $authorId variable that's passed to postCount.

You can do this even if postCount is also a local-only field (i.e., if it's also marked as @client).

For more information and other considerations when using the @export directive, check out the local-only fields docs.

The @nonreactive directive can be used to mark query fields or fragment spreads and is used to indicate that changes to the data contained within the subtrees marked @nonreactive should not trigger rerendering. This allows parent components to fetch data to be rendered by their children without rerendering themselves when the data corresponding with fields marked as @nonreactive change.

Consider an App component that fetches and renders a list of ski trails:

1
const TrailFragment = gql`
2
  fragment TrailFragment on Trail {
3
    name
4
    status
5
  }
6
`;
7

8
const ALL_TRAILS = gql`
9
  query allTrails {
10
    allTrails {
11
      id
12
      ...TrailFragment @nonreactive
13
    }
14
  }
15
  ${TrailFragment}
16
`;
17

18
function App() {
19
  const { data, loading } = useQuery(ALL_TRAILS);
20
  return (
21
    <main>
22
      <h2>Ski Trails</h2>
23
      <ul>
24
        {data?.trails.map((trail) => (
25
          <Trail key={trail.id} id={trail.id} />
26
        ))}
27
      </ul>
28
    </main>
29
  );
30
}

The Trail component renders a trail's name and status and allows the user to execute a mutation to toggle the status of the trail between "OPEN" and "CLOSED":

1
const Trail = ({ id }) => {
2
  const [updateTrail] = useMutation(UPDATE_TRAIL);
3
  const { data } = useFragment({
4
    fragment: TrailFragment,
5
    from: {
6
      __typename: "Trail",
7
      id,
8
    },
9
  });
10
  return (
11
    <li key={id}>
12
      {data.name} - {data.status}
13
      <input
14
        checked={data.status === "OPEN" ? true : false}
15
        type="checkbox"
16
        onChange={(e) => {
17
          updateTrail({
18
            variables: {
19
              trailId: id,
20
              status: e.target.checked ? "OPEN" : "CLOSED",
21
            },
22
          });
23
        }}
24
      />
25
    </li>
26
  );
27
};

Notice that the Trail component isn't receiving the entire trail object via props, only the id which is used along with the fragment document to create a live binding for each trail item in the cache. This allows each Trail component to react to the cache updates for a single trail independently. Updates to a trail's status will not cause the parent App component to rerender since the @nonreactive directive is applied to the TrailFragment spread, a fragment that includes the status field.