API Reference: expressMiddleware

This API reference documents Apollo Server 4's Express integration, the expressMiddleware function.

`expressMiddleware`

The expressMiddleware function enables you to attach Apollo Server to an Express server.

The expressMiddleware function expects you to set up HTTP body parsing and CORS headers for your web framework. Specifically, you should install the body-parser and cors packages and use them to set up your Express app, as shown below.

See Configuring CORS for guidance on configuring the CORS behavior of your project.

The expressMiddleware function accepts two arguments. The first required argument is an instance of ApolloServer that has been started:

1
import { ApolloServer } from '@apollo/server';
2
import { expressMiddleware } from '@apollo/server/express4';
3
import cors from 'cors';
4
import { json } from 'body-parser';
5
import express from 'express';
6

7
const app = express();
8

9
const server = new ApolloServer<MyContext>({
10
  typeDefs,
11
  resolvers,
12
});
13
// Note you must call `server.start()` on the `ApolloServer`
14
// instance before passing the instance to `expressMiddleware`
15
await server.start();
16

17
// Specify the path where we'd like to mount our server
18
app.use(
19
  '/graphql',
20
  cors<cors.CorsRequest>(),
21
  json(),
22
  expressMiddleware(server),
23
);

1
import { ApolloServer } from '@apollo/server';
2
import { expressMiddleware } from '@apollo/server/express4';
3
import cors from 'cors';
4
import { json } from 'body-parser';
5
import express from 'express';
6

7
const app = express();
8

9
const server = new ApolloServer({
10
  typeDefs,
11
  resolvers,
12
});
13

14
// Note you must call `server.start()` on the `ApolloServer`
15
// instance before passing the instance to `expressMiddleware`
16
await server.start();
17

18
// Specify the path where we'd like to mount our server
19
app.use('/graphql', cors(), json(), expressMiddleware(server));
20

⚠️ To ensure your server gracefully shuts down, we recommend using the ApolloServerPluginDrainHttpServer plugin. See below for an example.

The expressMiddleware function's second optional argument is an object for configuring ApolloServer, which can contain the following options:

Name / Type	Description
`context` `Function`	An optional asynchronous `context` initialization function. The `context` function should return an object that all your server's resolvers share during an operation's execution. This enables resolvers to share helpful context values, such as a database connection. The `context` function receives `req` and `res` options which are `express.Request` and `express.Response` objects.

Example

Below is a full example of setting up expressMiddleware:

1
// npm install @apollo/server express graphql cors body-parser
2
import { ApolloServer } from '@apollo/server';
3
import { expressMiddleware } from '@apollo/server/express4';
4
import { ApolloServerPluginDrainHttpServer } from '@apollo/server/plugin/drainHttpServer';
5
import express from 'express';
6
import http from 'http';
7
import cors from 'cors';
8
import bodyParser from 'body-parser';
9
import { typeDefs, resolvers } from './schema';
10

11
interface MyContext {
12
  token?: String;
13
}
14

15
async function startApolloServer() {
16
  // Required logic for integrating with Express
17
  const app = express();
18
  // Our httpServer handles incoming requests to our Express app.
19
  // Below, we tell Apollo Server to "drain" this httpServer,
20
  // enabling our servers to shut down gracefully.
21
  const httpServer = http.createServer(app);
22

23
  // Same ApolloServer initialization as before, plus the drain plugin
24
  // for our httpServer.
25
  const server = new ApolloServer<MyContext>({
26
    typeDefs,
27
    resolvers,
28
    plugins: [ApolloServerPluginDrainHttpServer({ httpServer })],
29
  });
30
  // Ensure we wait for our server to start
31
  await server.start();
32

33
  // Set up our Express middleware to handle CORS, body parsing,
34
  // and our expressMiddleware function.
35
  app.use(
36
    '/',
37
    cors<cors.CorsRequest>(),
38
    bodyParser.json(),
39
    // expressMiddleware accepts the same arguments:
40
    // an Apollo Server instance and optional configuration options
41
    expressMiddleware(server, {
42
      context: async ({ req }) => ({ token: req.headers.token }),
43
    }),
44
  );
45

46
  // Modified server startup
47
  await new Promise<void>((resolve) =>
48
    httpServer.listen({ port: 4000 }, resolve),
49
  );
50
  console.log(`🚀 Server ready at http://localhost:4000/`);
51
}

1
// npm install @apollo/server express graphql cors body-parser
2
import { ApolloServer } from '@apollo/server';
3
import { expressMiddleware } from '@apollo/server/express4';
4
import { ApolloServerPluginDrainHttpServer } from '@apollo/server/plugin/drainHttpServer';
5
import express from 'express';
6
import http from 'http';
7
import cors from 'cors';
8
import bodyParser from 'body-parser';
9
import { typeDefs, resolvers } from './schema';
10

11
async function startApolloServer() {
12
  // Required logic for integrating with Express
13
  const app = express();
14
  // Our httpServer handles incoming requests to our Express app.
15
  // Below, we tell Apollo Server to "drain" this httpServer,
16
  // enabling our servers to shut down gracefully.
17
  const httpServer = http.createServer(app);
18

19
  // Same ApolloServer initialization as before, plus the drain plugin
20
  // for our httpServer.
21
  const server = new ApolloServer({
22
    typeDefs,
23
    resolvers,
24
    plugins: [ApolloServerPluginDrainHttpServer({ httpServer })],
25
  });
26

27
  // Ensure we wait for our server to start
28
  await server.start();
29

30
  // Set up our Express middleware to handle CORS, body parsing,
31
  // and our expressMiddleware function.
32
  app.use(
33
    '/',
34
    cors(),
35
    bodyParser.json(),
36
    // expressMiddleware accepts the same arguments:
37
    // an Apollo Server instance and optional configuration options
38
    expressMiddleware(server, {
39
      context: async ({ req }) => ({ token: req.headers.token }),
40
    }),
41
  );
42

43
  // Modified server startup
44
  await new Promise(resolve => httpServer.listen({ port: 4000 }, resolve));
45

46
  console.log(`🚀 Server ready at http://localhost:4000/`);
47
}

Edit on GitHub

startStandaloneServer

Overview