Improvements to GraphiQL IDE - adding GraphiQL Explorer

Updated September 19th 2019

Gatsby’s data layer is powered by GraphQL. This means that if you are building a Gatsby site, you will almost certainly use GraphQL to take advantage of Gatsby’s rich plugin ecosystem that extends this schema with data from anywhere. A popular tool for exploring your GraphQL schema is GraphiQL — which is a graphical, interactive, in-browser GraphQL development environment. It serves as an interactive playground where you can compose, test, and see the live results of your queries. If you haven’t seen or used GraphiQL, it looks something like this:

What is GraphiQL Explorer?

graphiql-explorer is a plugin for GraphiQL that adds a new technique to explore and build GraphQL queries. It adds a graphical representation of available fields and inputs that can be used in queries. It also allows constructing full queries by clicking through available fields and inputs without the repetitive process of typing these queries out by hand!

GraphiQL Explorer was built by the team at OneGraph (OneGraph is a single GraphQL endpoint through which you can bring in data from dozens of services like Salesforce, Stripe, Spotify, GitHub, and more). Check out the “Build a Podcast Mashup App Using OneGraph and Gatsby — Learn With Jason recording to learn more about OneGraph and how to use it with Gatsby.

Why use GraphiQL Explorer?

We often hear that many developers’ first usage of GraphQL is through Gatsby. GraphQL, like any technology, has a learning curve. We can’t eliminate this learning curve completely but we can try to make it smoother. As mentioned previously, GraphiQL Explorer allows users to build full GraphQL queries without typing a single line of code. This enables users that don’t yet fully understand the GraphQL query syntax to learn GraphQL much more easily:

Check out “How OneGraph onboards users who are new to GraphQL” blog post for more details.

Advanced usecases

Improvements to on-boarding users new to GraphQL isn’t the only goal of integrating GraphiQL Explorer into Gatsby. There are other pain points that are getting addressed with this addition. Specifically union types and inline fragments. If the user is not aware of this syntax to query this type of fields it can be a fairly frustrating experience! GraphiQL Explorer helps solve this problem by listing available union types:

Try it now

We recently added GraphiQL Explorer to Gatsby. It’s available starting with gatsby@2.7.3.

Create new Gatsby project:

or update Gatsby in your existing project:

or try it live.

Future work

There are opportunities for further improvements for Gatsby users. Few things we will be working on are:

• evaluating accessibility of GraphiQL interface and addressing found issues,
• adding support for using GraphQL fragments provided by Gatsby plugins,
• adding code snippet generation for common workflows (using another awesome OneGraph’s GraphiQL addon - graphiql-code-exporter). Check update!

Update (September 19th 2019)

Code snippet generation (mentioned in Future work section) was added in gatsby@2.15.3! Huge thanks to Dan Kirkham who integrated graphiql-code-exporter into Gatsby’s GraphiQL IDE!

Snippets we currently support are:

• Page templates
• Components using static queries (both <StaticQuery> and useStaticQuery variants)

Using those snippets allows users to quickly scaffold new pages and components that use queries created in GraphiQL IDE.

Usual flow would look like this:

1. compose your query in GraphiQL,
2. click “Code Exporter” button in GraphiQL’s toolbar,
3. select type of snippet
4. click “copy” button (or manually select generated code snippet and copy it),
5. paste copied snippet into new file in your code editor and save it.

Now you have working page or component that uses your query!

Interested in checking how Dan did this? Check his Pull request!