API Reference: Cache control plugin

Using the plugin

This API reference documents the ApolloServerPluginCacheControl plugin.

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 by default sets the cache-control HTTP response header. This page is a reference for the options available in configuring the plugin; more background and examples are available in the caching documentation.

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 this plugin, import it from the apollo-server-core package and pass it to your ApolloServer in the plugins array:

import { ApolloServer } from "apollo-server";
import { ApolloServerPluginCacheControl } from "apollo-server-core";

const server = new ApolloServer({
  typeDefs,
  resolvers,
  plugins: [
    ApolloServerPluginCacheControl({
      // Cache everything for 1 second by default.
      defaultMaxAge: 1000,
      // Don't send the `cache-control` response header.
      calculateHttpHeaders: false,
    }),
  ],
});

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

import { ApolloServer } from "apollo-server";
import { ApolloServerPluginCacheControlDisabled } from "apollo-server-core";

const server = new ApolloServer({
  typeDefs,
  resolvers,
  plugins: [ApolloServerPluginCacheControlDisabled()],
});

(The plugin does not have much of an effect on your app if you do not use the @cacheControl directive or use the info.cacheControl API; there might be a very slight performance improvement from disabling the plugin if you do not use it.)

Note that in Apollo Server 3, the cache control plugin does not define the @cacheControl directive for you; if you want to use the directive, you must define the @cacheControl directive in your schema.

Options