• Stars
    star
    1,481
  • Rank 31,741 (Top 0.7 %)
  • Language
    TypeScript
  • License
    MIT License
  • Created almost 8 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Apollo Client browser developer tools.

Apollo Client

Apollo Client Browser Devtools

Build Status Join the community on Spectrum

Download for Firefox | Download for Chrome

This repository contains the Apollo Client Browser Devtools extension for Chrome & Firefox.

Features

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 Browser Devtools

Maintainers

Name Username
Ben Newman @benjamn
Alessia Bellisario @alessbell
Jeff Auriemma @bignimbus
Hugh Willson @hwillson
Jerel Miller @jerelmiller
Lenz Weber-Tronic @phryneas

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.x versions of Apollo Client for use with our Client Browser DevTools.
  • We do not offer support of 2.x versions of Apollo Client for use with our Client Browser DevTools.

Installation

You can install the extension via Firefox Browser Add-ons or the Chrome Webstore. If you want to install a local version of the extension instead, skip ahead to the Developing section.

Configuration

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.

Developing

Installation

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

Navigate to localhost:3000 to view the application. To view the API schema, navigate to localhost:4000.

Development with web-ext & WebExtWebpackPlugin

For cross-browser development, we rely on the web-ext command line tool and a modified version of the WebExtWebpackPlugin that hooks into the build process.

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
  • Use webpack --watch to 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.

Development defaults

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 lintOnBuild.

Tests

We use Jest and the React Testing Library to write and run our tests.

To run tests for both src and 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

Folder structure

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 src/application.

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.

Application Structure

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.

Explorer

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 tabRelay.ts.

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 devtools.ts.

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, sendExplorerRequest in explorerRelay.ts dispatches an EXPLORER_REQUEST event which is picked up in devtools.ts and forwarded to the client. In hook.ts the 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 Explorer.tsx.

Debugging

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 Inspect.

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.

Publishing

Release process, for those with permission:

  1. Verify that your changes work as expected by loading the extension as an "unpacked extension" locally for each browser.
  2. Update the ./package.json and ./src/extension/manifest.json version numbers.
  3. Commit changes and tag your version as a github release.
  4. Publish a new version to npm using npm publish in the root of the project. We're publishing to npm to allow other projects to have a dependency on devtools.
  5. Run npm run zip to pack all of the builds for submission.
  6. Create a new release in the Chrome/Firefox web stores (following the instructions for each browser in the sections below), uploading the zip bundle.

Chrome

Testing locally

  1. In your Chrome URL bar, go to: chrome://extensions/
  2. Click on Load unpacked.
  3. Add the apollo-client-devtools/build directory.
  4. The add-on should now be installed.

Submit for review

  1. Login to the Chrome webstore and access the Developer Dashboard.
  2. Select the Apollo Client Devtools extension to update.
  3. Click on Package then Upload new package.
  4. Select the ./dist/chrome.zip file for upload.
  5. Click on "Submit for review".

Firefox

Testing locally

  1. In your Firefox URL bar, go to: about:debugging#/runtime/this-firefox
  2. Click on Load Temporary Add-on.
  3. Add the apollo-client-devtools/dist/apollo_client_developer_tools-X.X.X.zip file.
  4. The add-on should now be installed.

Submit for review

  1. Login to the Firefox developer hub (user/pass is in our shared password system as "Firefox Developer Account").
  2. Once logged in, click on the Apollo Client Developer Tools "Edit Product Page" link.
  3. Click on the "Upload New Version" link in the top left side menu.
  4. Agree to any new Firefox distribution agreements or policies that might show up.
  5. 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).
  6. Choose the apollo-client-devtools/dist/apollo_client_developer_tools-X.X.X.zip for upload and submit. NOTE: when uploading to Firefox, you also must include the source code. A zipped version of the apollo-client-devtools repo with the built files, node_modules, tests & development folder deleted will do
  7. 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 Kotlin.
  • Apollo Server – A production-ready JavaScript GraphQL server that connects to any microservice, API, or database. Compatible with all popular JavaScript frameworks and deployable in serverless environments.

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.

More Repositories

1

apollo-client

🚀  A fully-featured, production ready caching GraphQL client for every UI framework and GraphQL server.
TypeScript
19,300
star
2

apollo-server

🌍  Spec-compliant and production ready JavaScript GraphQL server that lets you develop in a schema-first way. Built for Express, Connect, Hapi, Koa, and more.
TypeScript
13,522
star
3

react-apollo

♻️ React integration for Apollo Client
JavaScript
6,887
star
4

apollo-ios

📱  A strongly-typed, caching GraphQL client for iOS, written in Swift.
Swift
3,737
star
5

apollo-kotlin

🤖  A strongly-typed, caching GraphQL client for the JVM, Android, and Kotlin multiplatform.
Kotlin
3,382
star
6

apollo-tooling

✏️ Apollo CLI for client tooling (Mostly replaced by Rover)
TypeScript
3,042
star
7

