Peach QE: Making GraphQL Queries Just… Peachy

7 min readJun 17, 2021

PeachQE is a Node.js-based desktop application powered by Electron. It is a Query Explorer tool developed to simplify the process of editing, creating, and parsing many GraphQL queries at once within a Relay environment.

Written in collaboration with :

PeachQE is a feature-packed tool for developers using Relay. But before we introduce it, there are a few questions we have to answer.

What is GraphQL?

GraphQL is a query language that simplifies requests to a database or API. By exposing data at a single endpoint and allowing you to declaratively request and receive only the data you need, GraphQL reduces waterfall requests and over-fetching. This brings an end to the tiresome process of cycling through a never-ending list of routes for different data, centralizing your entry point, and saving you time in the process.

And because your queries only ask for what you need, GraphQL is self-documenting. Your components can be concisely co-located with their data-dependencies.

There are several popular, powerful, and user-friendly GraphQL clients on the market. We’re going to focus on one of the most sophisticated and performant: Relay.

What is Relay?

Relay is a powerful, opinionated GraphQL client designed for performance at scale. Under the hood, it handles caching and state management while fetching GraphQL data in React applications. Relay emphasizes maintainability, type safety, and runtime performance with a “render-as-you-fetch” design pattern.

Relay is deeply tied to React and the company that created it — Facebook. It was built for Facebook’s specific needs: complex applications with a lot of moving parts and many rapidly updating data dependencies. Components declare what data they need, and Relay figures out how to efficiently fetch it while managing state and caching for you behind the scenes.

If Relay is so powerful, what’s the problem?

Relay can be like jet fuel to a project. It is incredibly powerful and delivers data fast. But, when not properly tracked and managed, it becomes cumbersome, confusing, and may feel like it is more trouble than it is worth. Getting a clear view of what is going on with Relay under-the-hood can be difficult without the availability of up-to-date dev tools.

Meanwhile, you have to manage and test your GraphQL queries. There are several popular query explorers on the market: GraphiQL and Apollo Explorer are perhaps the most popular. But no Relay-specific query explorer exists.

Think about it: with all that Relay handles under-the-hood — caching, state-management, fetch-or-store policy — and all the complexity that comes from working with such a highly-opinionated tool, wouldn’t you want a Relay-specific tool?

And given that Relay is built for managing applications at scale, you probably don’t want to be entering your queries one at a time. In fact, developers have been filling GitHub with requests for features that would allow them to upload multiple queries at a time.

And with all those queries, wouldn’t you want a way to keep track of them? A way to save and step back through the history of your queries as your project grows?

If only there were a tool to track, manage, and edit your queries on the fly in an environment that displays all the information you need about what’s going on behind the scenes…

Can you guess where this is going? You’re right: there is a solution. That solution is PeachQE.

The Solution PeachQE

Peach QE is an all-in-one Query Explorer built for Relay. PeachQE assists you in parsing, organizing, editing, and creating new GraphQL queries. This feature-rich application uses the Relay framework to compile your queries with precision and speed guaranteeing accurate responses and real-time variable input updating.

It’s everything you expect from a Query Explorer, plus some Relay-specific tools and features that make working with Relay easier and faster.

Want to upload dozens or even hundreds of queries? You can render them all with a button click in PeachQE.

Want to save the history of your queries for multiple GraphQL schema and endpoints? PeachQE comes with a built-in history for your queries and conveniently stores references to the GraphQL Schema and endpoints you work with.

Have another query file to test? No problem! Peach QE allows for drag and drop query files so you can test and use any GraphQL query you want!

All this, plus a visualizer for the Relay Store that you can save and revert as you explore and edit your updated queries. It’s a one-stop shop for your Relay application.

Come Git some PeachQE!

Built With

Node.js
Electron
Relay
React

Getting Started

Fork and Clone the Repo:

git clone https://github.com/oslabs-beta/peach.git

Prerequisites

Install the dependencies:

[ npm i ]

npm install

Run the Electron App locally

npm start

Deployment

In order to build the executable file (aka, the desktop client) you will need to run specific commands for your OS:

Mac:

npm run package-mac

Windows:

npm run package-win

Linux:

npm run package-linux

Look for the directory Release-builds in the root folder where you cloned this Repo. (created automatically by the previous command)
Find the specific folder for your OS. (e.g., peachQE-win)
The file peachQE.exe (in Windows) will launch the app on your machine.

In every case, you will need to add the file schema.graphql to the root directory and the file imported.js to the directory src>relay. For example:

.
├── (Root)                    # Installed Root folder
├── schema.graphql
├── src   
    ├── relay                 # Create both folders
          ├── imported.js     
│   
└── ...

User Manual

Once you have the application running, you will notice that PeachQE operates in two different “modes”:

Relay Proper

When the application first opens, the window will by default display “Relay Proper” mode, which contains much of the core functionality of the application:

The left section of the window is reserved for the Schema Display. Here, you can:

View your current schema and type into the search bar to find specific fields.
Import a new Schema, updating the contents of the schema display to contain the newly imported schema.
Update the GraphQL API urlendpoint. This determines what API PeachQE is interacting with.

Below the Schema Display, you will find the Variable Input. Here you can:

Manually enter variables as JSON objects.
The Variable Input will interact with the Query Input to set the response in the Response Display.

The central section is reserved for the Query Input. Here you can:

Manually type in valid GraphQL queries.
Select previous queries from the Query History dropdown. Once clicked the selected query will populate the Query Input Field.
Submit your query.

The right section is the Response Display which, upon clicking the Submit Query button, will display the responses to any submitted query.

Peach Mode

By clicking the yellow button titled Peach Mode at the top right corner of the window, or simply by scrolling down, you will find our designated UI for Relay-specific functionality.

While the Response Display functions entirely the same, the central and left sections have been altered to accommodate for Relay-specific functionality.

The left section still contains a Variable Input with two additional fields:

The Query File Uploader simply directs you to the “Peaches” dropdown from the menu bar, where you can “Start a New Peach” by uploading a file containing a list of GraphQL Queries.
The Store Display offers you a direct visual of the Relay Store, a Relay-specific functionality that stores all the data sent by your GraphQL Queries, and all the data sent back from the responding GraphQL API. It is effectively a log of your interactions with a given GraphQl API, and it is made available with PeachQE!

The central section contains 2 new components:

The Query Editor where you may copy/paste or manually type in multiple GraphQl Queries. Upon clicking Save Edited Query, the user inputted text will be saved and rendered as Relay queries, which will be displayed in the New Query Selector.
The New Query Selector will contain a list of queries matching the queries inputted in the Query Editor. You may then toggle between these queries, and the Response display will update with the currently selected query.

Enjoy!

Downloadable App

Or if you don’t want the codebase. Simply download our App! https://peachqe.io/
Enjoy a simplified way to pick your peachy queries!

License

Distributed under the MIT License. See LICENSE for more information.

Acknowledgments to the PEach QE team: