Apollo Client Browser Devtools
This repository contains the Apollo Client Browser Devtools extension for Chrome & Firefox.
The Apollo Client Browser Devtools appear as an "Apollo" tab in your web browser inspector, alongside other tabs like "Elements" and "Console". The devtools currently have four main features:
- GraphiQL: Send queries to your server through your web applications configured Apollo Client instance, or query the Apollo Client cache to see what data is loaded.
- Watched query inspector: View active queries, variables, cached results, and re-run individual queries.
- Mutation inspector: View fired mutations, variables, and re-run individual mutations.
- Cache inspector: Visualize the Apollo Client cache and search through it by field names and/or values.
Apollo Client version support
if you are using an older version of Apollo Client and have issues with our Client Browser Devtools we recommend you upgrade to the latest version of Apollo Client.
- We provide active support for the current minor release of Apollo Client for use with our Client Browser DevTools.
- We do our best to support older
3.xversions of Apollo Client for use with our Client Browser DevTools.
- We do not offer support of
2.xversions of Apollo Client for use with our Client Browser DevTools.
While your application is in dev mode, the devtools will appear as an "Apollo" tab in your web browser inspector. To enable the devtools for your application in production, pass
connectToDevTools: true to the ApolloClient constructor in your application. Pass
connectToDevTools: false if want to manually disable this functionality.
The "Apollo" tab will appear in your web browser inspector if a global
window.__APOLLO_CLIENT__ object exists in your application. Apollo Client adds this hook to the window automatically unless
process.env.NODE_ENV === 'production'. If you would like to use the devtools in production, manually attach your Apollo Client instance to
window.__APOLLO_CLIENT__ or pass
connectToDevTools: true to the constructor.
If you are seeing the "Apollo" tab but are still having issues, skip ahead to the Debugging section.
After cloning this repo, install the required packages:
cd apollo-client-devtools npm install
Running the sample application
We provide a sample application to run when developing and testing the extension. To run it, install the required dependencies for both the client and server:
npm run install:dev
Then start the application:
npm run start:dev
localhost:3000 to view the application. To view the API schema, navigate to
Development with web-ext & WebExtWebpackPlugin
To develop with Firefox, run the following command:
npm run firefox
For Chrome, run the following command:
npm run chrome
Running either of these commands will:
- Build and bundle the extension and application
webpack --watchto watch source files for changes
- Install the extension in the browser
- Open the targeted browser window to
localhost:3000(the sample application)
- Rebuild and reload the extension when the source files are changed
Note that even though the extension is rebuilt and reloaded, a hard refresh is still required. Hot reloading is not an option for web extensions.
Defaults can be found and modified in the WebExtPlugin. You might want to do so if you'd like the targeted browser to open to a different address or to turn on
To run tests for both
development, run the following command:
npm run test
You can also run with
--watch to watch and re-run tests automatically:
npm run test:watch
There are two main pieces of the Apollo Client Browser Devtools: the extension itself and a React application. The extension is the code that communicates with the browser. It allows us to search an inspected window for an instance of Apollo Client and to create the Apollo tab in the browser's devtools panel. The React application powers the experience in the devtools panel.
The devtools folder structure mirrors this architecture. The source code for the extension can be found in
src/extension. The React application code can be found in
For builds, we use the
build folder. After a build, all of the files needed to run the devtools can be found here. If these files are bundled for development, source maps are provided. When these files are bundled for production, source maps are not provided and the code is minified. We use the
dist folder for distributable zip files.
The Apollo Client Devtools project is split up by Screens. In the navigation of the Apollo Client Devtools you can select from Explorer, Queries, Mutations and Cache. Each of these Screens has their own React component and is wrapped in a Layout component.
The Explorer is an Embedded iframe that renders Apollo Studio's Explorer. The Explorer accepts post messages from the dev tools to populate the schema and to communicate network requests and responses. All network requests are done in this app via the parent page's Apollo Client instance. Documentation for all of the configurable properties of the Embedded Explorer can be found in the studio docs.
Communication between client & tab
hook.ts is where we hook into the Apollo Client instance of the parent page and execute operations. In
initializeHook we set up a communication between the client page and the Apollo Client Devtools tab via an instance of
Relay.ts using postMessage. The hook sends the tab information from the parent page, such as the queries, mutations & the cache info on this page (from the Apollo Client instance), responses that come back from Devtools-triggered network requests, and when the page is reloading.
tabRelay.ts is injected into each tab via script tag. Any communication that needs to go from the client to the Apollo Client Devtools need to be forwarded in
devtools.ts is the file where all Apollo Client Devtools communication happens. In this file, network communications for executed operations are forwarded to the Explorer. This is also the file where incoming client messages about the tab state are handled & acted on. Any communication that needs to go from the Apollo Client Devtools to the client needs to be forwarded in
explorerRelay.ts is a file with a bunch of exported functions that are specific to the Explorer network communications for executed operations.
devtools.ts uses the functions as callbacks for its incoming messages, and
Explorer.tsx uses the functions to dispatch network requests & accept responses to display in the embedded Explorer.
Explorer network communication
When requests are triggered by the user from Explorer,
explorerRelay.ts dispatches an
EXPLORER_REQUEST event which is picked up in
devtools.ts and forwarded to the client. In
EXPLORER_REQUEST message is listened for, and an operation is executed. When a response for this network request is recieved by the client,
EXPLORER_RESPONSE is sent to the tab by the client in
hook.ts. This message is forwarded in
tabRelay.ts to the devtools, which calls
sendResponseToExplorer which is picked up by
receiveExplorerResponses called in
If there is an error in the devtools panel, you can inspect it just like you would inspect a normal webpage.
In Chrome, detach the inspector console from the window (if it's not already detached) by clicking the button with three vertical dots in the upper right corner of the console and selecting the detach option. With the detached console in focus, press
opt-cmd-I again to open an inspector for the detached console (inspector inception). In this new inspector you will be able to inspect elements in the first inspector, including the devtools panel.
In Firefox, go to
about:debugging, click on
This Firefox, find the Apollo Devtool extension and click
If you are using Apollo Client 2.0, make sure you are using at least version 2.0.5 of the devtools.
If you are using Apollo Client 3.0, make sure you are using at least version 2.3.5 of the devtools.
If you're seeing an error that's being caused by the devtools, please open an issue on this repository with a detailed explanation of the problem and steps that we can take to replicate the error.
Release process, for those with permission:
- Verify that your changes work as expected by loading the extension as an "unpacked extension" locally for each browser.
- Update the
- Commit changes and tag your version as a github release.
- Publish a new version to npm using
npm publishin the root of the project. We're publishing to npm to allow other projects to have a dependency on devtools.
npm run zipto pack all of the builds for submission.
- Create a new release in the Chrome/Firefox web stores (following the instructions for each browser in the sections below), uploading the zip bundle.
- In your Chrome URL bar, go to:
- Click on
- Add the
- The add-on should now be installed.
Submit for review
- Login to the Chrome webstore and access the Developer Dashboard.
- Select the
Apollo Client Devtoolsextension to update.
- Click on
Upload new package.
- Select the
./dist/chrome.zipfile for upload.
- Click on "Submit for review".
- In your Firefox URL bar, go to:
- Click on
Load Temporary Add-on.
- Add the
- The add-on should now be installed.
Submit for review
- Login to the Firefox developer hub (user/pass is in our shared password system as "Firefox Developer Account").
- Once logged in, click on the Apollo Client Developer Tools "Edit Product Page" link.
- Click on the "Upload New Version" link in the top left side menu.
- Agree to any new Firefox distribution agreements or policies that might show up.
- When the "Submit a New Version" page shows, click on the file upload button in the "Upload Version" section (keeping "Firefox" as the only option checked in the compatible application section).
- Choose the
apollo-client-devtools/dist/apollo_client_developer_tools-X.X.X.zipfor upload and submit. NOTE: when uploading to Firefox, you also must include the source code. A zipped version of the
apollo-client-devtoolsrepo with the built files, node_modules, tests & development folder deleted will do
- After the file has been validated, continue with the submission.
Code of Conduct
This project is governed by the Apollo Code of Conduct.
Who is Apollo?
Apollo builds open-source software and a graph platform to unify GraphQL across your apps and services. We help you ship faster with:
- Apollo Studio – A free, end-to-end platform for managing your GraphQL lifecycle. Track your GraphQL schemas in a hosted registry to create a source of truth for everything in your graph. Studio provides an IDE (Apollo Explorer) so you can explore data, collaborate on queries, observe usage, and safely make schema changes.
- Apollo Federation – The industry-standard open architecture for building a distributed graph. Use Apollo’s gateway to compose a unified graph from multiple subgraphs, determine a query plan, and route requests across your services.
- Apollo Client – The most popular GraphQL client for the web. Apollo also builds and maintains Apollo iOS and Apollo Android.
Learn how to build with Apollo
Check out the Odyssey learning platform, the perfect place to start your GraphQL journey with videos and interactive code challenges. Join the Apollo Community to interact with and get technical help from the GraphQL community.