Adding Docs with Storybook

Now that you’re sharing our project with the world, you should think about taking the documentation to the next level. Storybook^[79] has rapidly become a popular library for generating documentation pages for React components. Using Storybook, you can integrate live examples with all the information devs need to take full advantage of your components.

Getting Started with Storybook

Storybook has a handy script that you can run with npx to get started:

Once that script finishes, you’ll see that you have some new devDependencies:

And two new scripts:

The script also added two new directories, .storybook and stories. The .storybook directory contains configuration, and the stories directory is where your documentation will live. The script generated some placeholder documentation in stories/index.stories.js.

Run the storybook script to start it up:

Under the hood, Storybook spun up a webpack server instance. Note that it’s using its own built-in configuration, not the webpack.config.js from the project root.

Open the link to see the Storybook page. (In VS Code, you can open links shown in the integrated terminal using ⌘-click on macOS, ⌃-click on Windows and Linux.) You should see a nice welcome screen in your browser with a handy link to the Storybook documentation on writing stories.^[80]

To see the Carousel component on this page, replace the placeholder documentation in stories.index.js with your own:

Moments after you save that, the change should immediately appear in the browser. Storybook’s webpack server comes configured out of the box for hot module reloading (HMR), making updates very fast: the page receives the new JavaScript modules without having to refresh.

This is a good time for a commit:

Now you have a Storybook page that shows Carousel in action. But if that’s all there was to it, there wouldn’t be much reason to use Storybook instead of the project’s existing example server. So let’s find out what else Storybook can do!

Enhancing Stories with Addons

The magic of Storybook is its extensibility, in the form of assorted addons.^[81] There are abundant options for making your documentation richer through these handy plugins.

Let’s start with the Actions addon. This will add a panel to the bottom of the page for reporting events. We’ll use it to display onIndexChange events. Start by installing the addon from npm:

Then create a new file called .storybook/addons.js and add this line to register the new addon:

The webpack server watches existing files for updates, but won’t recognize new files, so you’ll need to restart it before continuing.

Now add a bit of code to the Carousel story to tell the addon to listen for onIndexChange:

With that change, you should see a new “Action Logger” panel at the bottom of the example page. Every time onIndexChange fires, either because you clicked the Prev/Next buttons or because the slides auto-advanced, the panel shows onIndexChange and the object that the listener received. It brings the API to life!

Let’s try one more addon: Knobs. This one provides controls so that people can adjust the example’s props directly from the page. We’ll use it to make autoAdvanceDelay customizable. Install it from npm:

As with the Actions addon, Knobs requires you to register it:

Then use it to create a numeric control that sets the autoAdvanceDelay prop:

Now the page should have a second panel containing an input that you can use to change how quickly slides auto-advance, as shown in the following screenshot. Set it to 200 for a frenetic, 5-slides-per-second experience. Set it to 0 to disable it entirely.

Cool story, right? There’s just one more thing we’re going to do with it: publish!

Deploying to GitHub Pages

So far, we’ve been using Storybook in dev server mode. It’s time to put the project’s story on the web where the world can see it! Shut down the dev server, then make one change to package.json: add the args -o docs to the build-storybook script. This gives us our final package.json for the chapter:

Like the dist directory, the docs directory is going to include some generated code that doesn’t abide by our formatting standards, so add it to the project’s .eslintignore and .prettierignore:

Now run the script:

This will generate a static web version of the project’s storybook in the docs directory we specified. (The particular choice of directory is important, for reasons that will become clear momentarily.) Once the script completes, create a commit with the new directory:

Then push that commit:

Now let’s ask GitHub to host our new docs for us. Open the project’s GitHub page and go to Settings. Scroll down to the “GitHub Pages” section. For the source, choose “master branch /docs folder,” then click Save as shown in the screenshot.

It may take a minute or two for GitHub to publish your page. You’ll see a link from the project’s Settings page to it. The address should be something like yourname.github.io/test-driven-carousel. Once it goes live, it should look exactly like your local Storybook page. Now every time you push changes to the docs directory on master, GitHub will update the project’s documentation site.

As it is, this setup has one problem: if you make changes to the project but forget to run the build-storybook script, the docs will become stale. There are a couple of possible solutions to this. One possibility is to add a Husky hook to package.json, e.g.:

That would be a bit of a nuisance for developers, who would have to wait on the build every time they commit a change. An ideal solution would be for Travis to take care of it. That requires a few extra steps. First, you’ll want to go into the GitHub repo’s settings and switch to using the gh-pages as the source of the docs; that will avoid the possibility of an infinite loop where Travis sees changes to master, rebuilds the docs, pushes the new docs to master, sees changes to master, etc. From there, follow Travis CI’s guide to GitHub Pages deployment.^[82]