The only thing worse than getting an error in response to a query is a vague error response or no response at all. For this, GraphQL API query language is certainly guilty.

For engineers Gwen Phillips, Jerald Stephenson, Josh Merrell, and Mariah Talicuran it was a problem worth solving.

They developed an open source tool, with the help of tech accelerator OSLabs, called GraphErrQL, that introduces clear error contextualization for GraphQL queries in a Node.js runtime environment without adding any dependencies to production applications.

Of the issue, Talicuran explains that it made working with GraphQL, “difficult to debug. It was an issue that needed more remedying.”

Phillips, explaining the challenges of debugging GraphQL queries, used the example of, “not having a user in a database isn’t an error, they just don’t exist in the database.” Because technically, are unexpected results an error? Yes, if it was a misspelled name but no if that user just isn’t in the database. And clear error responses are a good way to find out what’s really going on with the query.

“Our original motivation was to develop a tool that could distinguish between two types of errors, the first being actual errors and the second being unexpected results with the goal of helping the developer improve upon their code base,” Merrell said.

Their original scope revealed itself as too narrow to fully solve the challenge at hand in the way the GraphErrQL engineers knew it had to be solved. The project grew due to the lack of readily available GraphQL sandbox environments that could also seamlessly connect to the user application’s front end to live capture queries. The idea of improving upon an existing sandbox was no more and the team had to build their own user interface as well.

The end result is GraphErrQL, an npm package that can test queries and receive queries and mutations from the host application’s frontend, live capture the queries in a separate tool, and log the query results including time stamps and error contextualization features.

What Does GraphErrQL Do?

GraphErrQL’s mission is to identify and clearly illustrate issues with GraphQL queries before the application or feature moves into production. Since GraphErrQL is a development tool, the package can be kept as a dev dependency or deleted altogether before production.

This piece of Node.js/ Express middleware is built for use with existing GraphQL Expressed-based host applications and is compatible with all frontend frameworks, libraries, and vanilla code. No frontend modifications or connections are needed for GraphErrQL to function.

Once the package is installed into the host application, and initial browser rendering takes place, GraphErrQL’s event listener (set up via Server-Side events) receives all GraphQL queries sent from the host application’s server.

By going to the specific /GraphErrQL endpoint, the developer will have full viewing of the GraphErrQL user interface which shows the query and result. Successful results will also show in the user interface.

For more detail on the tech specifics, check out their article in Medium.

Making a Scalable, User-Friendly Application

“If it’s easy to use, it’s more likely to be used. If there’s a lot of ramp-up time just to get better error handling, it’s not likely that developers are going to use it,” said Merrell, echoing was a sentiment shared by all engineers on the team.

These ideas lead the team’s drive to do the heavy lifting to make sure GraphErrQL didn’t need its own server. Now that it’s launch time, everyone is confident that this was the correct choice but this topic did come about while discussing the largest technical challenges of building the product.

The challenge was as follows. The user interface is built with React. React needs to be compiled before it’s served, which, in theory, no problem, but there’s no server here. Since the endpoint couldn’t lead to a bunch of components just floating around, the team had to configure a way for the user interface to precompile. Once that was done, they had to write a script allowing the page to be accessed from within the host application’s node modules.

The last piece of the challenge the team needed to nail down was scripting out instructions on how to dynamically grab the React files from anywhere the developer may have them on their computer. While this isn’t the sole purpose of the last part, it’s also one of the reasons why GraphErrQL is also compatible with desktop applications.

Less Code Is More

Keeping with the theme of ease of implementation, Stephenson elaborated on the challenge of condensing the functions and logic into the least amount of code as possible without losing any functionality. He explains, “It was a little tricky since we have to hit multiple endpoints meaning we need at least four lines of code. We leveraged closures within closures to get everything cleaned up!”

The final code that users can implement into their application includes middleware with that connects to the GraphQL endpoint, serves up the React user interface, and connects the GraphErrQL interface to server-side events.

The Road(map) Ahead

The initial release last week is the Beta release. The engineers are excited to have a fully functional platform. With the access to host applications’ live queries up and running, there is a rich area for them to work in. Currently, the team is working on a feature that will pinpoint which errors need development focus and prioritization.

Another feature on the team’s radar is adding the capability of identifying which file or line of code caused the error and compatibility with Apollo. No release date has been set for those features yet.