GraphQL Voyager: turning an introspection response into an interactive schema graph

The problem GraphQL Voyager solves for schema readers

A GraphQL schema is a graph, but the tools most teams read it with are not. The SDL file is a list of type definitions, and the documentation pane in GraphiQL or Apollo Sandbox shows one type at a time. Answering a question like which types reach User, or what a mutation returns three hops down, means clicking through a sidebar and holding the path in your head.

GraphQL Voyager draws the whole thing at once. The README describes it as a way to "visually explore your GraphQL API as an interactive graph" and says it is useful "when designing or discussing your data model". That is the honest scope: it is a reading and discussion tool, not a code generator and not a test harness. The people who get value from it are the ones who have to explain a schema to someone else, backend engineers in design review, frontend engineers joining a project, and anyone documenting a public API.

The repository also keeps a list of public GraphQL APIs at APIs-guru/graphql-apis, and the hosted demo lets you load them without running anything locally. That is the fastest way to decide whether the rendering style suits you before you wire it into an application.

What Voyager does with an introspection response

The data flow is short and worth stating plainly. Voyager does not parse SDL and it does not talk to your database. It consumes the standard GraphQL introspection response, the JSON object a server returns for the introspection query, and lays it out as a node-link diagram where types are nodes and fields that reference other types are edges.

The React component takes that object through the introspection property. The README notes that if you pass a function instead of an object, Voyager calls it with the introspection query as the first argument and expects a Promise that resolves to the introspection response. That detail matters because it means the fetch happens on your terms: you can attach authentication headers, route through a proxy, or serve a cached response from disk.

Layout is the part Voyager does not own. The repository's topics list graphviz, and the graph is laid out automatically rather than positioned by hand. There is no documented way to pin a node or save a manual arrangement, so two runs against the same schema should look the same but you cannot curate the picture. The displayOptions object is where the real control lives: skipRelay defaults to true and strips Relay wrapper types, skipDeprecated defaults to true and removes deprecated fields along with entities that contain only deprecated fields, rootType lets you pick any type as the root of the graph, sortByAlphabet defaults to false, showLeafFields defaults to true, and hideRoot defaults to false. Those defaults explain the first impression: a Relay-style schema looks much smaller than its SDL suggests until you turn skipRelay off.

Installing GraphQL Voyager and rendering a first graph

The package is published on npm as graphql-voyager. Note the engine constraint in package.json: node >=25.2.0. If your runtime is older, npm will warn or refuse depending on your configuration, so check that before you plan an upgrade around this tool.

The quickest path needs no build step. The README points at jsDelivr, where a pinned version and the latest version of voyager.standalone.js are both available, and notes that the file is bundled with React, so you only need to call renderVoyager. The README also links an HTML example under example/cdn for the full page.

If you would rather keep the browser out of it, the middleware is smaller to wire up. The README gives an Express example that mounts the viewer at /voyager and points it at a GraphQL endpoint, with the server listening on port 3001. The same middleware is exported for Hapi (version 20 and above) and Koa.

import express from 'express';
import { express as voyagerMiddleware } from 'graphql-voyager/middleware';

const app = express();

app.use('/voyager', voyagerMiddleware({ endpointUrl: '/graphql' }));

app.listen(3001);

Middleware accepts endpointUrl, the same displayOptions object described above, and headersJS, a string of serialized headers with a default of "{}". The README notes that headersJS can hold any JS expression that evaluates to an object, and gives { Authorization: localStorage['Meteor.loginToken'] } as an example. That is convenient and also the part to think about: the expression is evaluated in the viewer's context, so anything it can reach is reachable by anyone who can load the page. For a local or internal deployment that is fine. For a public one, the middleware route needs the same access control as the GraphQL endpoint itself.

Where GraphQL Voyager stops being the right tool

Voyager reads a schema. It does not compare two of them. If the question is what changed between the schema on main and the schema in a pull request, Voyager will show you each graph but it will not highlight the difference, and the README documents no diff mode. Teams that need that usually want a schema registry or a snapshot test, not a viewer.

