Migrating to Apollo Server 4

Apollo Server 4 focuses on improving Apollo Server's extensibility and making it simpler to use, maintain, and document. To learn more about the inspiration behind this release, see the Apollo Server Roadmap.

Apollo Server 4 provides the following features:

• A well-defined API with a stable HTTP abstraction, enabling contributors to easily build and maintain integrations in their preferred frameworks.
• A new @apollo/server package, combining numerous smaller packages and including the startStandaloneServer and expressMiddleware functions.
• Packages that can be used as either ECMAScript or CJS modules.
• Experimental support for incremental delivery when combined with a pre-release of graphql-js.

We recommend that all users of Apollo Server upgrade to Apollo Server 4 as soon as possible. Apollo Server 2 and Apollo Server 3 are deprecated, with an end-of-life date of October 22nd, 2023.

The new @apollo/server package

Apollo Server 3 is distributed as a fixed set of packages for integrating with different web frameworks and environments. The main "batteries-included" apollo-server package reduces setup time by providing a minimally customizable GraphQL server.

In Apollo Server 3, the apollo-server-core package defines an ApolloServer "base" class, which each integration package (apollo-server-express,apollo-server-lambda, etc.) subclasses with a slightly different API. This packaging structure means that new integration package releases are lockstep versioned to Apollo Server itself, making it challenging to support major versions of frameworks and add integration-specific changes. Additionally, Apollo Server 3 doesn't provide a way to add new integrations for additional frameworks.

Apollo Server 4 takes a different approach to integrations by providing a stable web framework integration API, which includes explicit support for serverless framework life cycles.

The new @apollo/server package contains:

