Storybook Integration

How to automate Storybook stories for everything - custom, WordPress Core, and Atlas blocks.

Storybook is the most popular system to document the visual styles and property behavior of React components, in a manner that's convenient for both designers and React developers.

Atlas ships with built-in support for Storybook. Just as the block meta-data automates controls in Gutenberg, the same meta-data automates stories and controls for Storybook. You can quickly get stories for all your blocks, as well as the Atlas Core blocks and Gutenberg Core blocks. Then, add additional stories if and when you want to.

If you want a sneak-peak of how it looks when configured, here's our own Storybook of Atlas Core and Gutenberg Core components.

Setting up Storybook

Let's set up Storybook in our tutorial application.

1. Install its packages and dependencies:

npm i -D --legacy-peer-deps @storybook/addon-actions \
    @storybook/addon-essentials @storybook/addon-links @storybook/react \
    @storybook/addon-postcss babel-loader webpack@4

2. Add package.json scripts to run Storybook. The first is for local development, running on a local port and auto-refreshing whenever you update your code. The other is optional; it builds a fully-static, optimized production Storybook website, like this. In the example below, we're placing the production build into Next.js's public directory, where you could then access it from your web application at the path /storybook/index.html.

{
  "scripts": {
    ...
    "storybook": "start-storybook --quiet --loglevel warn -p 6006",
    "storybook-build": "build-storybook --quiet --loglevel error -o ./public/storybook"
  }
}

3. Configure Storybook to locate the stories inside our block directories, both for included modules as well as in the current project. Storybook keeps this configuration in a directory named .storybook in the root of your project. Create that directory, and the main configuration file inside the directory, named main.js. The following complete example for main.js looks for stories in your own blocks (which we'll implement next), and includes the Atlas blocks and Gutenberg Core blocks:

module.exports = {
  "stories": [
    "../blocks/**/*.stories.mdx",
    "../blocks/**/*.stories.@(js|jsx|ts|tsx)",
    "../node_modules/@asmartbear/gutenberg-bridge/**/*.stories.@(js|jsx|ts|tsx)",
  ],
  "addons": [
    "@storybook/addon-essentials",
    "@storybook/addon-links",
    "@storybook/addon-postcss"
  ]
}

4. Configure Storybook to load your CSS and your theme. CSS is included in exactly the same way and for the same reason that we included the global CSS in the web application; in fact we can use identical code to what we used there. Your theme you can load from your existing JSON file -- the same one used by the WordPress Theme Builder, using an Atlas utility that automatically applies the Atlas theme to all Storybook stories.

All of this is done in a separate configuration file located in .storybook/preview.js. Here's a complete example:

// Include Atlas styles and generated block styles
import '@asmartbear/gutenberg-bridge/dist/css/full.css';
import '@asmartbear/gutenberg-bridge/dist/css/core-blocks.css';
import '../css/block.css';

// Apply our custom Atlas theme, loading it from the JSON file
import { setThemeFromJSON } from '@asmartbear/gutenberg-bridge/dist/storybookHelper';
setThemeFromJSON(require('../atlas-block-config.json'));

Now, run Storybook locally using npm run storybook, and you'll find all the Atlas blocks, as well as the Gutenberg core blocks, organized by namespace, with appropriate controls:

Storybook for your custom blocks

Your custom blocks will not automatically appear in the list. To create a story for a block, use the following boilerplate code. Create a file in your block's directory called block.stories.tsx, and fill it with this:

// Import your block's React component and Atlas Block definition
import { default as Component, tutorialHelloDefinition as definition } from ".";

// Atlas provides a function that configures everything for you
import { createStoryMeta } from '@asmartbear/gutenberg-bridge/dist/storybookHelper';
export default createStoryMeta(definition);

// Provide a trivial story for Storybook to render
import { Story } from '@storybook/react';
export const TypicalExample: Story = (args) => (
    <Component {...args} />
);

Navigate to tutorial/hello in the Storybook sidebar to see it working.

If your component uses child blocks, you'll need to supply some children for Storybook to display. For example, in our "hello" component, after we added support for child blocks, we'd need to do something like this, to display properly in Storybook:

import { Story } from '@storybook/react';
export const TypicalExample: Story = (args) => (
    <Component {...args}>
        This is a child.
    </Component>
);

Also consider using Atlas Block components for the children, because this is what will actually happen when your block is used in Gutenberg:

import { Prose } from '@asmartbear/gutenberg-bridge/dist/registerAll'
import { Story } from '@storybook/react';
export const TypicalExample: Story = (args) => (
    <Component {...args}>
        <Prose preset="h3" content="This is a child." />
    </Component>
);

Doing more with Storybook

You are not limited to a single, trivial example story! Create additional stories by exporting more examples of type Story. Implement complex logic inside the examples, or automatically generate a bunch of variations for designers to visually compare.

This is still just a normal Storybook story file, so you can still do anything that is valid in the Storybook system. We just made it very easy to set up the basics.