apollo

🚀 Open source tools for GraphQL. Central repo for discussion.
JavaScript
2,626
star
8

graphql-tag

A JavaScript template literal tag that parses GraphQL queries
TypeScript
2,275
star
9

graphql-subscriptions

📰 A small module that implements GraphQL subscriptions for Node.js
TypeScript
1,567
star
10

subscriptions-transport-ws

🔃 A WebSocket client + server for GraphQL subscriptions
TypeScript
1,524
star
11

apollo-link

🔗 Interface for fetching and modifying control flow of GraphQL requests
TypeScript
1,438
star
12

apollo-link-state

✨ Manage your application's state with Apollo!
TypeScript
1,405
star
13

apollo-cache-persist

🎏 Simple persistence for all Apollo Cache implementations
TypeScript
1,368
star
14

fullstack-tutorial

🚀 The Apollo platform tutorial app
TypeScript
1,233
star
15

eslint-plugin-graphql

🚦 Check your GraphQL query strings against a schema.
JavaScript
1,194
star
16

router

A configurable, high-performance routing runtime for Apollo Federation 🚀
Rust
793
star
17

apollo-link-rest

Use existing REST endpoints with GraphQL
TypeScript
783
star
18

federation

🌐  Build and scale a single data graph across multiple services with Apollo's federation gateway.
TypeScript
659
star
19

apollo-fetch

🐶 Lightweight GraphQL client that supports middleware and afterware
TypeScript
576
star
20

apollo-rs

Spec compliant GraphQL Tools in Rust.
Rust
566
star
21

reason-apollo

Reason binding for Apollo Client and React Apollo
Reason
552
star
22

federation-demo

Federation 2 supersedes this demo and this example is no longer the newest. See https://www.apollographql.com/docs/federation/ for migration steps!
JavaScript
502
star
23

ac3-state-management-examples

✨ Learn Apollo Client 3's state management best practices
TypeScript
493
star
24

apollo-tracing

A GraphQL extension for performance tracing
475
star
25

apollo-client-nextjs

Apollo Client support for the Next.js App Router
TypeScript
446
star
26

persistgraphql

A build tool for GraphQL projects.
TypeScript
424
star
27

rover

The CLI for Apollo GraphOS
Rust
404
star
28

gatsby-theme-apollo

💜 Themes that we use to build Gatsby sites at Apollo
JavaScript
371
star
29

apollo-link-persisted-queries

Persisted Query support with Apollo Link
TypeScript
307
star
30

xcode-graphql

🛠 Xcode add-ons that add syntax highlighting for GraphQL query document files
Shell
276
star
31

apollo-studio-community

🎡  GraphQL developer portal featuring an IDE (Apollo Explorer), auto-documentation, metrics reporting, and more. This repo is for issues, feature requests, and preview docs. 📬
249
star
32

federation-jvm

JVM support for Apollo Federation
Java
247
star
33

supergraph-demo-fed2

🍿 Supergraph demo for Federation 2 and Apollo Router
Shell
162
star
34

principled-graphql

📈 Best practices for implementing and scaling a data graph
JavaScript
148
star
35

apollo-cache-control

A GraphQL extension for cache control
146
star
36

supergraph-demo

🍿 Compose subgraphs into a Federation v1 supergraph at build-time with static composition to power a federated graph router at runtime.
Shell
135
star
37

apollo-feature-requests

🧑‍🚀 Apollo Client Feature Requests | (no 🐛 please).
130
star
38

spotify-showcase

A Spotify clone that showcases the Apollo GraphQL platform.
TypeScript
126
star
39

meteor-integration

🚀 meteor add apollo
JavaScript
108
star
40

frontpage-ios-app

📄 Apollo "hello world" app, for iOS
Swift
101
star
41

space-kit

👩‍🚀 Home base for Apollo's design system: https://space-kit.netlify.com
TypeScript
88
star
42

apollo-scalajs

Use Apollo GraphQL from Scala.js apps!
Scala
88
star
43

invariant-packages

Packages for working with invariant(condition, message) assertions
TypeScript
88
star
44

apollo-federation-subgraph-compatibility

A repo to test subgraph libraries compatibility with the Apollo Federation Specification
TypeScript
77
star
45

starwars-server

JavaScript
73
star
46

blog

📝 Blog website built with Wordpress and Gatsby
JavaScript
68
star
47

iOSTutorial

The tutorial application for the Apollo iOS SDK
Swift
68
star
48

odyssey-lift-off-part1

JavaScript
64
star
49

federation-jvm-spring-example

Apollo Federation JVM example implementation using Spring for GraphQL
Java
64
star
50

vscode-graphql

Apollo GraphQL VS Code extension
TypeScript
55
star
51

apollo-kotlin-tutorial

The code for the Apollo Kotlin Tutorial
Kotlin
52
star
52

docs-examples

Example code supporting the Apollo docs
TypeScript
50
star
53

docs

