Docs
Launch GraphOS Studio

API Reference: Landing page plugins


This API reference documents built-in plugins that add a landing page to '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

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, does the following by default:

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

In either case, 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:

import { ApolloServer } from '@apollo/server';
import { ApolloServerPluginLandingPageLocalDefault, ApolloServerPluginLandingPageProductionDefault } from '@apollo/server/plugin/landingPage/default';
const server = new ApolloServer({
typeDefs,
resolvers,
plugins: [
// Install a landing page plugin based on NODE_ENV
process.env.NODE_ENV === 'production'
? ApolloServerPluginLandingPageProductionDefault({
graphRef: 'my-graph-id@my-graph-variant',
footer: false,
})
: ApolloServerPluginLandingPageLocalDefault({ footer: false }),
],
});
import { ApolloServer } from '@apollo/server';
import { ApolloServerPluginLandingPageLocalDefault, ApolloServerPluginLandingPageProductionDefault } from '@apollo/server/plugin/landingPage/default';
const server = new ApolloServer({
typeDefs,
resolvers,
plugins: [
// Install a landing page plugin based on NODE_ENV
process.env.NODE_ENV === 'production'
? ApolloServerPluginLandingPageProductionDefault({
graphRef: 'my-graph-id@my-graph-variant',
footer: false,
})
: ApolloServerPluginLandingPageLocalDefault({ footer: false }),
],
});

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

Default non-production landing page

In non-production environments, 4's landing page is an embedded version of

