Storybook is a great visual testing tool for any React project because it allows you to develop your components independently of your main application, and perform easy visual testing with Storyshots.

Another great feature is the docs add-on which can automagically generate great living documentation from the component itself; using docgen comments, prop-types and default props.

Storybook can also draw in the results of any Gatsby Static Queries, so that your components will be able to render outside the scope of a full Gatsby page.

Getting started with Storybook and Gatsby is easy: Just follow this tutorial. After that, I would highly recommend you install the Storybook docs add-on, instructions for which you can find here. Finally, after installing about a million things, you might be tempted to jump straight into starting the Storybook development server. That is where things might start to fall apart... There will be missing documentation, no PropTypes and lots of errors complaining about static queries.

Fear not! The following steps show you how to get around these 'gotchas', and properly pull a component's comments, PropTypes and static queries into Storybook.

1. Make sure to export your components in the story defaults.

First things first, make sure to set the component attribute in your story's default export. This will tell the docs add-on where to look for all the docgen comments, PropTypes and more. The example below uses a greeting component, but this is a drop-in example for any component. In your component's story, make sure the default export looks like this:

import { Greeting } from './Greeting';

export default {
  title: 'Default Greeting',
  // Pass the component to allow the docs addon access to the metadata!
  component: Greeting,
};

// Rest of your story below.
...

2. Add babel-plugin-react-docgen in the webpack plugins section of main.js.

This is the crucial step which kept me searching for a good couple of hours. If you followed the Gatsby tutorial for getting Storybook ready to rumble, you will have already made some changes in the .storybook/main.js file. To enable all the lovely docgen goodness, you need to ensure that the correct Babel plugins are available to transpile the Gatsby components properly and make the info available to Storybook. In this case, the babel-plugin-react-docgen plugin must be referenced in the custom webpack config. Make sure you plugin option look like this in the .storybook/main.js file:

...

config.module.rules[0].use[0].options.plugins = [
      // ...
      require.resolve("@babel/plugin-proposal-class-properties"),
      // ...
      require.resolve("babel-plugin-remove-graphql-queries"),
      // use babel-plugin-react-docgen for docgen support.
      require.resolve("babel-plugin-react-docgen"),
    ]
    
...

This step will bring all your Prop Types, default Props and docgen standard comments right into the storybook docs tab. Sweet!

3. Tell Storybook to serve the ./public folder with the correct environment configured.

Once you run gatsby develop in your project directory, a ./public folder will be generated. The babel plugin babel-plugin-remove-graphql-queries (see the webpack config above) does all the heavy lifting when it comes to dealing with your Gatsby static queries. However, we still need to serve the results of all the GraphQL queries alongside Storybook so that the components get everything they need to render properly. So we can just change our Storybook run command in the package.json to look a little something like this, right?

"storybook": "start-storybook -p 6006 -s ./public"

Well, it turns out that babel-plugin-remove-graphql-queries only runs in production or test environments. By default, the development environment is configured. So, to fix this, we can run Storybook with the NODE_ENV environment variable set to test or production (your choice), like so:

"storybook": "NODE_ENV=test start-storybook -p 6006 -s ./public"

And there we go! Running npm run storybook should present a Storybook with all static queries properly taken care of. Note that the components only have access to whatever query results reside within ./public. You might need to restart your Gatsby development server if things are not showing up as you might expect.

To Conclude

I hope these tips save you the pain of trying to figure out Babel and Webpack intricacies. I must confess, I am still very much learning these technologies, but get closer to understanding every day!

Now, here is some music to celebrate your victory: