Creating Apollo Server plugins

You can create your own Apollo Server plugins to perform custom operations in response to certain events. For example, a basic logging plugin might log the GraphQL query string associated with each request that's sent to Apollo Server.

The anatomy of a plugin

Plugins are JavaScript objects that implement one or more functions that respond to events. Here's a basic plugin that responds to the serverWillStart event:

1
const myPlugin = {
2
  async serverWillStart() {
3
    console.log('Server starting up!');
4
  },
5
};

1
const myPlugin = {
2
  async serverWillStart() {
3
    console.log('Server starting up!');
4
  },
5
};

You can define a plugin in the same file where you initialize Apollo Server, or you can export it as a separate module:

1
export default {
2
  async serverWillStart() {
3
    console.log('Server starting up!');
4
  },
5
};

1
export default {
2
  async serverWillStart() {
3
    console.log('Server starting up!');
4
  },
5
};

To create a plugin that accepts options, create a function that accepts an options object and returns a properly structured plugin object, like so:

1
export default (options: { logMessage: string }) => {
2
  return {
3
    async serverWillStart() {
4
      console.log(options.logMessage);
5
    },
6
  };
7
};

1
export default (options) => {
2
  return {
3
    async serverWillStart() {
4
      console.log(options.logMessage);
5
    },
6
  };
7
};

If your plugin needs to read the contextValue of a request (i.e., requestContext.contextValue), you must declare your plugin as an ApolloServerPlugin<YourContextType>, like so:

1
interface MyContext {
2
  token: string;
3
}
4

5
export default function (): ApolloServerPlugin<MyContext> {
6
  return {
7
    async requestDidStart({ contextValue }) {
8
      // token is properly inferred as a string
9
      console.log(contextValue.token);
10
    },
11
  };
12
}

1
export default function () {
2
  return {
3
    async requestDidStart({ contextValue }) {
4
      // token is properly inferred as a string
5
      console.log(contextValue.token);
6
    },
7
  };
8
}

Responding to events

A plugin specifies exactly which events it responds to by implementing functions that correspond to those events. The plugin in the examples above responds to the serverWillStart event, which fires when Apollo Server is preparing to start up. Almost all plugin events are async functions (i.e., functions that return Promises). The only exceptions are willResolveField and schemaDidLoadOrUpdate.

A plugin can respond to any combination of supported events.

Responding to request lifecycle events

Plugins can respond to the following events associated with the GraphQL request lifecycle:

• didResolveSource
• parsingDidStart
• validationDidStart
• didResolveOperation
• responseForOperation
• executionDidStart
• didEncounterErrors
• willSendResponse

However, the way you define these functions is slightly different from the serverWillStart example above. First, your plugin must define the requestDidStart function:

1
const myPlugin = {
2
  async requestDidStart() {
3
    console.log('Request started!');
4
  },
5
};

1
const myPlugin = {
2
  async requestDidStart() {
3
    console.log('Request started!');
4
  },
5
};

The requestDidStart event fires whenever Apollo Server receives a GraphQL request, before any of the lifecycle events listed above. You can respond to this event just like you respond to serverWillStart, but you also use this function to define responses for a request's lifecycle events, like so:

1
const myPlugin = {
2
  async requestDidStart(requestContext) {
3
    console.log('Request started!');
4

5
    return {
6
      async parsingDidStart(requestContext) {
7
        console.log('Parsing started!');
8
      },
9

10
      async validationDidStart(requestContext) {
11
        console.log('Validation started!');
12
      },
13
    };
14
  },
15
};

1
const myPlugin = {
2
  async requestDidStart(requestContext) {
3
    console.log('Request started!');
4

5
    return {
6
      async parsingDidStart(requestContext) {
7
        console.log('Parsing started!');
8
      },
9

10
      async validationDidStart(requestContext) {
11
        console.log('Validation started!');
12
      },
13
    };
14
  },
15
};

As shown, the requestDidStart function can optionally return an object that defines functions that respond to request lifecycle events. This structure organizes and encapsulates all of your plugin's request lifecycle logic, making it easier to reason about.

Request lifecycle event flow

The following diagram illustrates the sequence of events that fire for each request. Each of these events is documented in Apollo Server plugin events.

End hooks

Event handlers for the following events can optionally return a function that is invoked after the corresponding lifecycle phase ends:

• parsingDidStart
• validationDidStart
• willResolveField

The executionDidStart hook returns an object containing an executionDidEnd function instead of just a function as an end hook. This is because the returned object can also contain willResolveField.

Just like the event handlers themselves, these end hooks are async functions (except for the end hook for willResolveField).

End hooks are passed any errors that occurred during the execution of that lifecycle phase. For example, the following plugin logs any errors that occur during any of the above lifecycle events:

1
const myPlugin = {
2
  async requestDidStart() {
3
    return {
4
      async parsingDidStart() {
5
        return async (err) => {
6
          if (err) {
7
            console.error(err);
8
          }
9
        };
10
      },
11
      async validationDidStart() {
12
        // This end hook is unique in that it can receive an array of errors,
13
        // which will contain every validation error that occurred.
14
        return async (errs) => {
15
          if (errs) {
16
            errs.forEach((err) => console.error(err));
17
          }
18
        };
19
      },
20
      async executionDidStart() {
21
        return {
22
          async executionDidEnd(err) {
23
            if (err) {
24
              console.error(err);
25
            }
26
          },
27
        };
28
      },
29
    };
30
  },
31
};

1
const myPlugin = {
2
  async requestDidStart() {
3
    return {
4
      async parsingDidStart() {
5
        return async (err) => {
6
          if (err) {
7
            console.error(err);
8
          }
9
        };
10
      },
11
      async validationDidStart() {
12
        // This end hook is unique in that it can receive an array of errors,
13
        // which will contain every validation error that occurred.
14
        return async (errs) => {
15
          if (errs) {
16
            errs.forEach((err) => console.error(err));
17
          }
18
        };
19
      },
20
      async executionDidStart() {
21
        return {
22
          async executionDidEnd(err) {
23
            if (err) {
24
              console.error(err);
25
            }
26
          },
27
        };
28
      },
29
    };
30
  },
31
};

Note that the validationDidStart end hook receives an array of errors that contains every validation error that occurred (if any). The willResolveField end hook receives the error thrown by the resolver as the first argument and the result of the resolver as the second argument. The arguments to each end hook are documented in the type definitions in Request lifecycle events.

Inspecting request and response details

As the example above shows, requestDidStart and request lifecycle functions accept a requestContext parameter. This parameter is of type GraphQLRequestContext, which includes a request (of type GraphQLRequest), along with a response field (of type GraphQLResponse) if it's available.

These types and their related subtypes are all defined in @apollo/server.

Installing custom plugins

Add your plugins to Apollo Server by providing a plugins configuration option to the ApolloServer constructor, like so:

1
import { ApolloServer } from '@apollo/server';
2
import ApolloServerOperationRegistry from '@apollo/server-plugin-operation-registry';
3

4
/* This example doesn't provide `typeDefs` or `resolvers`,
5
   both of which are required to start the server. */
6
import { typeDefs, resolvers } from './separatelyDefined';
7

8
const server = new ApolloServer({
9
  typeDefs,
10
  resolvers,
11
  // You can import plugins or define them in-line, as shown:
12
  plugins: [
13
    /* This plugin is from a package that's imported above. */
14
    ApolloServerOperationRegistry({
15
      /* options */
16
    }),
17

18
    /* This plugin is imported in-place. */
19
    require('./localPluginModule'),
20

21
    /* This plugin is defined in-line. */
22
    {
23
      async serverWillStart() {
24
        console.log('Server starting up!');
25
      },
26
    },
27
  ],
28
});

1
import { ApolloServer } from '@apollo/server';
2
import ApolloServerOperationRegistry from '@apollo/server-plugin-operation-registry';
3

4
/* This example doesn't provide `typeDefs` or `resolvers`,
5
   both of which are required to start the server. */
6
import { typeDefs, resolvers } from './separatelyDefined';
7

8
const server = new ApolloServer({
9
  typeDefs,
10
  resolvers,
11
  // You can import plugins or define them in-line, as shown:
12
  plugins: [
13
    /* This plugin is from a package that's imported above. */
14
    ApolloServerOperationRegistry({
15
      /* options */
16
    }),
17

18
    /* This plugin is imported in-place. */
19
    require('./localPluginModule'),
20

21
    /* This plugin is defined in-line. */
22
    {
23
      async serverWillStart() {
24
        console.log('Server starting up!');
25
      },
26
    },
27
  ],
28
});