Choosing an Apollo Server package
Use the right package for your project
Apollo Server 3 has been released, but is not yet installed by default. To install Apollo Server 3, specify
@3.x
after the name of the Apollo Server package you are installing (for example,npm install apollo-server@3.x
).
Apollo Server is distributed as a collection of different packages for different environments and web frameworks. You can choose which package to use based on your project.
Which package should I use?
In most cases, you should get started with the "batteries-included" apollo-server
package.
If your project has specific requirements, we recommend choosing a package based on this flowchart:
After you choose a package, see its basic usage.
All supported packages
Name | Description |
---|---|
|
This "batteries-included" package helps you get started quickly. Recommended for all projects that don't require serverless support or a particular Node.js framework (such as hapi). Because it sets helpful defaults, this library is also less configurable than other Apollo Server libraries. Complex projects might eventually need to swap it out for |
|
This library enables you to attach Apollo Server to an Express server. The |
Serverless-specific packages |
The following libraries are available for running in a particular serverless environment:
Use each of these libraries if and only if you're running your server in the corresponding service. |
Framework-specific packages |
The following libraries are available for integrating Apollo Server with a particular Node.js framework:
Use each of these libraries if and only if you're integrating with the corresponding framework. |
Swapping out apollo-server
After you get up and running with the "batteries-included" apollo-server
package, you might want to configure its HTTP behavior in ways that this package doesn't support. For example, you might want to run some middleware before processing GraphQL requests, or you might want to serve other endpoints from the same server.
In this case, we recommend you swap out apollo-server
for apollo-server-express
(unless you are confident that you want to use a different Node.js framework). This change requires only a few lines and has a minimal effect on your server's existing behavior (apollo-server
uses apollo-server-express
under the hood).
We recommend Express because it's the most popular Node.js web framework, and it integrates well with many other popular libraries. It does have its limitations (for example, Express async support is not built around
Promise
s andasync
functions), but backward incompatible changes to the framework are rarer than in newer libraries.
Example
Let's say our apollo-server
implementation uses the following code:
import { ApolloServer } from 'apollo-server';
async function startApolloServer(typeDefs, resolvers) {
const server = new ApolloServer({ typeDefs, resolvers });
const { url } = await server.listen();
console.log(`๐ Server ready at ${url}`);
}
To swap this out for apollo-server-express
, we first install the following required packages:
npm install apollo-server-express@3.x express graphql
We can (and should) also uninstall apollo-server
.
Next, we can modify our code to match the following:
import { ApolloServer } from 'apollo-server-express';
import express from 'express';
async function startApolloServer(typeDefs, resolvers) {
// Same ApolloServer initialization as before
const server = new ApolloServer({ typeDefs, resolvers });
// Required logic for integrating with Express
await server.start();
const app = express();
server.applyMiddleware({
app,
// By default, apollo-server hosts its GraphQL endpoint at the
// server root. However, *other* Apollo Server packages host it at
// /graphql. Optionally provide this to match apollo-server.
path: '/'
});
// Modified server startup
await new Promise(resolve => app.listen({ port: 4000 }, resolve));
console.log(`๐ Server ready at http://localhost:4000${server.graphqlPath}`);
}
Handling server shutdown
The apollo-server
package does provide one feature that isn't straightforward to implement with other packages: because apollo-server
handles making its HTTP server listen for requests, its stop
method handles stopping the HTTP server. This means it can make sure to stop accepting new requests before it begins to shut down the machinery that processes GraphQL operations.
If you want this behavior in another package, you need to make sure to stop your web server before calling stop()
on your ApolloServer
instance. This can be challenging if stop
is being called due to the signal handlers that Apollo Server installs by default.
We intend to improve this behavior discrepancy, as described in this GitHub issue.
Package conventions
Each Apollo Server package exports an ApolloServer
class. The APIs for these classes are similar but not identical.
All Apollo Server packages depend on apollo-server-core
, which contains the code that's shared by all integrations. Certain symbols, such as built-in plugins, are imported directly from apollo-server-core
instead of from a particular package.
All Apollo Server packages (and apollo-server-core
) are published to npm with the same version number, even if certain packages have no changes for a particular version. This makes it more straightforward to discuss a particular version of Apollo Server without needing to specify a package name.
Certain support libraries (such as apollo-server-caching
, apollo-server-types
, and apollo-server-plugin-base
) use their own versioning and are published only when they change or one of their dependencies changes.
Common options
Most Apollo Server packages require calling a method named applyMiddleware
, getMiddleware
, or createHandler
(depending on the package). These methods accept a (mostly) common set of options (not every package accepts every option).
For descriptions of these options, see the API reference.
The set of common options supported by each package is listed under Basic usage.
Basic usage
The sections below demonstrate how to initialize an ApolloServer
instance with each package. More details are available in each package's README.
Each section also lists the options supported by each package's applyMiddleware
or getMiddleware
or createHandler
function. Learn more about how these options work in the ApolloServer
API reference.
apollo-server
apollo-server
is the "batteries-included" Apollo Server package. It enables you to spin up a GraphQL server without thinking about web frameworks or URLs or middleware, and its main entry point (listen
) is an async
function instead of a callback-based function.
npm install apollo-server@3.x graphql
import { ApolloServer } from 'apollo-server';
async function startApolloServer(typeDefs, resolvers) {
const server = new ApolloServer({ typeDefs, resolvers });
const { url } = await server.listen();
console.log(`๐ Server ready at ${url}`);
}
Although apollo-server
helps you get started quickly, you can't configure its behavior as much as you can other Apollo Server packages. For example, you can't serve other endpoints from the same HTTP server.
If you want to do something with your server that isn't supported by apollo-server
, you can swap to apollo-server-express
.
apollo-server-express
apollo-server-express
is the Apollo Server package for Express, the most popular Node.js web framework. It enables you to attach a GraphQL server to an existing Express server.
apollo-server
uses apollo-server-express
under the hood. If you start with apollo-server
and later need to modify how it serves over HTTP, you can swap apollo-server
to apollo-server-express
.
The following example is roughly equivalent to the apollo-server
example above.
npm install apollo-server-express@3.x express graphql
import { ApolloServer } from 'apollo-server-express';
import express from 'express';
async function startApolloServer(typeDefs, resolvers) {
const server = new ApolloServer({ typeDefs, resolvers });
await server.start();
const app = express();
server.applyMiddleware({ app });
await new Promise(resolve => app.listen({ port: 4000 }, resolve));
console.log(`๐ Server ready at http://localhost:4000${server.graphqlPath}`);
}
You must await server.start()
before calling server.applyMiddleware
. You can add other middleware to app
before or after calling applyMiddleware
.
You can call server.getMiddleware
instead of server.applyMiddleware
if you want to do something with the middleware function besides apply it directly to your app. (server.applyMiddleware({ app, ...rest })
is shorthand for app.use(server.getMiddleware(rest))
.)
applyMiddleware
(along with getMiddleware
) accepts the following common options:
path
cors
bodyParserConfig
onHealthCheck
disableHealthCheck
apollo-server-fastify
apollo-server-fastify
is the GraphQL server for Fastify, a Node.js web framework. Apollo Server 3 supports Fastify v3.
The following example is roughly equivalent to the apollo-server
example above.
$ npm install apollo-server-fastify@3.x fastify graphql
import { ApolloServer } from 'apollo-server-fastify';
import fastify from 'fastify';
async function startApolloServer(typeDefs, resolvers) {
const server = new ApolloServer({ typeDefs, resolvers });
await server.start();
const app = fastify();
app.register(server.createHandler());
await app.listen(4000);
console.log(`๐ Server ready at http://localhost:4000${server.graphqlPath}`);
}
You must await server.start()
before calling server.createHandler
. You can call other functions on app
before or after calling createHandler
.
createHandler
accepts the following common options:
path
cors
onHealthCheck
disableHealthCheck
apollo-server-hapi
apollo-server-hapi
is the GraphQL server for hapi, a Node.js web framework. Apollo Server 3 is only tested with @hapi/hapi
v20.1.2 and later (the minimum version that supports Node.js 16).
The following example is roughly equivalent to the apollo-server
example above.
$ npm install apollo-server-hapi@3.x @hapi/hapi graphql
import { ApolloServer } from 'apollo-server-hapi';
import Hapi from '@hapi/hapi';
async function startApolloServer(typeDefs, resolvers) {
const server = new ApolloServer({ typeDefs, resolvers });
await server.start();
const app = new Hapi.server({
port: 4000
});
await server.applyMiddleware({
app,
});
await app.start();
}
You must await server.start()
before calling server.applyMiddleware
. You can call other functions on app
before or after calling applyMiddleware
.
applyMiddleware
accepts the following common options:
path
route
cors
onHealthCheck
disableHealthCheck
apollo-server-koa
apollo-server-koa
is the GraphQL server for Koa, a Node.js web framework.
The following example is roughly equivalent to the apollo-server
example above.
$ npm install apollo-server-koa@3.x koa graphql
import { ApolloServer } from 'apollo-server-koa';
import Koa from 'koa';
async function startApolloServer(typeDefs, resolvers) {
const server = new ApolloServer({ typeDefs, resolvers });
await server.start();
const app = new Koa();
server.applyMiddleware({ app });
await new Promise(resolve => app.listen({ port: 4000 }, resolve));
console.log(`๐ Server ready at http://localhost:4000${server.graphqlPath}`);
return { server, app };
}
You must await server.start()
before calling server.applyMiddleware
. You can call other functions on app
before or after calling applyMiddleware
.
You can call server.getMiddleware
instead of server.applyMiddleware
if you want to do something with the middleware function besides apply it directly to your app. (server.applyMiddleware({ app, ...rest })
is shorthand for app.use(server.getMiddleware(rest))
.)
applyMiddleware
(along with getMiddleware
) accepts the following common options:
path
cors
bodyParserConfig
onHealthCheck
disableHealthCheck
apollo-server-micro
apollo-server-micro
is the GraphQL server for Micro, a Node.js web framework.
The following example is roughly equivalent to the apollo-server
example above. You should put this code in a file called index.js
in order for the micro
CLI to find it.
$ npm install apollo-server-micro@3.x micro graphql
import { ApolloServer } from 'apollo-server-micro';
const server = new ApolloServer({ typeDefs, resolvers });
module.exports = server.start().then(() => server.createHandler());
Then run the web server with npx micro
.
createHandler
accepts the following common options:
path
onHealthCheck
disableHealthCheck
.
Note that apollo-server-micro
does not have a built-in way of setting CORS headers.
apollo-server-lambda
apollo-server-lambda
is the GraphQL server for AWS Lambda, Amazon's serverless compute service.
This package is a layer around apollo-server-express
, which uses the @vendia/serverless-express
package to translate Lambda events into Express requests. (This package is not related to the Serverless framework.) It supports API Gateway and ALB.
The following example is roughly equivalent to the apollo-server
example above.
$ npm install apollo-server-lambda@3.x graphql
import { ApolloServer } from 'apollo-server-lambda';
const server = new ApolloServer({ typeDefs, resolvers });
exports.handler = server.createHandler();
For more details on using apollo-server-lambda
, see the documentation on deploying to Lambda.
apollo-server-cloud-functions
apollo-server-cloud-functions
is the GraphQL server for Cloud Functions, Google's serverless compute service.
Because the Cloud Functions Node.js runtime uses Express, apollo-server-cloud-functions
is a layer around apollo-server-express
.
The following example is roughly equivalent to the apollo-server
example above.
$ npm install apollo-server-cloud-functions@3.x graphql
import { ApolloServer } from 'apollo-server-cloud-functions';
const server = new ApolloServer({ typeDefs, resolvers });
exports.handler = server.createHandler();
For more details on using apollo-server-cloud-functions
, see the documentation on deploying to Cloud Functions.
apollo-server-azure-functions
apollo-server-azure-functions
is the GraphQL server for Azure Functions, Microsoft's serverless compute service.
The following example is roughly equivalent to the apollo-server
example above.
$ npm install apollo-server-azure-functions@3.x graphql
import { ApolloServer } from 'apollo-server-azure-functions';
const server = new ApolloServer({ typeDefs, resolvers });
exports.handler = server.createHandler();
For more details on using apollo-server-azure-functions
, see the documentation on deploying to Azure Functions.
apollo-server-cloudflare
apollo-server-cloudflare
is the GraphQL server for Cloudflare Workers. This package is experimental and is not actively supported by Apollo.
For more details on using Apollo Server with Cloudflare Workers, see the Apollo GraphQL Server Quickstart in the Cloudflare Workers documentation.