The second limitation is the output. The README documents the on-screen graph, the left panel with per-type details, the Skip Relay option and the ability to choose a root type. It does not document exporting the graph to PNG, SVG or PDF. If your goal is a diagram committed to a repository or pasted into a design document, you will be taking a screenshot, and the automatic layout means that screenshot is whatever the layout engine produced.

The third is the environment. The standalone bundle is JavaScript, and the middleware serves a page. There is no documented offline or headless mode, so anything that has to run in a CI container without a browser is out of scope. Related to that, the whole approach depends on introspection being enabled on the target endpoint. Many production GraphQL servers disable introspection, and Voyager has no fallback for that case; you would need to supply a saved introspection response instead.

Finally, there is the release cadence. The most recent release listed is v2.0.0 from 2023-08-08, while the last push to the repository was on 2026-05-12 and package.json carries version 2.1.0. The repository is not archived, but the gap between published releases and commits is worth noticing if your project depends on a tagged version rather than a git reference.

How Voyager differs from GraphiQL and schema documentation generators

The nearest alternative most teams already have is GraphiQL or a similar IDE, which pairs a query editor with a documentation sidebar. The difference is in the unit of display. GraphiQL shows one type at a time and is built around writing and running queries. Voyager shows the whole type graph at once and cannot run a query at all. If your task is exploring what a field returns for a given argument, the IDE wins; if your task is understanding how types connect, the graph does.

A second alternative is a documentation generator that produces static HTML or Markdown from a schema, in the style of tools that emit a reference page. Those produce something you can commit, review in a diff and host without JavaScript. Voyager produces something you interact with. The trade-off is real in both directions: the static page is diffable and the graph is not, but the static page cannot be re-rooted at an arbitrary type or have Relay wrappers stripped with a toggle.

There is also the manual route, which is what the README credits as the inspiration: graphql-visualizer by NathanRSmith. If you have an existing Graphviz pipeline, Voyager's value is that it does the introspection fetch, the layout and the interaction for you rather than emitting DOT for you to render yourself.

Licence, maintenance and the cost of upgrading

GraphQL Voyager is MIT licensed, stated in both the README and package.json. That is a permissive licence, and it means embedding the viewer in a commercial product does not by itself create an obligation to publish your own source. The usual caveat applies: this is a description of what the licence file says, not legal advice, and if you are redistributing the bundle you should read the LICENSE file in the repository root yourself.

The maintenance picture is mixed and only a narrow claim is supported. The repository is not archived. Its last push was on 2026-05-12. The latest release listed is v2.0.0 from 2023-08-08, and package.json declares version 2.1.0, so work has happened on the main branch without a corresponding tagged release. If you install from npm you are likely getting a published version that predates current main; if you install from git you are tracking a branch.

Upgrade cost is dominated by two things. The Node engine requirement of >=25.2.0 in package.json is a hard floor for building from source, and the package is ESM only ("type": "module" with an exports map that lists import and browser conditions). A CommonJS consumer cannot simply require it. The React component API itself has been stable enough that the v2.0.0 release is the last breaking change listed, but the jump from the 1.x line to 2.x is the one to check in a changelog before upgrading an existing integration.

Editorial conclusion

Adopt GraphQL Voyager if you already have a GraphQL endpoint and want a browsable picture of its types for design reviews or onboarding, either as the pre-bundled voyager.standalone.js file or as Express, Hapi and Koa middleware pointed at endpointUrl. Do not adopt it if you need a committed diagram in CI, a schema diff between branches, or anything that runs without JavaScript in the browser: the README documents no export to PNG or SVG and no offline mode, and the project has not published a release since v2.0.0 in August 2023. Before you commit, check the Node engine constraint in package.json against your runtime, and open the introspection endpoint you intend to point it at to confirm introspection is enabled in production.

Frequently asked questions

Official sources

1. APIs-guru/graphql-voyager on GitHub
2. License: MIT
3. Project website
4. README
5. Releases