📚 Apollo's docs framework
MDX
42
star
54

apollo-kotlin-2-tutorial

The code for the Apollo Android Tutorial
Kotlin
38
star
55

iOSCodegenTemplate

A template for the code you need to set up to get Swift Scripting up and running.
Swift
38
star
56

datasource-rest

A caching data source for REST APIs
TypeScript
37
star
57

apollo-workbench-vscode

Apollo Workbench is a design tool that facilitates planning changes to your supergraph. It enables you to understand the overall composition and execution of any given query at design time.
TypeScript
37
star
58

apollo-utils

Monorepo of common utilities related to Apollo and GraphQL
TypeScript
35
star
59

graphql-testing-library

Testing utilities that encourage good practices for apps built with GraphQL.
TypeScript
35
star
60

federation-rs

Contains source code for Apollo Federation's Rust<--> JavaScript interop
Rust
34
star
61

react-apollo-error-template

Apollo Client issue reproduction.
JavaScript
33
star
62

embeddable-explorer

TypeScript
32
star
63

federation-migration-example

🚀Example app migrated from schema stitching to Apollo federation
JavaScript
32
star
64

odyssey-lift-off-part5-server

Odyssey Lift-off V - Server - Course Companion App
JavaScript
31
star
65

odyssey-lift-off-part5-client

Odyssey Lift-off V - Client - Course Companion App
JavaScript
28
star
66

GraphiQL-Subscriptions-Fetcher

GraphiQL's fetcher that supports GraphQL-Subscriptions with the `subscriptions-transport-ws` package
TypeScript
28
star
67

supergraph-demo-k8s-graph-ops

Archived: GitOps config repo for an Apollo GraphQL federated graph with a supergraph router and subgraph services deployed to Kubernetes.
Shell
28
star
68

apollo-ios-dev

Apollo iOS Development Repo
Swift
28
star
69

apollo-ios-pagination

Swift
26
star
70

odyssey-lift-off-part2

Odyssey Lift-off Part 2 Course Companion App
JavaScript
26
star
71

spacex

A re-creation of https://github.com/SpaceXLand/api
TypeScript
21
star
72

apollo-graphql-stream-scenes

This is used for hosting streaming scenes for OBS - for Apollo GraphQL stream
JavaScript
19
star
73

federation-next

Moved to the Router repository
Rust
19
star
74

subgraph-template-typescript-apollo-server-boilerplate

A template for a minimal setup Apollo Server 4.x using TypeScript
TypeScript
17
star
75

federation-hotchocolate

HotChocolate support for Apollo Federation
C#
16
star
76

odyssey-lift-off-part3

Odyssey Lift-off Part 3 Course Companion App
JavaScript
15
star
77

odyssey-voyage-I

JavaScript
14
star
78

typescript-repo-template

A template for TypeScript projects with pre-configured tooling
TypeScript
14
star
79

subgraph-template-typescript-apollo-server

A Typescript template for Apollo Server as a subgraph using Apollo Federation
TypeScript
13
star
80

next-apollo-example

Template for creating Apollo Client + Next.js reproductions
JavaScript
13
star
81

community

Apollo community guidelines
JavaScript
13
star
82

design-principles

Where we are defining and collaborating on our Apollo internal design principles (individually and collaboratively). This is a public repo, but intended only for use by Apollo employees.
13
star
83

odyssey-lift-off-part4

Odyssey Lift-off Part 4 Course Companion App
JavaScript
12
star
84

core-schema-js

Typescript library for processing core schemas
TypeScript
12
star
85

apollo-client-swift-playground

Swift
11
star
86

apollo-ios-codegen

Apollo iOS Code Generation
Swift
11
star
87

test-span

Rust
11
star
88

specs

Apollo Library of Technical Specifications
CSS
10
star
89

router-template

A general purpose self-hosted Apollo Router template connected to GraphOS
Dockerfile
10
star
90

apollo-midnight

A VS Code color theme based on Apollo Studio Explorer color palette.
9
star
91

serde_json_bytes

a JSON Value object with strings backed by Bytes, parsed by serde_json
Rust
8
star
92

hack-the-supergraph

JavaScript
8
star
93

subgraph-template-rust-async-graphql

A boilerplate template project for building a subgraph with async-graphql
Rust
8
star
94

router-biscuit-plugin

⚠️experimental⚠️ plugin for the router using Biscuit tokens for authorization
Rust
7
star
95

devhub

🔭 Explore all the latest resources for building apps with Apollo
JavaScript
7
star
96

client-router-e2e-tests

Apollo Client ↔️ Router E2E Test Suite
JavaScript
7
star
97

odyssey-lift-off-lab

Odyssey Lift-off Lab starter repo
JavaScript
7
star
98

graphchat

TypeScript
6
star
99

introspector-gadget

GraphQL introspection utilities
Rust
6
star
100

zen-observable-ts

Thin wrapper around zen-observable and @types/zen-observable, to support ESM exports
JavaScript
6
star