Preview GraphQL data in a comfy way - Storybook GraphQL Kit

This is a dev tool that allows you to write queries and immediately see the results in the browser. Unlike other tools here your queries and passing variables are stored alongside your code. You can use it withing your existing project for better visual documentation, testing and exploring your backend. It's created on top of Storybook and could be used as a Storybook addon or as a base for creating your own addons for Storybook.

It’s intended to be useful for both Backend and Frontend developers. If you’re a Backend developer you don’t need to have any Frontend knolege to use it with your GraphQL service.

<ImageBlock src="https://cdn-images-1.medium.com/max/3832/1*HdjB0ioTgNfNXReg2Hc6Ow.gif" alt="writing graphql queries${full-width,clickable}"/>

If your query results contain nested objects, arrays or image URLs they will be outputted in a user-friendly way: nested object will be spread, arrays displayed with a count of items and images will be displayed …as images :)

You only need to know Javascript and GraphQL to quick start

Just write your queries, organize them in whatever nested structure you need and all your data will be displayed via default UI.

You can deploy it as SPA and share with your teammates/users/managers to see and browse your backend. Each query (in terms of Storybook they are “stories”) will have the own route so you can easily point your colleagues to the exact part of your service.

Frontend developers can pass received data as props into React components and see how they look with real data.

Before we dive into details: If you’re not familiar with these amazing tools yet it’s really worth to check them out:

<ImageBlock src="https://cdn-images-1.medium.com/max/300/1*6oPrHfFukKwkXpavhriSKQ.png" alt="Storybook${small,centered}"/>

Storybook is an open-source tool for developing (not only) UI components in isolation for React, Vue, and Angular.

<ImageBlock src="https://cdn-images-1.medium.com/max/300/1*u0Fm8eWbobhvjUXdLYHIAw.png" alt="GraphQL${small,centered}"/>

GraphQL is a modern query language for server API

Why it was created?

Usually I’m creating Storybook Addons when facing a problem that isn’t solved yet. So the reasons were:

1. I wanted to have a handy tool to quickly observe, document and share my data that I receive in my project from GraphQL. This is especially useful for working with static or server side rendering applications which usually contains a data layer with information for creating all other components.
2. As a Storybook user and React developer I always dreamed to have a simple way to develop components in isolation but with access to real backend data.
3. When working with headless CMS it would be usefull to quickly create simple SPA to browse CMS data. Here my motivation was to extend default GraphCMS UI for our content managers in GitNation. Idea was to write own GraphQL queries and to deliver them to our manages. All things (queries, variables, headers) should be hardcoded once and then deployed to web.

Storybook-GraphQL-Kit do that exact thing: handles everything you need to fetch data from any GraphQL endpoint and then pass it to your stories so you are flexible to use it as you need.

So how does it look for users?

You can discover the real project that we created for our conference managers. This tool is for quickly observing a summary of current progress with speakers, talks, workshops and other stuff we provide for our conferences in GitNation.

<ImageBlock src="https://raw.githubusercontent.com/focusreactive/storybook-graphql-kit/master/docs/screenshot-example2.png" alt="writing graphql queries${full-width}"/>

Left panel contains navigation withing your queries. The structure of navigation you can create while adding stories to Storybook

Bottom panel contains input fields section and query data section. Input fields are generated by the variables you specified for your query. Users can use these inputs for searching withing entries. In data section you can inspect row data coming from your query.

<ImageBlock src="https://raw.githubusercontent.com/focusreactive/storybook-graphql-kit/master/docs/screenshot-example3.png" alt="writing graphql queries${full-width}"/>

Each section from left side navigation has a unique URL (example)

In some cases, it’s important for us to see how and with what details some entries will be displayed on the conference site. Here we switched from the default view to our custom components.

<ImageBlock src="https://cdn-images-1.medium.com/max/3056/1*8wgeH1c9KM69mVj8DyV-GQ.png" alt="writing graphql queries${full-width}"/>

You can write your own template to output fetched data using JSX syntax. For example, React developers can pass data as props to React Components.

Many features like story navigation, story routes, entire UI are comes from the Storybook itself. Storybook can be built as a static application and deployed to Github Pages or whatever you want. You can extend your project with other Storybook addons and features. For example by writing additional notes for your queries or by customizing the appearance.

And how it looks for developers?

For example you have a query like this:

<Gist id={'7513c1e974018ab24ca905112c4bc5b1'}/>

To add this into your project you’ll need to pass this to your story:

<Gist id={'2c5e764816fdea62a02e8ba64edcc513'}/>

Here name is the title you will see in the stories navigation, query is your query and vars - the object with variables.

Instead of passing hardcoded variables you can allow users to type them in the addon panel:

<Gist id={'c9fa40bc9d6d70c8b9576168a0e15858'}/>

Variables from searchVars will be merged with vars and passed with the query.

Until now all examples will output the default table with fetched entries. But if you want you can easily switch to your own output, just write a “story” for that:

<Gist id={'235468ffc5e0bc3a738adea4af89b66a'}/>

Note that your story will be rendered only after the request is finished. You don’t need to handle async operations by yourself.

You can write your stories using classic StoriesOf API as well.

In order to connect your queries with GraphQL client, your stories should be wrapped by withGraphQL decorator. You can do it for example this way:

<Gist id={'fb9c70966f1a5314df5feeb8a7cb1019'}/>

If you’re developing a GraphCMS service you need to provide additionally projectId and stage parameters. See Storybook-Addon-GraphCMS for details.

<Gist id={'0a6819d6c362689e8f0e8b926da9c6ec'}/>

Note that actually there are no difference in options accepted in decorator and via story parameters. You can pass all of them to both in any order.

How to start

You can start with this boilerplate project: Storybook GraphQL Quick Start.

For React developers who already have Storybook in theirs project it’s will be enough to add this addon from npm:

yarn add --dev @focusreactive/storybook-graphql-kit

You can find details and API references in the project repository on Github

How to extend

If you have fields that you'd like to output in your own way just extend this addon with your custom renderers. See how we created Storybook Addon GraphCMS with specific CMS features. You can use it as an example for creating your own addons.

This project is friendly for new contributors. Fell free to write an issue or start a PR. If you're interested in helping to develop this addon you can find contribution details in the project doc

You can always reach me in the Storybook Slack or in Twitter

Thanks for reading and happy coding!