• The ApolloServer class
• An Express 4 integration (similar to Apollo Server 3's apollo-server-express package)
• A standalone server (similar to Apollo Server 3's apollo-server package)
• A set of core plugins (similar to Apollo Server 3's apollo-server-core package)

There are no integration-specific subclasses in Apollo Server 4. Instead, there's a single ApolloServer class with a single API that all integrations use.

In Apollo Server 3, the Apollo Server core team was responsible for maintaining every integration package. With Apollo Server 4, the AS core team no longer directly maintains most integration packages. Instead, we work with the broader open source community to maintain Apollo Server integrations, enabling those who regularly use different web frameworks to make the best choices for their framework's integration.

For those migrating from Apollo Server 3 to Apollo Server 4, use the below flowchart to see your migration path:

• If you're currently using the apollo-server package, you should use the startStandaloneServer function.
• If you're currently using the apollo-server-express package, you should use the expressMiddleware function.

The @apollo/server package exports these functions alongside the ApolloServer class.

If you are using another Apollo Server 3 framework integration package (such as apollo-server-koa or apollo-server-lambda), check out our list of integrations to see if a community-maintained integration package exists for your framework of choice.

If there is no Apollo Server integration for your favorite framework yet, help the broader community by building a new integration! You can also join the discussions about maintaining our existing integrations.

Below are a few high-level changes for using framework integrations:

• You can pass your context initialization function directly to your framework's integration function (e.g., expressMiddleware or startStandaloneServer) instead of the ApolloServer constructor.
• You are responsible for setting up HTTP body parsing and CORS using your framework integration's standard functionality.
• If you want your server to listen on a specific URL path, pass that path directly to your framework's router instead of using the path option. If you did not specify a URL path, the default in Apollo Server 3 was /graphql, so to preserve existing behavior, you should specify that path explicitly.

The following sections show how servers using apollo-server or apollo-server-express can update to Apollo Server 4.

Migrate from apollo-server

In Apollo Server 3, the apollo-server package is a "batteries-included" package that wraps apollo-server-express, providing an HTTP server with minimal HTTP-level customization.

If you used the "batteries included" apollo-server package in Apollo Server 3, use the startStandaloneServer function in Apollo Server 4.

This Apollo Server 3 code:

1
// npm install apollo-server graphql
2
import { ApolloServer } from 'apollo-server';
3
import { typeDefs, resolvers } from './schema';
4

5
interface MyContext {
6
  token?: String;
7
}
8

9
const server = new ApolloServer({
10
  typeDefs,
11
  resolvers,
12
  context: async ({ req }) => ({ token: req.headers.token }),
13
});
14
const { url } = await server.listen(4000);
15
console.log(`🚀  Server ready at ${url}`);

1
// npm install apollo-server graphql
2
import { ApolloServer } from 'apollo-server';
3
import { typeDefs, resolvers } from './schema';
4

5
const server = new ApolloServer({
6
  typeDefs,
7
  resolvers,
8
  context: async ({ req }) => ({ token: req.headers.token }),
9
});
10
const { url } = await server.listen(4000);
11
console.log(`🚀  Server ready at ${url}`);

looks like this in Apollo Server 4:

1
// npm install @apollo/server graphql
2
import { ApolloServer } from '@apollo/server';
3
import { startStandaloneServer } from '@apollo/server/standalone';
4
import { typeDefs, resolvers } from './schema';
5

6
interface MyContext {
7
  token?: String;
8
}
9

10
const server = new ApolloServer<MyContext>({ typeDefs, resolvers });
11
const { url } = await startStandaloneServer(server, {
12
  context: async ({ req }) => ({ token: req.headers.token }),
13
  listen: { port: 4000 },
14
});
15
console.log(`🚀  Server ready at ${url}`);

1
// npm install @apollo/server graphql
2
import { ApolloServer } from '@apollo/server';
3
import { startStandaloneServer } from '@apollo/server/standalone';
4
import { typeDefs, resolvers } from './schema';
5

6
const server = new ApolloServer({ typeDefs, resolvers });
7
const { url } = await startStandaloneServer(server, {
8
  context: async ({ req }) => ({ token: req.headers.token }),
9
  listen: { port: 4000 },
10
});
11
console.log(`🚀  Server ready at ${url}`);

The startStandaloneServer function accepts two arguments; the first is the instance of ApolloServer that should begin listening for incoming requests. The second is an object for configuring your server's options, which most notably accepts the following properties:

The startStandaloneServer function doesn't enable you to configure your server's CORS behavior. If you previously used the cors constructor option to customize your CORS settings in Apollo Server 3, use the expressMiddleware function in Apollo Server 4.

Similarly, if you used the stopGracePeriodMillis constructor option in Apollo Server 3, use the expressMiddleware function and specify stopGracePeriodMillis to the ApolloServerPluginDrainHttpServer plugin.

Migrate from apollo-server-express

If you used the apollo-server-express package in Apollo Server 3, use the expressMiddleware function in Apollo Server 4 (i.e., instead of using server.applyMiddleware or server.getMiddleware).

To migrate from Apollo Server 3's apollo-server-express package to using the expressMiddleware function, do the following:

1. Install the @apollo/server, cors, and body-parser packages.
2. Import symbols from @apollo/server (i.e., instead of from apollo-server-express and apollo-server-core).
3. Add cors and bodyParser.json() to your server setup.
4. Remove the Apollo Server 3 apollo-server-express and apollo-server-core packages.
5. If you are using apollo-server-express's default /graphql URL path (i.e., not specifying another URL with the path option), you can mount expressMiddleware at /graphql to maintain behavior. To use another URL path, mount your server (with app.use) at the specified path.

This Apollo Server 3 code:

1
// npm install apollo-server-express apollo-server-core express graphql
2
import { ApolloServer } from 'apollo-server-express';
3
import { ApolloServerPluginDrainHttpServer } from 'apollo-server-core';
4
import express from 'express';
5
import http from 'http';
6
import { typeDefs, resolvers } from './schema';
7

8
interface MyContext {
9
  token?: String;
10
}
11

12
const app = express();
13
const httpServer = http.createServer(app);
14
const server = new ApolloServer({
15
  typeDefs,
16
  resolvers,
17
  context: async ({ req }) => ({ token: req.headers.token }),
18
  plugins: [ApolloServerPluginDrainHttpServer({ httpServer })],
19
});
20
await server.start();
21
server.applyMiddleware({ app });
22
await new Promise<void>((resolve) => httpServer.listen({ port: 4000 }, resolve));
23
console.log(`🚀 Server ready at http://localhost:4000${server.graphqlPath}`);

1
// npm install apollo-server-express apollo-server-core express graphql
2
import { ApolloServer } from 'apollo-server-express';
3
import { ApolloServerPluginDrainHttpServer } from 'apollo-server-core';
4
import express from 'express';
5
import http from 'http';
6
import { typeDefs, resolvers } from './schema';
7

8
const app = express();
9
const httpServer = http.createServer(app);
10
const server = new ApolloServer({
11
  typeDefs,
12
  resolvers,
13
  context: async ({ req }) => ({ token: req.headers.token }),
14
  plugins: [ApolloServerPluginDrainHttpServer({ httpServer })],
15
});
16
await server.start();
17
server.applyMiddleware({ app });
18
await new Promise((resolve) => httpServer.listen({ port: 4000 }, resolve));
19
console.log(`🚀 Server ready at http://localhost:4000${server.graphqlPath}`);

looks like this in Apollo Server 4:

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 { json } from 'body-parser';
9
import { typeDefs, resolvers } from './schema';
10

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

15
const app = express();
16
const httpServer = http.createServer(app);
17
const server = new ApolloServer<MyContext>({
18
  typeDefs,
19
  resolvers,
20
  plugins: [ApolloServerPluginDrainHttpServer({ httpServer })],
21
});
22
await server.start();
23
app.use(
24
  '/graphql',
25
  cors<cors.CorsRequest>(),
26
  json(),
27
  expressMiddleware(server, {
28
    context: async ({ req }) => ({ token: req.headers.token }),
29
  }),
30
);
31

32
await new Promise<void>((resolve) => httpServer.listen({ port: 4000 }, resolve));
33
console.log(`🚀 Server ready at http://localhost:4000/graphql`);

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 { json } from 'body-parser';
9
import { typeDefs, resolvers } from './schema';
10

11
const app = express();
12
const httpServer = http.createServer(app);
13
const server = new ApolloServer({
14
  typeDefs,
15
  resolvers,
16
  plugins: [ApolloServerPluginDrainHttpServer({ httpServer })],
17
});
18
await server.start();
19
app.use(
20
  '/graphql',
21
  cors(),
22
  json(),
23
  expressMiddleware(server, {
24
    context: async ({ req }) => ({ token: req.headers.token }),
25
  }),
26
);
27

28
await new Promise((resolve) => httpServer.listen({ port: 4000 }, resolve));
29
console.log(`🚀 Server ready at http://localhost:4000/graphql`);

Removed integrations

Apollo Server 4 takes a fundamentally different approach to web framework integrations. By offering a well-defined API with a stable HTTP abstraction, Apollo Server 4 enables contributors to build and maintain integrations for the first time.

To that end, the Apollo Server core team no longer maintains the following integration packages in Apollo Server 4:

• apollo-server-fastify
• apollo-server-hapi
• apollo-server-koa
• apollo-server-lambda
• apollo-server-micro
• apollo-server-cloud-functions
• apollo-server-cloudflare
• apollo-server-azure-functions

Instead, we now work with the broader community to maintain the following open-source integrations for Apollo Server:

In Apollo Server 3, the apollo-server-express package supported both Express and its older predecessor Connect. In Apollo Server 4, expressMiddleware no longer supports Connect. An interested developer could build a Connect-specific middleware, and a PR to this migration guide is welcome if someone does this!

Packages merged into @apollo/server

As shown above, Apollo Server 4 combines the functionality of the apollo-server, apollo-server-express, and apollo-server-core packages into a new @apollo/server package.

But wait: there's more! The @apollo/server package also combines the following packages:

• apollo-server-errors
• apollo-server-plugin-base
• apollo-server-types

Plugins are in deep imports

In Apollo Server 3, the apollo-server-core package exports built-in plugins, like ApolloServerUsageReporting, at the top level. To use these plugins, you must install both the apollo-server-core package and the package you use to import ApolloServer (e.g., apollo-server or apollo-server-express).

In Apollo Server 4, these built-in plugins are part of the main @apollo/server package, which also imports the ApolloServer class. The @apollo/server package exports these built-in plugins with deep exports. This means you use deep imports for each built-in plugin, enabling you to evaluate only the plugin you use in your app and making it easier for bundlers to eliminate unused code.

There's one exception: the ApolloServerPluginLandingPageGraphQLPlayground plugin is now in its own package @apollo/server-plugin-landing-page-graphql-playground, which you can install separately.

This plugin installs the unmaintained GraphQL Playground project as a landing page and is provided for compatibility with Apollo Server 2. This package will not be supported after Apollo Server 4 is released. We strongly recommend you switch to Apollo Server's 4's default landing page, which installs the actively maintained Apollo Sandbox.

Apollo Server exports the following plugins:

For example, replace this Apollo Server 3 code:

1
import { ApolloServerPluginUsageReporting } from 'apollo-server-core';

with this Apollo Server 4 code:

1
import { ApolloServerPluginUsageReporting } from '@apollo/server/plugin/usageReporting';

You can also import each plugin's associated TypeScript types (e.g., ApolloServerPluginUsageReportingOptions) from the same deep import as that plugin.

Once you've updated your imports, you can remove your project's dependency on apollo-server-core.

Bumped dependencies

Node.js

Apollo Server 4 supports Node.js 14.16.0 and later. (Apollo Server 3 supports Node.js 12.) This includes all LTS and Current major versions at the time of release.

If you're using Node.js 12, upgrade your runtime before upgrading to Apollo Server 4.

(Apollo Server 4 specifically requires v14.16.0 instead of merely v14.0.0, because that is the minimum version of Node.js 14 supported by our minimum supported version of graphql, as described in the next section.)

graphql

Apollo Server has a peer dependency on graphql (the core JS GraphQL implementation). Apollo Server 4 supports graphql v16.6.0 and later. (Apollo Server 3 supports graphql v15.3.0 through v16.)

If you're using an older version of graphql, upgrade it to a supported version before upgrading to Apollo Server 4.

Note that upgrading graphql may require you to upgrade other libraries that are installed in your project. For example, if you use Apollo Server with Apollo Gateway, you should upgrade Apollo Gateway to at least v0.50.1 or any v2.x version for full graphql 16 support before upgrading to Apollo Server 4.

TypeScript

If you use Apollo Server with TypeScript, you must use TypeScript v4.7.0 or newer.

For background, Apollo Server uses type system features introduced in v4.7. We want to put out "downleveled" versions of @apollo/server's type definitions for older versions of TypeScript, but have found TypeScript's typesVersions feature challenging to use.

If supporting older versions of TypeScript is important to you and you'd like to help us get typesVersions working, we'd appreciate PRs!

Removed constructor options

The following ApolloServer constructor options have been removed in favor of other features or configuration methods.

dataSources

In Apollo Server 3, the top-level dataSources constructor option essentially adds a post-processing step to your app's context function, creating DataSource subclasses and adding them to a dataSources field on your context object. This means the TypeScript type the context function returns is different from the context type your resolvers and plugins receive. Additionally, this design obfuscates that DataSource objects are created once per request (i.e., like the rest of the context object).

Apollo Server 4 removes the dataSources constructor option. You can now treat DataSources like any other part of your context object.

In Apollo Server 3, immediately after constructing each DataSource subclass, Apollo Server invokes the dataSource.initialize({ cache, context }) function on each new DataSource. If you need to replicate this behavior in Apollo Server 4, you can pass the cache and context arguments to each DataSource constructor. In Apollo Server 4, you can find cache as a new readonly field on ApolloServer.

For example, below, we use the RESTDataSource class to create a DataSource with Apollo Server 3:

1
import { RESTDataSource, RequestOptions } from 'apollo-datasource-rest';
2
import { ApolloServer } from 'apollo-server';
3

4
class MoviesAPI extends RESTDataSource {
5
  override baseURL = 'https://movies-api.example.com/';
6

7
  override willSendRequest(request: RequestOptions) {
8
    request.headers.set('Authorization', this.context.token);
9
  }
10

11
  async getMovie(id: string): Promise<Movie> {
12
    return this.get<Movie>(`movies/${encodeURIComponent(id)}`);
13
  }
14

15
  async updateMovie(movie: Movie): Promise<Movie> {
16
    return this.patch(
17
      'movies',
18
      // Syntax for passing a request body
19
       { id: movie.id, movie },
20
    );
21
  }
22
}
23

24
interface ContextValue {
25
  token: string;
26
  dataSources: {
27
    moviesAPI: MoviesAPI;
28
  };
29
}
30

31
const server = new ApolloServer({
32
  typeDefs,
33
  resolvers,
34
  context: ({ req: ExpressRequest }): Omit<ContextValue, 'dataSources'> => {
35
    return {
36
      token: getTokenFromRequest(req),
37
    };
38
  },
39
  dataSources: (): ContextValue['dataSources'] => {
40
    return {
41
      moviesAPI: new MoviesAPI(),
42
    };
43
  },
44
});
45

46
await server.listen();

1
import { RESTDataSource } from 'apollo-datasource-rest';
2
import { ApolloServer } from 'apollo-server';
3

4
class MoviesAPI extends RESTDataSource {
5
  baseURL = 'https://movies-api.example.com/';
6

7
  willSendRequest(request) {
8
    request.headers.set('Authorization', this.context.token);
9
  }
10

11
  async getMovie(id) {
12
    return this.get(`movies/${encodeURIComponent(id)}`);
13
  }
14

15
  async updateMovie(movie) {
16
    return this.patch(
17
      'movies',
18
      // Syntax for passing a request body
19
       { id: movie.id, movie },
20
    );
21
  }
22
}
23

24
const server = new ApolloServer({
25
  typeDefs,
26
  resolvers,
27
  context: ({ req: ExpressRequest }) => {
28
    return {
29
      token: getTokenFromRequest(req),
30
    };
31
  },
32
  dataSources: () => {
33
    return {
34
      moviesAPI: new MoviesAPI(),
35
    };
36
  },
37
});
38

39
await server.listen();

Below is how you write the same code in Apollo Server 4.

1
import { RESTDataSource, AugmentedRequest } from '@apollo/datasource-rest';
2
// KeyValueCache is the type of Apollo server's default cache
3
import type { KeyValueCache } from '@apollo/utils.keyvaluecache';
4
import { ApolloServer } from '@apollo/server';
5
import { startStandaloneServer } from '@apollo/server/standalone';
6

7
 class MoviesAPI extends RESTDataSource {
8
  override baseURL = 'https://movies-api.example.com/';
9
  private token: string;
10

11
  constructor(options: { token: string; cache: KeyValueCache }) {
12
    super(options); // this sends our server's `cache` through
13
    this.token = options.token;
14
  }
15

16
  override willSendRequest(path: string, request: AugmentedRequest) {
17
    request.headers.authorization = this.token;
18
  }
19

20
  async getMovie(id: string): Promise<Movie> {
21
    return this.get<Movie>(`movies/${encodeURIComponent(id)}`);
22
  }
23

24
  async updateMovie(movie: Movie): Promise<Movie> {
25
    return this.patch(
26
      'movies',
27
      // Note the way we pass request bodies has also changed!
28
       { body: { id: movie.id, movie } },
29
    );
30
  }
31
}
32
interface ContextValue {
33
  token: string;
34
  dataSources: {
35
    moviesAPI: MoviesAPI;
36
  };
37
}
38

39
const server = new ApolloServer<ContextValue>({
40
  typeDefs,
41
  resolvers,
42
});
43

44
const { url } = await startStandaloneServer(server, {
45
  context: async ({ req }) => {
46
    const token = getTokenFromRequest(req);
47
    const { cache } = server;
48
    return {
49
      token,
50
      dataSources: {
51
        moviesAPI: new MoviesAPI({ cache, token }),
52
      },
53
    };
54
  },
55
});
56

57
console.log(`🚀  Server ready at ${url}`);

1
import { RESTDataSource } from '@apollo/datasource-rest';
2
// KeyValueCache is the type of Apollo server's default cache
3

4
import { ApolloServer } from '@apollo/server';
5
import { startStandaloneServer } from '@apollo/server/standalone';
6

7
 class MoviesAPI extends RESTDataSource {
8
  baseURL = 'https://movies-api.example.com/';
9

10
  constructor(options) {
11
    super(options); // this sends our server's `cache` through
12
    this.token = options.token;
13
  }
14

15
  willSendRequest(path, request) {
16
    request.headers.authorization = this.token;
17
  }
18

19
  async getMovie(id) {
20
    return this.get(`movies/${encodeURIComponent(id)}`);
21
  }
22

23
  async updateMovie(movie) {
24
    return this.patch(
25
      'movies',
26
      // Note the way we pass request bodies has also changed!
27
       { body: { id: movie.id, movie } },
28
    );
29
  }
30
}
31

32
const server = new ApolloServer({
33
  typeDefs,
34
  resolvers,
35
});
36

37
const { url } = await startStandaloneServer(server, {
38
  context: async ({ req }) => {
39
    const token = getTokenFromRequest(req);
40
    const { cache } = server;
41
    return {
42
      token,
43
      dataSources: {
44
        moviesAPI: new MoviesAPI({ cache, token }),
45
      },
46
    };
47
  },
48
});
49

50
console.log(`🚀  Server ready at ${url}`);

If you want to access your entire context's value within your DataSource, you can do so by making your context value a class (enabling it to refer to itself via this in its constructor):

1
 import { RESTDataSource, WillSendRequestOptions } from '@apollo/datasource-rest';
2
import { KeyValueCache } from '@apollo/utils.keyvaluecache';
3
import { ApolloServer } from '@apollo/server';
4
import { startStandaloneServer } from '@apollo/server/standalone';
5
import { IncomingMessage } from 'http';
6

7
class MoviesAPI extends RESTDataSource {
8
  override baseURL = 'https://movies-api.example.com/';
9
  private contextValue: ContextValue;
10

11
  constructor(options: { contextValue: ContextValue; cache: KeyValueCache }) {
12
    super(options); // this should send `cache` through
13
    this.contextValue = options.contextValue;
14
  }
15

16
  override willSendRequest(path: string, request: WillSendRequestOptions) {
17
    request.headers['authorization'] = this.contextValue.token;
18
  }
19

20
  async getMovie(id): Promise<Movie> {
21
    return this.get<Movie>(`movies/${encodeURIComponent(id)}`);
22
  }
23
}
24

25
class ContextValue {
26
  public token: string;
27
  public dataSources: {
28
    moviesAPI: MoviesAPI;
29
  };
30

31
  constructor({ req, server }: { req: IncomingMessage; server: ApolloServer<ContextValue> }) {
32
    this.token = getTokenFromRequest(req);
33
    const { cache } = server;
34
    this.dataSources = {
35
      moviesAPI: new MoviesAPI({ cache, contextValue: this }),
36
    };
37
  }
38
}
39

40
const server = new ApolloServer<ContextValue>({
41
  typeDefs,
42
  resolvers,
43
});
44

45
await startStandaloneServer(server, {
46
   context: async ({ req }) => new ContextValue({ req, server }),
47
});

1
 import { RESTDataSource } from '@apollo/datasource-rest';
2

3
import { ApolloServer } from '@apollo/server';
4
import { startStandaloneServer } from '@apollo/server/standalone';
5

6
class MoviesAPI extends RESTDataSource {
7
  baseURL = 'https://movies-api.example.com/';
8

9
  constructor(options) {
10
    super(options); // this should send `cache` through
11
    this.contextValue = options.contextValue;
12
  }
13

14
  willSendRequest(path, request) {
15
    request.headers['authorization'] = this.contextValue.token;
16
  }
17

18
  async getMovie(id) {
19
    return this.get(`movies/${encodeURIComponent(id)}`);
20
  }
21
}
22

23
class ContextValue {
24
  constructor({ req, server }) {
25
    this.token = getTokenFromRequest(req);
26
    const { cache } = server;
27
    this.dataSources = {
28
      moviesAPI: new MoviesAPI({ cache, contextValue: this }),
29
    };
30
  }
31
}
32

33
const server = new ApolloServer({
34
  typeDefs,
35
  resolvers,
36
});
37

38
await startStandaloneServer(server, {
39
   context: async ({ req }) => new ContextValue({ req, server }),
40
});

If you want to migrate quickly to Apollo Server 4 without altering your data sources, the snippet below replicates Apollo Server 3's dataSources behavior with a custom plugin.

1
import { ApolloServerPlugin, BaseContext } from "@apollo/server";
2
import type { DataSource } from "apollo-datasource";
3

4
type DataSources = Record<string, DataSource>;
5
type DataSourcesFn = () => DataSources;
6

7
interface ContextWithDataSources extends BaseContext {
8
  dataSources?: DataSources;
9
}
10

11
export const ApolloDataSources = (options: {
12
  dataSources: DataSourcesFn,
13
}): ApolloServerPlugin<ContextWithDataSources> => ({
14
  requestDidStart: async (requestContext) => {
15
    const dataSources = options.dataSources();
16
    const initializers = Object.values(dataSources).map(async (dataSource) => {
17
      if (dataSource.initialize)
18
        dataSource.initialize({
19
          cache: requestContext.cache,
20
          context: requestContext.contextValue,
21
        });
22
    });
23

24
    await Promise.all(initializers);
25

26
    requestContext.contextValue.dataSources = dataSources;
27
  },
28
});
29

30
const server = new ApolloServer({
31
  schema,
32
  plugins: [ApolloDataSources({ dataSources })],
33
});

We include this as a short-term fix and encourage you to create custom data source classes best suited for each source.

modules

In Apollo Server 3, there are several ways to provide your ApolloServer instance with a schema. One of the most common ways is to provide typeDefs and resolvers options (each of which can optionally be an array). Another way is using the modules option with an array of objects, each object containing typeDefs and resolvers keys. Under the hood, these two options use entirely different logic to do the same thing.

To simplify its API, Apollo Server 4 removes the modules constructor option. You can replace any previous usage of modules with the following syntax:

1
new ApolloServer({
2
  typeDefs: modules.map({ typeDefs } => typeDefs),
3
  resolvers: modules.map({ resolvers } => resolvers),
4
})

Additionally, the corresponding GraphQLSchemaModule TypeScript type is no longer exported.

mocks and mockEntireSchema

In Apollo Server 3, the mocks and mockEntireSchema constructor options enable Apollo Server to return simulated data for GraphQL operations based on your server's schema. Under the hood, Apollo Server 3's mocking functionality is provided via an outdated version of the @graphql-tools/mocks library.

Apollo Server 4 removes both the mocks and mockEntireSchema constructor options. You can instead directly incorporate the @graphql-tools/mock package into your app, enabling you to get the most up-to-date mocking features. For more details on configuring mocks, see the @graphql-tools/mocks docs.

The following examples compare the mocks and mockEntireSchema constructor options in Apollo Server 3 on the left and a replacement using @graphql-tools/mock on the right. You can also incrementally apply these changes in Apollo Server 3 without affecting behavior.

new ApolloServer({
  mocks: true,
});

import { addMocksToSchema } from '@graphql-tools/mock';
import { makeExecutableSchema } from '@graphql-tools/schema';

new ApolloServer({
  schema: addMocksToSchema({
    schema: makeExecutableSchema({ typeDefs, resolvers }),
  }),
});

const mocks = {
  Int: () => 6,
};

new ApolloServer({
  mocks,
});

import { addMocksToSchema } from '@graphql-tools/mock';
import { makeExecutableSchema } from '@graphql-tools/schema';

const mocks = {
  Int: () => 6,
};

new ApolloServer({
  schema: addMocksToSchema({
    schema: makeExecutableSchema({ typeDefs, resolvers }),
    mocks,
  }),
});

const mocks = {
  Int: () => 6,
};
new ApolloServer({
  mocks,
  mockEntireSchema: false,
});

import { addMocksToSchema } from '@graphql-tools/mock';
import { makeExecutableSchema } from '@graphql-tools/schema';

const mocks = {
  Int: () => 6,
};
new ApolloServer({
  schema: addMocksToSchema({
    schema: makeExecutableSchema({ typeDefs, resolvers }),
    mocks,
    preserveResolvers: true,
  }),
});

debug

In Apollo Server 3, the debug constructor option (which defaults to true unless the NODE_ENV environment variable is either production or test) controls several unrelated aspects of Apollo Server:

• If debug is true, GraphQL responses with errors include stack traces.
• If debug is true and ApolloServer uses the default logger, Apollo Server prints all DEBUG log-level messages.
  • Apollo Server 3 rarely sends messages at the DEBUG level, so this primarily affects plugins that use the provided logger to send DEBUG messages.
• The debug flag is also available to plugins on GraphQLRequestContext to use as they wish.

Apollo Server 4 removes the debug constructor option. In its place is a new includeStacktraceInErrorResponses option which controls its namesake feature. Like debug, this option defaults to true unless the NODE_ENV environment variable is either production or test.

If you use debug in Apollo Server 3, you can use includeStacktraceInErrorResponses with the same value in Apollo Server 4:

1
const apolloServerInstance = new ApolloServer<MyContext>({
2
  typeDefs,
3
  resolvers,
4
  includeStacktraceInErrorResponses: true,
5
});

Additionally, if your app or a plugin uses DEBUG-level log messages and your server doesn't use a custom logger, you are responsible for setting the default log level. For example, you can use the same Logger implementation that Apollo Server uses by default:

1
import loglevel from 'loglevel';
2

3
const logger = loglevel.getLogger('apollo-server');
4
logger.setLevel(shouldShowDebugMessages ? loglevel.levels.DEBUG : loglevel.levels.INFO);
5
const server = new ApolloServer({
6
  logger,
7
  // ...
8
});

(Note that the stack traces themselves have moved from extensions.exception.stacktrace to extensions.stacktrace.)

formatResponse hook

Apollo Server 3 provides the formatResponse hook as a top-level constructor argument. The formatResponse hook is called after an operation successfully gets to the "execution" stage, enabling you to transform the structure of GraphQL response objects before sending them to a client.

The formatResponse hook receives a successful operation's response and requestContext (containing an unset response field). If the formatResponse hook returns a non-null GraphQLResponse, it uses that response instead of the initially received response argument.

Apollo Server 4 removes the formatResponse hook. We instead recommend using the willSendResponse plugin hook, which enables you to do everything you previously did with formatResponse. The willSendResponse plugin hook receives an operation's requestContext, which has a response field containing a GraphQLResponse object. Note that the willSendResponse hook is allowed to mutate the requestContext.response field.

Apollo Server calls the willSendResponse plugin hook for all requests that get far enough along to invoke requestDidStart (i.e., requests with a parsable JSON body, etc. ). This means that Apollo Server calls the willSendResponse hook in more contexts than the previous formatResponse hook.

To only use willSendResponse after an operation's "execution" stage (i.e., like the previous formatResponse hook), you can make a filter checking for the existence of a data field in the result. If an operation has a data field in the result, it has made it to the execution phase. Note, there are some edge cases: for example, an error in the coercion of variable values calls formatResponse but doesn't have data in the result. If differentiating these edge cases is important to you, please open an issue, and we'll help.

For example, if your Apollo Server 3 code used formatResponse like this:

1
new ApolloServer({
2
  typeDefs,
3
  resolvers,
4
  formatResponse({ response, requestContext }) {
5
    return {
6
      ...response,
7
      extensions: {
8
        ...(response.extensions),
9
        hello: 'world',
10
      },
11
    },
12
  },
13
}),

your Apollo Server 4 code can use willSendResponse, like so:

1
new ApolloServer<MyContext>({
2
  typeDefs,
3
  resolvers,
4
  plugins: [
5
    {
6
      async requestDidStart() {
7
        return {
8
          async willSendResponse(requestContext) {
9
            const { response } = requestContext;
10
            // Augment response with an extension, as long as the operation
11
            // actually executed. (The `kind` check allows you to handle
12
            // incremental delivery responses specially.)
13
            if (response.body.kind === 'single' && 'data' in response.body.singleResult) {
14
              response.body.singleResult.extensions = {
15
                ...response.body.singleResult.extensions,
16
                hello: 'world',
17
              };
18
            }
19
          },
20
        };
21
      },
22
    },
23
  ],
24
});