Skip to main content

Michal Piechowiak

Software developer @ GatsbyJS. Likes solving weird problems, skiing and watching/reading sci-fi. In that order.

2 min read · June 3rd 2019

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:

GraphiQL demo

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:

GraphiQL Explorer introduction demo

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:

GraphiQL Explorer union types support

Try it now

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

Create new Gatsby project:

gatsby new gatsby-with-explorer

or update Gatsby in your existing project:

npm install gatsby

or try it live.

Future work

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

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!

Demo of scaffolding new page with GraphiQL Code Exporter

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

Tagged with graphql, building-sites-faster, developer-experienceView all Tags

Enjoyed this post? Receive the next one in your inbox!

Docs
Tutorials
Plugins
Blog
Showcase