Development guide
March 9, 2023 · View on GitHub
There are a lot of moving parts to devtools so here's a quick run-through to make your life easier!
❓ What does this do?
This is a graphical interface for debugging and interacting with urql which consists of:
- A frontend interface for viewing and triggering
urqlactions (see panel) - A messaging interface for communicating with the devtools exchange in a browser envrioment (see extension)
- A messaging interface for communicating with the devtools exchange in a React Native environment (see electron)
👩💻 Getting started
Here are a few useful approaches to get started developing.
Development environments
You'll need these installations to get started, these should work on Linux/Windows/MacOS.
Installation
We use pnpm to manage our dependencies, to initially install all of them you need to run:
pnpm i
from your command-line at the root of this repository.
Producing a build
By running the build command we produce the final build that is uploaded when we create a release.
pnpm run build
This build will be located in dist/extension.
When you want to create the build for a specific version you can use our tags.
git fetch --all --tags && git checkout vx.x.x && pnpm i && pnpm run build
This will ensure that you have the dependencies we used at that tag and produce a build.
Fixture environment (panel)
The easiest way to get started on a change in the devtools panel is in the fixture environment.
pnpm run cosmos
With a fixture environment, you can:
- model and test panel components and their states
- quickly make visual changes to the panel (with hot reloading)
- increase test coverage
Shallow environment (panel/extension/electron)
When working on functional changes (such as messaging, event handling, etc), the easiest way is going to be in a shallow/test environment.
Tests environments can be spun up using the following command.
pnpm run test --watch
Integration environments
Running an devtools in an integrated environment can be useful for working on/testing messaging features.
Browser environment (extension)
Start a build
Run the following command to start a watched build.
pnpm run dev:extension
Load the extension
Load the built extension in chrome or firefox.
Visit a project
Visit the live urql project - or create an app which uses the devtools exchange and navigate to it in your browser.
Standalone environment (electron)
Start a build
Run the following command to start a watched build.
pnpm run dev:electron
Start devtools
Run the following command in a separate shell to start the built app.
pnpm run start
Start an app
If you don't already have a React Native app that uses @urql/devtools, you could use this example app
🚀 Publishing releases
Anyone with write access to the repository can publish a release. The steps are as follows.
1. Merge the "Version Packages" PR
This will increment all the versions on the master branch
2. Publish new release
(replace v0.0.0 with your new version)
git fetch origin master
git tag v0.0.0 origin/master
git push origin v0.0.0
Warning: This will publish a new release to:
3. Create a new release on Github
Finally, navigate to releases and choose draft a new release.
- You can copy and paste the release notes from the changelog you just generated
- Attatching the published assets from the chrome store, mozilla addons, and npm (
wget $(npm view urql-devtools dist.tarball)) is also a good idea
4. Upload the source-code
Go to your tag, download the .zip file, upload it on your FireFox version with the instructions to build the package.
An example description:
You'll need these installations to get started, these should work on Linux/Windows/MacOS.
- [Node](https://nodejs.org/en/) LTS or Current
- [pnpm](https://pnpm.io/)
Steps to produce a build:
- run pnpm i from your cli
- run pnpm run build from your cli
- navigate to dist/extension to see the published build