gatsby-recipe-storybook-js
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 https://webpack.js.org/concepts#loaders
|
| 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 developandgatsby buildsteps 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|jsxfile extensions - Transpile all ES6 code found within them to ES5 / CommonJs
- Strip out any GraphQL queries
- Add the
react-docgenplugin (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
https://raw.githubusercontent.com/PaulieScanlon/gatsby-recipe-storybook-js/master/gatsby-recipe-storybook-js.mdx
🚨 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