API Reference: Cache control plugin

Using the plugin

This article documents the options for the ApolloServerPluginCacheControl plugin, which you can import from @apollo/server/plugin/cacheControl.

This plugin enables your GraphQL server to specify a cache policy at the field level, either statically in your schema with the @cacheControl directive, or dynamically in your resolvers via the info.cacheControl API. It also sets the cache-control HTTP response header by default. See Server-side caching for more information and examples.

To use the @cacheControl directive, you must first define it in your schema.

Apollo Server installs this plugin by default in all servers, with its default configuration. You typically do not have to install this plugin yourself; you only need to do so if you want to provide non-default configuration.

If you want to configure the ApolloServerPluginCacheControl plugin, import it and pass it to your ApolloServer constructor's plugins array:

1
import { ApolloServer } from '@apollo/server';
2
import { ApolloServerPluginCacheControl } from '@apollo/server/plugin/cacheControl';
3

4
const server = new ApolloServer({
5
  typeDefs,
6
  resolvers,
7
  plugins: [
8
    ApolloServerPluginCacheControl({
9
      // Cache everything for 1 second by default.
10
      defaultMaxAge: 1,
11
      // Don't send the `cache-control` response header.
12
      calculateHttpHeaders: false,
13
    }),
14
  ],
15
});

1
import { ApolloServer } from '@apollo/server';
2
import { ApolloServerPluginCacheControl } from '@apollo/server/plugin/cacheControl';
3

4
const server = new ApolloServer({
5
  typeDefs,
6
  resolvers,
7
  plugins: [
8
    ApolloServerPluginCacheControl({
9
      // Cache everything for 1 second by default.
10
      defaultMaxAge: 1,
11
      // Don't send the `cache-control` response header.
12
      calculateHttpHeaders: false,
13
    }),
14
  ],
15
});

If you don't want to use cache control at all, you can explicitly disable it with the ApolloServerPluginCacheControlDisabled plugin:

1
import { ApolloServer } from '@apollo/server';
2
import { ApolloServerPluginCacheControlDisabled } from '@apollo/server/plugin/disabled';
3

4
const server = new ApolloServer({
5
  typeDefs,
6
  resolvers,
7
  plugins: [ApolloServerPluginCacheControlDisabled()],
8
});

1
import { ApolloServer } from '@apollo/server';
2
import { ApolloServerPluginCacheControlDisabled } from '@apollo/server/plugin/disabled';
3

4
const server = new ApolloServer({
5
  typeDefs,
6
  resolvers,
7
  plugins: [ApolloServerPluginCacheControlDisabled()],
8
});

The plugin doesn't affect your app much if you don't use the @cacheControl directive or the info.cacheControl API. If you don't currently use it, there might be a very slight performance improvement from disabling the plugin.

Options

Name / Type	Description
`defaultMaxAge` `number`	By default, root fields and fields that return a composite type (object, interface, or union) are considered to be uncacheable (`maxAge` 0) unless a cache hint is explicitly provided via `@cacheControl` or `info.cacheControl`. You can set this option to make the default `maxAge` for these larger than 0; this will effectively cause all requests to be cacheable. This option was popular in Apollo Server 2 as a workaround for the problem solved by the `@cacheControl(inheritMaxAge: true)` directive argument. See Default `maxAge` for more details.
`calculateHttpHeaders` `boolean \| 'if-cacheable'`	By default, the cache control plugin sets the `cache-control` HTTP response header to `max-age=MAXAGE, public` or `max-age=MAXAGE, private` if the request is cacheable, and to `no-store` if the request is not cacheable. If you specify `calculateHttpHeaders: false`, it will not set this header. If you specify `calculateHttpHeaders: 'if-cacheable'`, it will only set the header if the request is cacheable. (A response is cacheable if its overall cache policy has a non-zero `maxAge`, and the body is a single result rather than an incremental delivery response, and the body contains no errors.) Setting this option does not prevent the `requestContext.overallCachePolicy` field from being calculated, nor does it prevent the response cache plugin from working.

Drain HTTP server

Landing pages

API Reference: Cache control plugin

Using the plugin

Options

`defaultMaxAge`

`calculateHttpHeaders`