API Reference: startStandaloneServer

This API reference documents the startStandaloneServer function.

Overview

This startStandaloneServer function helps you get started with Apollo Server quickly. This function is recommended for all projects that don't require serverless support or a particular Node.js framework (such as Fastify). Under the hood, the startStandaloneServer function uses Apollo Server 4's Express integration (i.e., expressMiddleware).

Because it sets helpful defaults, this function is less configurable than other Apollo Server integrations. Complex projects might eventually need to swap to using expressMiddleware (this process is straightforward).

`startStandaloneServer`

The startStandaloneServer function accepts two arguments. The first required argument is the instance of ApolloServer to begin listening for incoming requests:

1
import { ApolloServer } from '@apollo/server';
2
import { startStandaloneServer } from '@apollo/server/standalone';
3

4
const server = new ApolloServer({ typeDefs, resolvers });
5

6
// `startStandaloneServer` returns a `Promise` with the
7
// the URL that the server is listening on.
8
const { url } = await startStandaloneServer(server);

1
import { ApolloServer } from '@apollo/server';
2
import { startStandaloneServer } from '@apollo/server/standalone';
3

4
const server = new ApolloServer({ typeDefs, resolvers });
5

6
// `startStandaloneServer` returns a `Promise` with the
7
// the URL that the server is listening on.
8
const { url } = await startStandaloneServer(server);

The startStandaloneServer function's second optional argument is an object for configuring your server's options, which can contain the following properties:

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 `http.IncomingMessage` and `http.ServerResponse` types.
`listen` `Object`	An optional `listen` configuration object. The `listen` option accepts an object with the same properties as the `net.Server.listen` options object. If no `port` is specified, this defaults to using `{port: 4000}`.

Example

Below is a full example of setting up startStandaloneServer:

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
async function startApolloServer() {
11
  const server = new ApolloServer<MyContext>({ typeDefs, resolvers });
12
  const { url } = await startStandaloneServer(server, {
13
    context: async ({ req }) => ({ token: req.headers.token }),
14
    listen: { port: 4000 },
15
  });
16
  console.log(`🚀  Server ready at ${url}`);
17
}

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
async function startApolloServer() {
7
  const server = new ApolloServer({ typeDefs, resolvers });
8
  const { url } = await startStandaloneServer(server, {
9
    context: async ({ req }) => ({ token: req.headers.token }),
10
    listen: { port: 4000 },
11
  });
12

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

Swapping to `expressMiddleware`

The startStandaloneServer function is not right for every use case, particularly if you need to customize your server's behavior. For example, you might want to customize your CORS behavior, run some middleware before processing GraphQL requests, or serve other endpoints from the same server.

In these cases, we recommend you swap out startStandaloneServer for expressMiddleware (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 (startStandaloneServer uses expressMiddleware 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 Promises and async functions), but backward incompatible changes to the framework are rarer than in newer libraries.

Example

Let's say our current startStandaloneServer setup uses the following code:

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

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

9
async function startApolloServer() {
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}`);
16
}

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

5
async function startApolloServer() {
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

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

To swap to using expressMiddleware, you'll first need to install the following packages so you'll be able to set up HTTP body parsing and CORS for your server:

1
npm install express cors body-parser

Next, we can modify our code to match the following:

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
    cors<cors.CorsRequest>(),
37
    bodyParser.json(),
38
    // expressMiddleware accepts the same arguments:
39
    // an Apollo Server instance and optional configuration options
40
    expressMiddleware(server, {
41
      context: async ({ req }) => ({ token: req.headers.token }),
42
    }),
43
  );
44

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

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
  console.log(`🚀 Server ready at http://localhost:4000/`);
46
}

Edit on GitHub

ApolloServer

expressMiddleware

API Reference: startStandaloneServer

Overview

`startStandaloneServer`

Options

`context`

`listen`

Example

Swapping to `expressMiddleware`

Example