Apollo Sandbox

Apollo Sandbox is a special mode of Apollo Studio that is meant to be used for local development. Sandbox loads with a schema from introspection as opposed to a schema from the Apollo registry and provides access to a subset of Studio's devtools:

• The Explorer
• Schema reference
• Schema checks and diffs against registered graphs (for logged-in users)

Sandbox can be used offline and without an Apollo account. You can use Sandbox in our hosted environment on Apollo Studio or run it yourself.

Overview video

Connecting to a GraphQL server

When you open Sandbox, it automatically attempts to connect to a GraphQL server running at http://localhost:4000. You can use the box at the top of the Explorer to change this URL to any local or remote GraphQL endpoint that's accessible by your browser:

Publishing schemas from Sandbox

If you're signed in to Sandbox with your Apollo account, you can publish your GraphQL server's schema to a new Studio graph.

To do so, first click Publish at the top of the Explorer. The following dialog appears:

1. Use the dropdown menu to choose an organization for your new graph.
2. Provide a title for your graph.
3. If you've created any Sandbox operation collections, you can copy those over to your new graph by checking the box.
   • This option doesn't appear if you haven't created any Sandbox collections.
4. Click Confirm.

When Sandbox finishes publishing your schema, it redirects you to your new graph in Studio.

Schema diffs

If you log into Apollo Studio, you can diff the schema in your Sandbox against any graph you have access to in the registry.

From Sandbox, open the Schema Diff page from the left navigation panel. Then use the dropdown menus to select any accessible organization, graph, and variant to compare against:

In addition to viewing the diff on this page, you can click Run a Check in the upper-right to run schema checks against the currently selected variant.

Schema checks

If you log into Apollo Studio, you can run a Schema Check between the schema in your Sandbox and a graph you have access to in the Apollo registry.

From Sandbox, open the Checks page from the left navigation panel:

Select any accessible organization, graph, and variant to check against and click Run a check. When the check completes, Sandbox displays a result summary:

To view the result's full details in Studio, click Go to details.

Subgraph checks

You can run subgraph checks on federated graphs. If you're using Sandbox with a subgraph, you can use the subgraph dropdown to select which subgraph you want to check your changes against.

When you click Run a check, Studio first performs a composition check using your local subgraph schema and the registered schemas of your other subgraphs. If composition succeeds, Sandbox then performs operation checks as usual and displays the results of all checks. If composition fails, Sandbox does not perform operation checks and displays the composition error.

Offline Sandbox

You can use Sandbox without an internet connection if you're querying a graph running on localhost. To do so, open Sandbox in your browser at least once while connected to the internet. You can then use that browser to open Sandbox while offline.

Reconnecting

Sandbox automatically reconnects to Apollo Studio whenever your internet connection is restored. When it does, it might display a notification that your Apollo Studio application version is stale by at least 24 hours. You can click the notification to update all of your browser's open Apollo Studio tabs to the latest version.

Operation collections in Sandbox

See this section.

Embedding Sandbox

In addition to using Studio's hosted version of Sandbox, you can also embed Sandbox on your own website. This may be useful for bootstrapping a GraphQL IDE onto a development endpoint or an endpoint with CORS restrictions.

Setup

1. Open Sandbox.

2. Under the Explorer's Settings tab, find Embed Sandbox and click Copy code snippet.

   The following dialog appears:

   

3. Within the dialog, use the tabs to select the code snippet for your use case:

   • Use React for React apps where you can npm install the @apollo/sandbox package.
   • Use JavaScript for non-React JavaScript apps where you can npm install the @apollo/sandbox package.
   • Use Built file on CDN to use Apollo's CDN-hosted embedded Sandbox.

4. Click Copy to copy the snippet, then paste it into your html code.

Options

The EmbeddedSandbox object takes an options object with the following structure (individual options are described below):

1
{
2
  initialEndpoint: 'http://localhost:4000',
3
  handleRequest: (endpointUrl, options) => {
4
    return fetch(endpointUrl, {
5
      ...options,
6
      headers: {
7
          ...options.headers,
8
          authorization: `token ${token}`
9
      },
10
    })
11
  },
12
  includeCookies: false,
13
}

These are the optional options you can include in the object you pass to new EmbeddedSandbox: