graphql-network-inspector: a devtools panel that speaks GraphQL

A network tab that knows what a GraphQL request is

GraphQL Network Inspector is a platform agnostic network inspector built specifically for GraphQL, and the promise in the description is that you can clearly see individual GraphQL requests, including support for query batching. The full documentation is published at overstacked.io/docs/graphql-network-inspector.

The problem it solves is that a GraphQL request over HTTP looks almost exactly like a REST request to a generic network inspector. The body is a JSON object with a query string, a variables object and an operation name, and the response is a JSON object with a data key and an errors key. A generic panel will show you the bytes, which is not what you want when you are trying to find out which field in a query returned null and why.

The extension is distributed for both Chrome and Firefox, through the Chrome Web Store and the Firefox Add-ons site, and the standard install is the browser store listing rather than a build from source.

There is also a test server, a mock GraphQL service on a Heroku URL, that the documentation points at so you can see the panel working against something that does not require your own application to be running. That is a small courtesy with a real effect, because a debugging tool is much easier to evaluate when there is a known baseline to compare against.

Batching, persisted queries and incremental delivery

The feature list is where the GraphQL specifics live, and each item corresponds to a thing a generic inspector handles badly.

Requests are automatically parsed and displayed as GraphQL queries rather than as a JSON string. Query batching is supported, and the important detail is that each query in the batch is displayed individually, which is the difference between seeing one opaque array and seeing the three operations that were actually sent. Persisted queries are supported, which is Automatic Persisted Queries, the technique where the client sends a hash instead of the query text. Incremental delivery is supported through the @defer and @stream directives, so a response that arrives in pieces is reassembled and shown as one result rather than as a stream of fragments.

And requests can be exported to be re-run and shared with graphdev.app, which turns a debugging session into something you can hand to a colleague or attach to a bug report, instead of pasting screenshots of a network tab.

Subscription monitoring is a separate capability with its own transports. GraphQL subscriptions over WebSocket are fully supported, using the graphql-ws protocol, and there is support for subscriptions over Server-Sent Events. The transport is chosen from the operation type filters in the toolbar, which is a sensible design decision, because whether you care about subscription traffic depends on what your application does.

Keyboard shortcuts and the small things that matter while debugging

Three shortcuts are documented, and each of them removes a step from a loop you repeat dozens of times an hour.

Clicking any header copies it to the clipboard, which is the move you make when you want the exact value of a header rather than a reading of it. Double clicking a JWT token header does both jobs, decoding the token and copying it, so you can look at a token and paste it elsewhere without a second trip through a tool. And Cmd or Ctrl plus F opens the full search panel, which is the feature that separates this from a plain network tab once a response is large enough that reading it linearly stops working.

The last one is the reason to prefer a dedicated panel at all. A generic network tab gives you a search box over the raw payload, which finds a string but does not tell you which part of a query it belongs to. Here the thing you are searching over is a parsed request list, so the answer to a question like which of these operations returned an error is one search away.

The panel also shows node statistics style context, in the sense that it presents the operation and the result together, which is what makes the error message legible in context rather than as a string in isolation.

Working on the extension itself, and the mock server

Local development is a yarn workflow. Installing the dependencies is a single command:

yarn

and the development server is another:

yarn start

That starts a development build and, as the documentation puts it, also caches files in the build directory so that you can load the directory as an unpacked extension in your browser. Changes are loaded automatically, with the caveat that you often have to close and reopen the devtools window to see them.

There is a mock GraphQL server in the mock-server directory, used for testing the extension features, and it runs with npm:

cd mock-server
npm install
npm run dev

The mock server has a transport toggle button, which lets you exercise both the WebSocket and the SSE subscription paths from the same fake service. That is a detail that saves a lot of time, because the two transports fail in different ways and a toggle lets you flip between them without a second server.

The extension itself is React with a hooks based architecture, and the source tree is organised by role. The src/hooks/ directory holds the custom hooks that carry the core logic: useNetworkMonitor monitors HTTP and HTTPS GraphQL requests, useGraphqlSubscriptions monitors WebSocket and SSE subscriptions, and useHighlight does syntax highlighting with Web Worker support, so highlighting a large response does not block the panel. The src/containers/ directory holds the main interface components such as the NetworkPanel and the Toolbar, src/components/ holds the reusable pieces, src/helpers/ holds the parsing and formatting utilities, and src/services/ holds the wrappers around the browser extension APIs.

Two browsers means two bundles and a set of scripts

The build is driven by craco rather than plain create-react-app, and the scripts in the manifest show the shape of the release process.

The build script sets REACT_APP_VERSION from the package version and turns off INLINE_RUNTIME_CHUNK, and the bundle scripts then produce a zip per browser. bundle:chrome runs the build, then a script that applies the Chrome specific settings, then packages the output with bestzip. bundle:firefox does the same with a Firefox settings script and zips from inside the build directory. The postbuild hook then sets the manifest version and patches the manifest content script, so the extension reports the right version to the store.

The rest of the toolchain is visible in the tree: craco.config.js for the build overrides, tailwind.config.js and the Tailwind forms plugin for the styling, jest.config.js with jest.setup.ts for the tests, a type check script, a lint script that runs with --max-warnings=0 over the source and the public scripts, and an eject script inherited from create-react-app. The package version is 2.26.1 and the package is marked private, which is normal for an application that is distributed as a browser extension rather than installed from npm.

There is a .serverless/ directory, which points at a serverless deployment for something in the project, most likely the mock service, and a PRIVACY.md at the root, which for an extension that reads page traffic is not optional. The TODO file in the root is also worth a look before you rely on a feature you expect to be there.

When the extension does not load, and where it stops working

The troubleshooting section exists because the extension has a known failure mode with a known fix.

Some users hit an issue where the extension does not load, and the cause may be custom settings in the devtools or a conflict with other extensions. The fix is to open the devtools, go to the settings using the cog icon in the top right, scroll to the bottom of the Preferences tab and click Restore defaults and reload. If the problem persists, the request is to raise an issue with the details of the browser.

That is a sensible answer to a question that has no single answer, because a devtools panel is injected by an extension and can be disabled by a devtools preference that the user forgot about.

The limits of the tool follow from what it is. It is a browser extension, so it sees the traffic of the browser it is installed in, which means it does not cover a native mobile client, a service worker running on a server, or a server to server GraphQL call. It is a GraphQL tool, so an ordinary REST endpoint that returns JSON is not what it is for. And subscription monitoring covers the WebSocket protocol graphql-ws and SSE, so a subscription delivered over another transport is outside what it monitors.

There is a second dimension to consider, which is that a persisted query request may not contain the query text at all. The documentation lists persisted query support as a feature, and the practical consequence is that the panel can only show what the request carried, which for a persisted query is a hash rather than a query. That is not a defect, it is what the protocol sends, but it does change what you can read in the panel.

Editorial conclusion

Adopt graphql-network-inspector if you spend your day reading GraphQL responses in a browser and want the queries parsed, the batches split and the subscription traffic visible instead of scrolling through raw payloads. Do not adopt it to inspect traffic from native apps or from server to server calls, and do not expect it to help with a REST endpoint that happens to return JSON. Verify first that the extension loads in your browser, since a devtools preference or a conflicting extension is the documented cause of a failure to load, and that your transport is covered, because subscriptions are monitored over WebSocket with the graphql-ws protocol or over SSE and nothing else.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. warrenday/graphql-network-inspector on GitHub