DEVELOPMENT.md

Development guide

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 urql actions (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.

• Node LTS or Current
• pnpm

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:

• The chrome web store
• Mozilla addons
• Npm (standalone for React Native)

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