If you work in front end development or with front end devs, you may have heard the term StorybookJS popping up more and more. This post will explain what it is, and how it might fit into your Drupal or WordPress theming workflow, and why you might want to do that.
What is StorybookJS
StorybookJS is a tool for developing and documenting a component library. A component library is a breakdown of your UI into discrete, modular, and reusable chunks. StorybookJS is not opinionated on any sort of CSS architectures. It is similar to other tools such as Pattern Lab, Fractal, etc in that it can be configured to suit the needs of your project. Storybook is written and configured in JS, and it has plugins for React, Vue, Angular, etc, as well as HTML. Since we don’t see ‘Drupal’ or ‘WordPress’ on that list, you may be wondering how appropriate of a fit Storybook is for those platforms. More to come on this!
Benefits of Using Storybook
Before we get into how to use this, lets talk about why Storybook is useful.
Storybook provides a component library. A component library is a valuable asset that catalogs and documents what is already styled, and presents that styling using representative markup. This allows for front end development and rapid prototyping without the additional lift of integrating it into your theme. This is useful during development, onboarding, and while discussing modifying existing features or prototyping new features.
A component library can provide a point of reference for content editors as well so that when planning a new landing page they can see what options and variations there are to visually present their content.
StorybookJS can also be extended so that the templates used to generate the example markup come from your applications templating languages. This allows you to use them directly in your theme. For example, Storybook can be extended to incorporate Twig for Drupal websites allowing your component library to be integrated into your custom theme.
Once you are set up to consume Twig in Storybook, those same templates become reusable chunks of markup. This will allow you to keep your template files clean and follow the Don't Repeat Yourself (DRY) principle.
A major benefit for a larger team using a tool like Storybook for working on styling is that it is run as an application separately from Drupal or WordPress. It is run via tools that are familiar to many front end developers such as npm and webpack. This means that it is easy for these developers to work on styling and interactivity without having to set up a local development environment or even be particularly familiar with the Drupal or WordPress theme layer.
How to set up Storybook
If you are curious about Storybook, it has very good documentation to get you up and running at Storybook JS Quick Start.
Here is a small walkthrough (from the React QuickStart page) setting up the React version of StorybookJS via the command line. This assumes you have a recent version of Node installed:
Create a directory:
mkdir my-storybook cd my-storybook
Set it up as an npm project:
npm init
Install the React flavor of StorybookJS
npm install @storybook/react --save-dev
Install React and React DOM as dependencies
npm install react react-dom --save
Install Babel loader and Babel Core as dev dependencies
npm install babel-loader @babel/core --save-dev
Add a directory inside my-storybook, my-storybook/.storybook.
This directory will story any config that you want to set up.
mkdir .storybook
Add a file named main.js inside this directory, and add the following contents:
module.exports = { stories: ['../src/**/*.stories.[tj]s'], };
This tells storybook where to look for the files that define your stories so in this case a directory at my-storybook/src.
{ "scripts": { "storybook": "start-storybook" } }
This sets up an npm script to call the command to start Storybook.
Before we launch this, let’s add a story. Create a file in my-storybook/src named taco.js. Add the following React component (yeah it is a bit useless):
my-storybook/src/taco.js import React, { Component } from 'react'; class Taco extends Component { render() { return ( <div className="taco"> 🌮 </div> ); } } export default Taco; export { Taco };
Add a file next to it named taco.stories.js, with the following contents:
mystorybook/src/taco.stories.js import React from 'react'; import { Taco } from './taco'; export default { title: 'Taco' }; export const taco = () => <Taco />;
Now if you run the command we added to package.json, you should see storybook launch:
npm run storybook
This should output something like:
╭──────────────────────────────────────────────────╮
│ │
│ Storybook 5.3.19 started │
│ 5.12 s for manager and 5.52 s for preview │
│ │
│ Local: http://localhost:52881/ │
│On your network: http://10.0.1.172:52881/ │
╰──────────────────────────────────────────────────╯
If you visit one of these URLs in your browser, you should see the Storybook UI, along with a render of our ‘taco’ component.
Storybook Resources
This has been a simple overview, but StorybookJS is an increasingly standard and widely used tool in the world of front end development, and there are lots of addons and resources out there. Here are some good ones to start with:
- Official docs
- Learn Storybook, guides, and walkthroughs by project maintainers
- Emulsify Design System from Four Kitchens, a Drupal and WordPress theme system that uses the React version of Storybook and is set up with Twig.js. This is an excellent choice as it is well documented and maintained, and has been around for a while in a previous incarnation that integrated Pattern Lab with Drupal theming.
- Emulsify DS Drupal
- Emulsify DS WordPress