API Reference: Landing Page Plugins

This API reference documents built-in plugins that add a landing page to Apollo Server's base URL, enabling visitors to interact with the server from their browser.

This includes plugins for:

• The default landing page for non-production environments (ApolloServerPluginLandingPageLocalDefault)

• The default landing page for production (ApolloServerPluginLandingPageProductionDefault)

• Using GraphQL Playground as a landing page (ApolloServerPluginLandingPageGraphQLPlayground)

• Disabling the landing page entirely

These plugins work by implementing the renderLandingPage plugin event, which serves an HTML page whenever a browser includes an accept: text/html header. Aside from these, you can also create a custom plugin that renders a custom landing page.

Default behavior

If you don't manually install any plugin that implements renderLandingPage, Apollo Server does the following by default:

• In non-production environments (NODE_ENV is not production), Apollo Server installs ApolloServerPluginLandingPageLocalDefault.

• In production environments (NODE_ENV is production), Apollo Server installs ApolloServerPluginLandingPageProductionDefault.

In either case, Apollo Server provides no configuration options to the plugin. You only need to install one of these plugins manually if you want to override its default configuration.

Configuring default landing pages

To configure these default plugins while still using the same NODE_ENV-based logic, import them from @apollo/server/plugin/landingPage/default and pass them to the ApolloServer constructor in the plugins array:

1import { ApolloServer } from '@apollo/server';
2import { ApolloServerPluginLandingPageLocalDefault, ApolloServerPluginLandingPageProductionDefault } from '@apollo/server/plugin/landingPage/default';
3
4const server = new ApolloServer({
5  typeDefs,
6  resolvers,
7  plugins: [
8    // Install a landing page plugin based on NODE_ENV
9    process.env.NODE_ENV === 'production'
10      ? ApolloServerPluginLandingPageProductionDefault({
11          graphRef: 'my-graph-id@my-graph-variant',
12          footer: false,
13        })
14      : ApolloServerPluginLandingPageLocalDefault({ footer: false }),
15  ],
16});
17

Available configuration options are listed in each plugin's reference below.

Default non-production landing page

In non-production environments, Apollo Server 4's landing page is an embedded version of Apollo Sandbox (served at http://localhost:4000 by default):

This landing page is designed for use in local development, where NODE_ENV is not set to production.

Apollo Sandbox is a special mode of Apollo Studio used for local development, which doesn't require an Apollo account. Sandbox includes the Apollo Studio Explorer, a powerful web IDE that enables you to build and run operations against your server (or any other reachable server).

Options

embed options

These are the fields you can include in the embed option you pass to the ApolloServerPluginLandingPageLocalDefault:

initialState options

These are the fields you can include in the initialState option you pass to embed under ApolloServerPluginLandingPageLocalDefault:

1initialState: {
2  sharedHeaders: {
3    authorization: "Bearer abc123";
4  }
5}

Default production landing page

The ApolloServerPluginLandingPageProductionDefault shows a minimalist landing page:

This landing page is designed for use in production. It provides a copyable command-line snippet showing how to run operations with your server. By default, the only visible reference to Apollo is a footer explaining how to customize the page. You can also configure it to add a link to query your graph with the Apollo Explorer. You can choose to embed the Apollo Explorer on your endpoint if you pass the embed option.

Options

embed options

These are the fields you can include in the embed option you pass to the ApolloServerPluginLandingPageProductionDefault:

embed.displayOptions options

These are the fields you can include in the displayOptions option you pass to the embedded Explorer plugin:

GraphQL Playground landing page

By default, Apollo Server 2 provided a GraphQL Playground landing page. For migration purposes, we've published the @apollo/server-plugin-landing-page-graphql-playground package, a GraphQL Playground plugin compatible with Apollo Server 4. However, we aren't supporting this plugin with documentation or security updates since the GraphQL Playground project is officially retired and we do not recommend its continued use. Instead, we recommend migrating to the actively maintained Apollo Sandbox (the default landing page in Apollo Server 4) at your earliest convenience.

Disabling the landing page

The ApolloServerPluginLandingPageDisabled plugin serves no landing page from Apollo Server's base URL. Install it to disable the default landing page in some or all environments:

1import { ApolloServer } from '@apollo/server';
2import { ApolloServerPluginLandingPageDisabled } from '@apollo/server/plugin/disabled';
3
4const server = new ApolloServer({
5  typeDefs,
6  resolvers,
7  plugins: [ApolloServerPluginLandingPageDisabled()],
8});

This plugin takes no arguments.