By Paul Scanlon


  • Gatsby
  • Gatsby Recipes
  • Storybook
  • JavaScript

If you haven’t tried Gatsby Recipes yet you really should!

You can read a bit more about them here which will give you a better overview of how they work, but to summarize here’s a quote from Gatsby founder Kyle Mathews

Gatsby Recipes, a new tool to automate common site building tasks.

To use recipes you must upgrade to the latest version of the Gatsby CLI

npm install -g gatsby-cli@latest

You can then use a recipe by running something similar to the below in your CLI

gatsby recipes url-to-recipe/name-of-recipe.mdx

The Storybook Problem

The problem in a nutshell is that Gatsby does a few things when you run either gatsby develop or gatsby build that Storybook by default does not.

To get the two playing nicely together we need a custom webpack config and it’s precisely tasks like this where Gatsby Recipes can do the lions share of the work so you don’t have to! 🦁

For instance, if you have any components that contain either a <Link /> imported from gatsby or any GraphQL queries you’ll likely see an error not to dissimilar to this 👇

ERROR in ../node_modules/gatsby/cache-dir/gatsby-browser-entry.js 25:4
Module parse failed: Unexpected token (25:4)
You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. See
|   return (
>     <React.Fragment>
|       {finalData && render(finalData)}
|       {!finalData && <div>Loading (StaticQuery)</div>}
  • The first reason we get this error is because Gatsby exports as ES6 and Storybook by default expects all code to be ES5 / CommonJs.
  • The second reason is that the gatsby develop and gatsby build steps remove GraphQL queries, Storybook by default does not.

So that’s the issue, but what can we do about fixing it?

The solution

Storybook allows us to write our own webpack config and there’s some docs on that here but in short we need to push a new rule to the Storybook webpack config that will mimic the Gatsby build steps.

This new rule will do the following things.

  • Match all js|jsx file extensions
  • Transpile all ES6 code found within them to ES5 / CommonJs
  • Strip out any GraphQL queries
  • Add the react-docgen plugin (not essential but i like prop documentation)

This doesn’t sound like a huge job but if you’re scared of Webpack like i am it’s nice to be able to automate this step so you can just get on and develop your UI.

So that’s why i created this recipe.

The recipe

The complete steps of my recipe are as follows:

  • Install babel plugins and presets
  • Install babel-plugin-react-docgen
  • Install Storybook React NPM packages and addons
  • Create custom Storybook webpack config (main.js) for js|jsx
  • Configure Storybook / Gatsby Link settings (preview.js)
  • Create example Link stories
  • Add Storybook npm scripts to package.json

You can test out my recipe gatsby-recipe-storybook-js by running the following in your CLI

gatsby recipes

🚨 Update:

This recipe is now part of the official Gatsby CLI 🎉 You can test it out by running the following in your CLI 👇

 gatsby recipes storybook-js.mdx

The repo can be found here on GitHub and if you’re interested in the Webpack config you can find that here in main.js

Oh and before i forget, make sure you’ve run gatsby develop or gatsby build before you start Storybook, because we need the relevant GraphQL data to exist before we run Storybook.

There’s also a TypeScript flavor of this recipe, you can read about that here gatsby-recipe-storybook-ts

Lemme know how you get on! @pauliescanlon


Leave a reaction and let me know how I'm doing.

  • 0
  • 0
  • 0
  • 0
  • 0
Powered byNeon