In the last couple of years I’ve been building apps with Parcel, a JS bundler that requires zero configuration.

I’ve also been busy building a library to assist in the creation of design systems for CSS-in-JS apps, aiming to reduce the friction of creating and maintaining such a system and allow clear communication between designers and developers surrounding the design system spec. As part of this project I wanted to use Storybook, so here I share how to do just that.

This tutorial should enable anyone who has an existing Parcel app to get set up with Storybook very easily, even though there isn’t currently official support for builders other than Angular, Vue, NextJs, Vite, Webpack and Svelte. This could simply be because it’s just so easy to do it yourself and there really isn’t all that much configuration needed with simple Parcel apps.

In this example, I’ll be using React but you could in theory use other supported libraries/frameworks.

First up, take an existing Parcel app or create a new one by following these instructions: Building a React app with Parcel.

 $ yarn init
 $ yarn add --dev parcel
 $ yarn react react-dom
 ...
 $ yarn parcel src/index.html

Once you’ve got a React-based parcel app up and running, you’ll need to install the dependencies required to run storybook. By default, storybook builds with Webpack 4, but you could also use Vite, which might be faster at building.

Note: One downside of using a different builder to the one you use to deploy your app is that your code goes through a slightly different process in production vs. your storybook deploy. Something to bear in mind if you’re doing this in the Real World™️.

Whichever builder you decide to go with, run the command to install storybook with the builder configured like so:

 $ yarn dlx storybook init --builder <webpack4 | webpack5 | vite>

For details, see the storybook docs.

The Storybook CLI should detect that our app is a React app, and install the necessary requirements to install itself, complete with initial stories that can be viewed in a web browser upon completion.

If you used Vite, you might find that on Storybook versions < 7, using yarn with PnP functionality might cause some issues. To disable that, you can do the following:

 $ rm -rf .pnp*
 $ yarn config set nodeLinker node-modules
 $ yarn install

Using the Vite builder also requires installation of a couple more dependencies (at least in versions of Storybook < 7).

 $ yarn add --dev vite
 $ yarn add --dev @storybook/react-vite @storybook/builder-vite

Once complete, we can run our new Storybook and observe the new shiny documentation.

 $ yarn storybook

And to prove that these components can appear in the main Parcel app, we can also import them into our app to test them.

// App.js

import React, { useState } from 'react'
import { Button } from './stories/Button'

export function App() {
  const [count, setCount] = useState(0)
  return (
    <Button
      onClick={() => setCount(count + 1)}
      label={`This button has been clicked ${count} times`}
      primary
    />
  )
}

As you can see here, I have the two apps running side-by-side and they both reflect the current state of the codebase.

The parcel app:

The storybook deploy:

Thanks for reading along, and if you want to check it out, you can find the repository for this blog online: https://github.com/lukebarnard1/how-to-use-storybook-with-parcel