(served at http://localhost:4000 by default):

Apollo Sandbox

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

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 against your server (or any other reachable server).

Options

Name /
Type
Description
version

string

By default, this plugin uses the latest version of the landing page published to Apollo's CDN. If you'd like to pin the current version, you can specify it here.

The current latest version is available at

.

boolean

If you aren't using the embedded (i.e., you are using {embed: false}), the landing splash page displays a footer that links to the documentation telling you how to configure it. To remove this footer, pass footer: false.

document

string

A (e.g., or ) to populate in the Studio Sandbox Explorer's editor on load.

If you omit this, the Explorer initially loads an example based on your schema.

variables

Record<string, any>

An object containing initial values to populate in the Explorer on load.

If provided, these should apply to the initial you provide in document.

headers

Record<string, string>

An object containing initial HTTP header values to populate in the Explorer on load.

collectionId & operationId

string

The ID of a collection, paired with an ID to populate in the Sandbox on load. You can find these values from a registered in Studio by clicking the ... menu next to an in the Explorer of that and selecting View operation details.

includeCookies

boolean

If true, the embedded Apollo Studio Explorer includes cookies in its requests to your server.

The default value is false, unless the user changes the setting in the Explorer UI.

If you omit this, the Explorer defaults includeCookies to false.

embed

boolean | ApolloServerPluginEmbedded LandingPageLocalConfigOptions

If true or an options object, the landing page renders an embedded version of

at its endpoint URL. This is the default behavior.

If you set this option to false, your server's landing page is a splash page containing a copyable command-line snippet showing how to run via curl alongside a link to .

embed options

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

Name /
Type
Description
runTelemetry

boolean

If false, the embedded Explorer rendered by doesn't initialize error or event tracking.

initialState

Object

An object containing additional display options related to the visual state of the embedded Explorer on page load.

For supported sub, see

.

endpointIsEditable

boolean

By default, the embedded Sandbox has a URL input box that is editable by users.

Set endpointIsEditable to false to prevent users of your instance from changing the endpoint URL.

initialState options

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

Name /
Type
Description
pollForSchemaUpdates

boolean

If true, the embedded Sandbox periodically polls your initialEndpoint for schema updates.

The default value is true.

sharedHeaders

Record<string, string>

Headers that are applied by default to every executed by the embedded Sandbox. Users can disable the application of these headers, but they can't modify their values.

The embedded Sandbox always includes these headers in its queries to your initialEndpoint.

Example:

initialState: {
sharedHeaders: {
authorization: "Bearer abc123";
}
}

Default production landing page

The ApolloServerPluginLandingPageProductionDefault shows a minimalist landing page:

Apollo Server default landing page

This landing page is designed for use in production. It provides a copyable command-line snippet showing how to run 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 your with the

. You can choose to embed the Apollo Explorer on your endpoint if you pass the embed
option
.

Options

Name /
Type
Description
version

string

By default, this plugin uses the latest version of the landing page published to Apollo's CDN. If you'd like to pin the current version, you can specify it here.

The current latest version is available at

.

boolean

By default, the landing page displays a footer that links to the documentation telling you how to configure it. To remove this footer, pass footer: false.

graphRef

string

If provided, the landing page includes a link (with opt-in auto-redirect) to the Apollo Studio page for the with the corresponding

. An example is my-graph@my-variant.

To enable this link, you need to provide graphRef here even if you already provide it elsewhere for usage reporting and other purposes. This is because if your server is publicly accessible, you might not want to display the publicly.

document

string

A (eg, or ) to populate in the Studio Explorer's editor on load.

If you omit this, the Explorer initially loads an example based on your schema.

variables

Record<string, any>

An object containing initial values to populate in the Explorer on load.

If provided, these should apply to the initial you provide in document.

headers

Record<string, string>

An object containing initial HTTP header values to populate in the Explorer on load.

embed

boolean | EmbeddableSandboxOptions

If true or you provide an options object, the landing page renders an embedded version of the

at its endpoint URL. This enables visitors to the endpoint directly and use additional Studio features if signed in with their Apollo account.

To embed the , you must also provide with the graph ref of the Studio to use, usually via the APOLLO_GRAPH_REF environment variable.

The default value is false, in which case the landing page displays a basic curl command.

You can configure the Explorer embedded on your endpoint with display and functional options. For supported options, see

.

collectionId & operationId

string

The ID of a collection, paired with an ID to populate in the Explorer on load. You can find these values from a registered in Studio by clicking the ... menu next to an in the Explorer of that and selecting View operation details.

includeCookies

boolean

A boolean used to set whether Studio Explorer should include cookies in its requests to your server.

If you omit this, the Explorer defaults includeCookies to false.

embed options

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

Name /
Type
Description
displayOptions

Object

An object containing additional display options related to the visual state of the embedded Explorer on page load.

For supported sub, see

.

persistExplorerState

boolean

If true, the embedded Explorer uses localStorage to persist its state (including , tabs, , and headers) between user sessions. This state is automatically populated in the Explorer on page load.

If false, the embedded Explorer loads with an example based on your schema (unless you provide

).

The default value is false.

embed.displayOptions options

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

Name /
Type
Description
docsPanelState

"open" | "closed"

If open, the Explorer's Documentation panel (the left column) is initially expanded. If closed, the panel is initially collapsed.

The default value is open.

showHeadersAndEnvVars

true | false

If true, the embedded Explorer includes the panels for setting request headers and environment variables. If false, those panels are not present.

The default value is true.

theme

"dark" | "light"

If dark, the Explorer's dark theme is used. If light, the light theme is used.

The default value is dark.

runTelemetry

boolean

If false, the embedded Explorer rendered by doesn't initialize error or event tracking.

GraphQL Playground landing page

By default, 2 provided a Playground landing page. For migration purposes, we've published the

package, a Playground plugin compatible with 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 4) at your earliest convenience.

Disabling the landing page

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

import { ApolloServer } from '@apollo/server';
import { ApolloServerPluginLandingPageDisabled } from '@apollo/server/plugin/disabled';
const server = new ApolloServer({
typeDefs,
resolvers,
plugins: [ApolloServerPluginLandingPageDisabled()],
});
import { ApolloServer } from '@apollo/server';
import { ApolloServerPluginLandingPageDisabled } from '@apollo/server/plugin/disabled';
const server = new ApolloServer({
typeDefs,
resolvers,
plugins: [ApolloServerPluginLandingPageDisabled()],
});

This plugin takes no .

Previous
Cache control
Next
Federated subscriptions
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company