Apollo Explorer logo

Backstage Apollo Explorer Plugin

Created by brizzbuzz

Apollo Explorer is a web UI from Apollo that helps you explore and test GraphQL. You can write queries. Browse the schema. See field docs. Inspect responses. Save operations for later. It is a focused workspace for day to day API work.

The Apollo Explorer Backstage plugin brings that experience into your developer portal. It embeds Explorer inside Backstage so your teams can run queries without leaving the portal. The plugin can point at one or many Apollo graphs. It supports authentication through Apollo Studio so access stays aligned with your existing setup. Once signed in, engineers get the same Explorer they know, now in the place they already use for docs and tooling.

Common use cases are straightforward. Triage a bug by querying live data next to your service catalog. Try a new field while reading API docs in the same window. Share a saved operation with a teammate during a review. Help a new hire learn the schema during onboarding. Keep graphs visible to the teams that own them so ownership is clear.

If your org uses GraphQL and Apollo Studio, this plugin cuts context switching. It keeps exploration close to where work happens. It is a simple way to make GraphQL work feel faster and more focused.

Installation Instructions

These instructions apply to self-hosted Backstage only.

Step 1 Get an Apollo graph reference

  • Sign in to Apollo Studio
  • Open your graph
  • Use the Share as Embedded option
  • Copy the graphRef value

You only need graphRef for a basic setup. Keep it ready.

Step 2 Install the plugin in your Backstage app

Run this in the root of your Backstage repo

Copy
yarn --cwd packages/app add @backstage-community/plugin-apollo-explorer

Step 3 Add the page route

Edit packages/app/src/App.tsx

  • Import the page from the plugin
  • Add a route so you can open the explorer
  • Pass your graphRef values
Copy
// packages/app/src/App.tsx
import React from 'react';
import { Route } from 'react-router-dom';
import { FlatRoutes } from '@backstage/core-app-api';
import { ApolloExplorerPage } from '@backstage-community/plugin-apollo-explorer';

export const App = () => (
  <FlatRoutes>
    {/* other routes */}
    <Route
      path="/apollo-explorer"
      element={
        <ApolloExplorerPage
          endpoints={[
            { title: 'Github', graphRef: 'my-github-graph-ref@current' },
            { title: 'Linear', graphRef: 'my-linear-graph-ref@current' },
          ]}
        />
      }
    />
  </FlatRoutes>
);

You can start with a single endpoint if you want

Copy
<ApolloExplorerPage
  endpoints={[
    { title: 'My Graph', graphRef: 'my-graph-ref@current' },
  ]}
/>

Edit packages/app/src/components/Root/Root.tsx

  • Add a SidebarItem that points to the page path you added
  • Use any icon you prefer or none
Copy
// packages/app/src/components/Root/Root.tsx
import React from 'react';
import { SidebarItem } from '@backstage/core-components';

export const Root = () => (
  <>
    {/* your existing sidebar layout */}
    <SidebarItem to="apollo-explorer" text="Apollo Explorer" />
  </>
);

Now you can open Apollo Explorer from the sidebar. The explorer will prompt you to sign in to Apollo Studio if needed.

Step 5 Optional token setup with an ApiRef

If your org issues tokens for Apollo through an internal ApiRef, you can pass a callback that returns a token. The import in this example is a placeholder. Replace it with your real ApiRef.

Copy
// packages/app/src/App.tsx
import React from 'react';
import { Route } from 'react-router-dom';
import { FlatRoutes } from '@backstage/core-app-api';
import { ApolloExplorerPage } from '@backstage-community/plugin-apollo-explorer';
import { ApiHolder } from '@backstage/core-plugin-api';
// Replace with your actual ApiRef and client
import { ssoAuthApiRef } from '@companyxyz/devkit';

async function authCallback(options: { apiHolder: ApiHolder }): Promise<{ token: string }> {
  const sso = options.apiHolder.get<any>(ssoAuthApiRef);
  const token = await sso.getToken();
  return { token };
}

export const App = () => (
  <FlatRoutes>
    <Route
      path="/apollo-explorer"
      element={
        <ApolloExplorerPage
          endpoints={[
            {
              title: 'Github',
              graphRef: 'my-github-graph-ref@current',
              authCallback,
            },
          ]}
        />
      }
    />
  </FlatRoutes>
);

The plugin will call authCallback when it needs a token. Return an object with a token string.

Backend setup

No backend package is required. The plugin runs fully in the frontend. This applies to the legacy backend and the new backend system. You do not need to add any backend module or route.

Changelog

This changelog is produced from commits made to the Apollo Explorer plugin since a year ago, and based on the code located here. It may not contain information about all commits. Releases and version bumps are intentionally omitted. This changelog is generated by AI.

User impact

  • None

Maintenance

  • Remove unused dev dependency canvas #3565 merged 5 months ago
  • Reduce false positives in knip reports by updating repo tools #3018 merged 6 months ago

Set up Backstage in minutes with Roadie