Context and contextValue

Sharing information and request details throughout your server

During a GraphQL operation, you can share data throughout your server's resolvers and plugins by creating an object named contextValue.

You can pass useful things through your contextValue that any resolver might need, like authentication scope, sources for fetching data, database connections, and custom fetch functions. If you're using dataloaders to batch requests across resolvers, you can also attach them to the shared contextValue.

The `context` function

📣 Apollo Server 4 changes the syntax for defining a context function. See more details.

The context function should be asynchronous and return an object. This object is then accessible to your server's resolvers and plugins using the name contextValue.

You can pass a context function to your integration function of choice (e.g., expressMiddleware or startStandaloneServer).

Your server calls the context function once for every request, enabling you to customize your contextValue with each request's details (such as HTTP headers):

1
import { GraphQLError } from 'graphql';
2

3
const resolvers = {
4
  Query: {
5
    // Example resolver
6
    adminExample: (parent, args, contextValue, info) => {
7
      if (contextValue.authScope !== ADMIN) {
8
        throw new GraphQLError('not admin!', {
9
          extensions: { code: 'UNAUTHENTICATED' },
10
        });
11
      }
12
    },
13
  },
14
};
15

16
interface MyContext {
17
  // You can optionally create a TS interface to set up types
18
  // for your contextValue
19
  authScope?: String;
20
}
21

22
const server = new ApolloServer<MyContext>({
23
  typeDefs,
24
  resolvers,
25
});
26

27
const { url } = await startStandaloneServer(server, {
28
  // Your async context function should async and
29
  // return an object
30
  context: async ({ req, res }) => ({
31
    authScope: getScope(req.headers.authorization),
32
  }),
33
});

1
import { GraphQLError } from 'graphql';
2

3
const resolvers = {
4
  Query: {
5
    // Example resolver
6
    adminExample: (parent, args, contextValue, info) => {
7
      if (contextValue.authScope !== ADMIN) {
8
        throw new GraphQLError('not admin!', {
9
          extensions: { code: 'UNAUTHENTICATED' },
10
        });
11
      }
12
    },
13
  },
14
};
15

16
const server = new ApolloServer({
17
  typeDefs,
18
  resolvers,
19
});
20

21
const { url } = await startStandaloneServer(server, {
22
  // Your async context function should async and
23
  // return an object
24
  context: async ({ req, res }) => ({
25
    authScope: getScope(req.headers.authorization),
26
  }),
27
});

The above example assumes you're using either startStandaloneServer or expressMiddleware, both of which use Express under the hood. Your context function's incoming arguments might differ if you're using a different integration.

If you are using TypeScript, you must provide a named context function if you type your context by passing a type parameter to ApolloServer (i.e., you don't use ApolloServer<BaseContext>).

Because the context initialization function is asynchronous, you can use it to establish database connections and wait for other operations to complete:

1
context: async () => ({
2
  db: await client.connect(),
3
})
4

5
// Resolver
6
(parent, args, contextValue, info) => {
7
  return contextValue.db.query('SELECT * FROM table_name');
8
}

Throwing errors

By default, if your context function throws an error, Apollo Server returns that error in a JSON response with a 500 HTTP status code. If the error is not a GraphQLError, the error's message is prepended with "Context creation failed: ".

You can change the HTTP status code of an error by throwing a GraphQLError with an http extension. For example:

1
context: async ({ req }) => {
2
  const user = await getUserFromReq(req);
3
  if (!user) {
4
    throw new GraphQLError('User is not authenticated', {
5
      extensions: {
6
        code: 'UNAUTHENTICATED',
7
        http: { status: 401 },
8
      }
9
    });
10
  }
11

12
  // If the below throws a non-GraphQLError, the server returns
13
  // `code: "INTERNAL_SERVER_ERROR"` with an HTTP status code 500, and
14
  // a message starting with "Context creation failed: ".
15
  const db = await getDatabaseConnection();
16

17
  return { user, db };
18
},

The `contextValue` object

The context function returns an object, contextValue, that is accessible to your plugins and resolvers.

Resolvers

Resolvers should never destructively modify the contextValue argument. This ensures consistency across all resolvers and prevents unexpected errors.

Your resolvers can access the shared contextValue object via their third positional argument. All resolvers that are executing for a particular operation have access to contextValue:

1
import { AnimalAPI } from './datasources/animals';
2

3
const resolvers = {
4
  Query: {
5
    // All of our resolvers can access our shared contextValue!
6
    dogs: (_, __, contextValue) => {
7
      return contextValue.dataSources.animalApi.getDogs();
8
    },
9
    cats: (_, __, contextValue) => {
10
      return contextValue.dataSources.animalApi.getCats();
11
    },
12
  },
13
};
14

15
interface MyContext {
16
  // Context typing
17
  dataSources: {
18
    animalApi: AnimalAPI;
19
  };
20
}
21

22
const server = new ApolloServer<MyContext>({
23
  typeDefs,
24
  resolvers,
25
});
26

27
const { url } = await startStandaloneServer(server, {
28
  context: async () => {
29
    const animalApi = new AnimalAPI();
30
    return {
31
      dataSources: {
32
        animalApi,
33
      },
34
    };
35
  },
36
});

1
import { AnimalAPI } from './datasources/animals';
2

3
const resolvers = {
4
  Query: {
5
    // All of our resolvers can access our shared contextValue!
6
    dogs: (_, __, contextValue) => {
7
      return contextValue.dataSources.animalApi.getDogs();
8
    },
9
    cats: (_, __, contextValue) => {
10
      return contextValue.dataSources.animalApi.getCats();
11
    },
12
  },
13
};
14

15
const server = new ApolloServer({
16
  typeDefs,
17
  resolvers,
18
});
19

20
const { url } = await startStandaloneServer(server, {
21
  context: async () => {
22
    const animalApi = new AnimalAPI();
23
    return {
24
      dataSources: {
25
        animalApi,
26
      },
27
    };
28
  },
29
});

Plugins

Built-in and custom plugins can access contextValue through request lifecycle functions, like so:

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

5
const server = new ApolloServer<MyContext>({
6
  typeDefs,
7
  resolvers: {
8
    Query: {
9
      hello: (root, args, { token }) => {
10
        return token;
11
      },
12
    },
13
  },
14
  plugins: [
15
    {
16
      async requestDidStart({ contextValue }) {
17
        // token is properly inferred as a string
18
        console.log(contextValue.token);
19
      },
20
    },
21
  ],
22
});
23

24
const { url } = await startStandaloneServer(server, {
25
  context: async ({ req, res }) => ({
26
    token: await getTokenForRequest(req),
27
  }),
28
});

1
const server = new ApolloServer({
2
  typeDefs,
3
  resolvers: {
4
    Query: {
5
      hello: (root, args, { token }) => {
6
        return token;
7
      },
8
    },
9
  },
10
  plugins: [
11
    {
12
      async requestDidStart({ contextValue }) {
13
        // token is properly inferred as a string
14
        console.log(contextValue.token);
15
      },
16
    },
17
  ],
18
});
19

20
const { url } = await startStandaloneServer(server, {
21
  context: async ({ req, res }) => ({
22
    token: await getTokenForRequest(req),
23
  }),
24
});

Resolvers

Error handling

Context and contextValue

Sharing information and request details throughout your server

The context function

Throwing errors

The contextValue object

Resolvers

Plugins

The `context` function

The `contextValue` object