urql Devtools: The Road to V1

April 28, 2020
Andy RichardsonAndy Richardson

In June 2019 we (the urql team) decided to set an adventurous goal of creating fully-featured developer tools for our GraphQL client.

10+ months, 10+ contributors, and 100+ pull requests later, we're proud to announce our first major release! Read below for the journey on how we got there or skip to the announcement.

πŸ“¦ Setting up an extension

One of the biggest hurdles we encountered when creating our first devtools extension was the initial boilerplate. For good reason, web pages can't talk directly to extensions or devtools panels without a myriad of communication layers.

We looked into existing implementations but found that, given their maturity, there was a lot more going on than just messaging. Because of this we decided to take our own approach by making use of an EventTarget in our background.js to route messages from our browser windows to their respective devtools panel.

We've found that this simpler approach, while it does have caveats, has worked great for our use cases.

  • Having also received great feedback from others working on browser extensions in the community, keep your eyes peeled for a boilerplate project / tutorial from us in the near future!

πŸ’¬ Sending messages from urql

Once messaging from the webpage to the devtools panel had been completed, it was time to put our money where our mouth is. urql has been created with extensibility in mind and we've been very vocal about this β€” so how did it do?

(Un)surprisingly well! Without modifications to the core urql client we were able to make an exchange which could:

  • See all incoming messages and responses
  • Inspect the state of the cache
  • Trigger GraphQL requests (sent from the extension)

This more than sufficed for our early pre-releases, but as time went on we found that we wanted more.

Introducing the debug target

Implementation details are an important part of any developer tool and over time it became apparent that we needed to find a way to expose the internal events happening inside of exchanges. A few examples include network triggers and responses (fetchExchange), cache invalidation (cacheExchange), and any other events which would be useful for debugging purposes.

In order to accommodate for this, we've added additional debugging capabilities to urql as of v1.11.x. It works a little something like this:

  • The urql client creates a debug source on creation
  • A dispatchDebug function is passed to every exchange
  • Exchanges can call this function to dispatch debugging events (at any time)
  • Anyone with access to the client can listen to these events
  • More details can be found in the new debugging section of the docs

For the devtools extension, this means that we can listen to debug messages coming from any exchanges and create a debugging experience for our users which is implementation agnostic - in other words, you could create a new exchange today and seamlessly have debugging info shown in the devtools extension just by calling dispatchDebug.

πŸ›  Building out the panel

At this point, we've now got messages coming from urql to the panel, so all we need to do now is create a webpage to present them... right? Well kind of...

Developer experience

In our first few months of working on the "frontend" of our extension, we found the developer experience to be rough, at best. Live reloading just wasn't an option, many changes would require us to reload the whole extension, and triggering/mocking debug events was a painful experience.

The biggest productivity booster, by far, was a few months in when we made the choice to develop using fixtures. This came with a whole host of benefits β€” from lowering the barrier to entry for new contributors, to faster updates thanks to the addition of hot reloading.

It also gave our team much more confidence in changes being made. We can quickly see the changes to fixtures while reviewing a PR and all our expected states are now modeled. To add to that latter point, fixtures allowed us to implement visual regression testing which would prove to flag unexpected visual and functional anomalies.

Design

Many of us working on this project have some kind of design experience in one form or another. As for design experience with browser extensions... not so much.

Data-heavy designs can be hard at the best of times; but add in the unique standards for browser panels such as smaller base font sizes, conservative use of spacing and color, and different interaction patterns - it doesn't take long to realize we're not in Kansas Bootstrap anymore.

While we're still learning, here are a few findings we've made on the way:

  • Acknowledge existing design languages - Chrome and Firefox have some great devtools so use them as a starting point
  • Aim for a highly static layout - theres going to be a lot of information on screen and having dynamic content such as panes appear and disappear can be more jarring than useful
  • Keep your information hierarchy flat - there's just not enough space for a deeply nested hierarchy (i.e. elements such as h1, h2, h3, etc) so flatter is better

πŸš€ The end result

After all that work, we're happy to announce that urql Devtools v1 is out! Here's what it does to make your GraphQL development experience even better!

Event timeline

  • Visualize all debugging events from your exchanges
  • Track queries, mutations, and subscriptions that have been executed
  • See network and cache updates, responses, and errors
  • Locate which components are triggering GraphQL requests
Events view of urql DevTool with a mutation query being observed

The events panel in urql Devtools v1.0.0

Cache Explorer

  • Explore an interactive overview of your cache
  • See which results are coming from the cache
  • Identify updates to cached data
Explorer view of urql DevTool with a "todos" field expanded

The explorer panel in urql Devtools v1.0.0

Request tool

  • Trigger GraphQL requests directly via urql client
  • Easily change the state of your app
  • Explore your backend schema
Request view of urql DevTool with a mutation and fragment being written

The request panel in urql Devtools v1.0.0

πŸ™ We did it!

A special thanks to everyone in the community who helped make this happen!

Whether you contributed code, reported issues, created feature requests, or provided feedback β€” you've helped make the urql developer experience what it is! We look forward to seeing the ecosystem continue to blossom 🌻

To find out more or get involved, check out the resources below:

Related Posts

Rust vs Go: Which Is Right For My Team?

August 29, 2024
In recent years, the shift away from dynamic, high-level programming languages back towards statically typed languages with low-level operating system access has been gaining momentum as engineers seek to more effectively solve problems with scaling and reliability. Demands on our infrastructure and devices are increasing every day and downtime seems to lurk around every corner.

A Rare Interview With A Designer who Designs Command-line Interfaces

May 13, 2024
For years, terminal and command-line applications have followed a familiar pattern: developers identify a need, code a solution, and release it for free, often as open-source software.

The Evolution of urql

December 6, 2022
As Formidable and urql evolve, urql has grown to be a project that is driven more by the urql community, including Phil and Jovi, than by Formidable itself. Because of this, and our commitment to the ethos of OSS, we are using this opportunity to kick off what we’re calling Formidable OSS Partnerships.