A note of what I learned integrating Storybook with Gatsby and the problems I solved.

Storybook: A framework to display and let you interact with your React components.

Gatsby: A framework to build a website using React.

Official document for integration.

Official document for Storybook

Problems

The install is supposed to be easy.

npx storybook init

It should just work, since the Gatsby based website essentially is an React app and Storybook works well with it. However :(

Problem 1 - Webpack 4 VS 5:

After installing Storybook, my Gatsby site won’t be able to build.

Solution 1:

After checking Gatsby integration doc, turns out Gatsby uses Webpack 5 while Storybook uses Webpack 4 . Besides, on Gatsby’s page, it says using following command:

npx sb init --builder webpack5

Then here comes the second problem.

Problem 2 - Webpack 5 not found in registry:

404 for installing Webpack 5 with above command line. (As of 2022/07/05)

If you are unlucky, you could encounter this failure:

npm ERR! 404 Not Found - GET https://registry.npmjs.org/webapck - Not found
npm ERR! 404  'webapck@latest' is not in this registry.

However, as I tried npm install webpack@5 , I was able to install it.
What is even more weird is that the first time to visit registry.npmjs.org/webpack in browser, it does return an 404. But if you change webpack to, say, “react”, it will load (of course), then if you change it back to “webpack”, it loads too. I don’t know what’s wrong with the server…

Solution 2:

As the document says, --builder is a convenient way to config. If it doesn’t work, just go manual:

npm i -D @storybook/builder-webpack5 @storybook/manager-webpack5

Then to update .storybook/main.js, in my case, after installing dependencies, it was configured to 

"framework": "@storybook/react",
"core": {
  "builder": "@storybook/builder-webpack5"
}

which still works.

What I Learned

Automated install is good, but sometimes if it doesn’t work, worth the time to try a manual process.

Now my Gatsby site is Storybook’d 😀 storybookd