Explains how to install and configure react-storybook into a project created from the react-boilerplate setup.
React-boilerplate (rbp) is a good starting point to create React apps, with a focus on performance, best practices and DX.
The community around the repository is amazing and a constant source of learning.
In parallel react-storybook is a great tool to develop and vizualize React components into isolation.
It lets you create component stories in order to mount your components into a gallery-type UI. Each story allows to specify different property values, leading to vizualize the component into different states.
While the basic integration of react-storybook into any kind of project is very easy and the documentation helpful, this post gives some tips to help you with issues like webpack loaders and internationalization support into the context of a project created from the react-boilerplate setup.
The following assumes you have a working copy of react-boilerplate and its default example app.
- Install the getstorybook utility :
npm i -g getstorybook - Run it into your react-boilerplate project directory :
cd my-react-boilerplate-project && getstorybook - Start the storybook local server :
npm run storybook - Now you can navigate to
http://localhost:6006/and see the storybook UI and the default stories generated by the utility
At this point you should be able to change the default stories/index.js file created for you by getstorybook with the following code to show the boilerplate's Button component right into the Storybook UI (auto reloaded !)
import React from 'react';
import { storiesOf, action } from '@kadira/storybook';
import Button from '../app/components/Button';
storiesOf('Button', module)
.add('with text', () => (
<Button onClick={action('clicked')}>Hello Button</Button>
));This is easy isn't it? But unfortunately this works for the Button component, but not for some other components that are part of the react-boilerplate example app.
In the following section, we'll provide some additional details to create a good integration.
Storybook comes with its own Webpack configuration used to process the stories and mount components into the UI.
Obviously this configuration doesn't include all the things included into the react-boilerplate setup.
Let's modify again the stories/index.js file to include a story about the Header component of the rbp example, and see the problem by yourself.
import React from 'react';
import { storiesOf, action } from '@kadira/storybook';
import Button from '../app/components/Button';
import Header from '../app/components/Header';
storiesOf('Button', module)
.add('with text', () => (
<Button onClick={action('clicked')}>Hello Button</Button>
));
storiesOf('Header', module)
.add('default', () => (
<Header />
));In this example the webpack image-loader that is already set into rbp will not be runned by the storybook building process, leading you to this kind of error message Module parse failed: (...)/app/components/Header/banner.jpg Unexpected character '�' (1:0) You may need an appropriate loader to handle this file type.
To fix this problem, you'll need to extend the default storybook webpack configuration to include the same loaders that are used into rbp development or production builds. See the storybook docs for more details.
The .storybook/webpack.config.js file can be modified to look like the following.
const path = require('path');
const baseDir = path.resolve(__dirname, '../app');
// load the dev config from react-boilerplate
const devConfig = require('../internals/webpack/webpack.dev.babel');
module.exports = function genConfig(storybookBaseConfig) {
// concat loaders from dev config
/* eslint-disable no-param-reassign */
storybookBaseConfig.module.loaders = storybookBaseConfig.module
.loaders.concat(devConfig.module.loaders);
// add the "app" folder to the resolve list
storybookBaseConfig.resolve.fallback.push(baseDir);
// return the altered config
return storybookBaseConfig;
};This configuration does the following things:
- Import and merge loaders settings from
internals/webpack/webpack.dev.babelso you'll be sure that components displayed into your storybook will be processed by the same loaders (babel, style-loader, css-loader, file-loader…) that are already in use into the boilerplate. - Add the
appfolder to the webpack resolve fallback option to get correct imports resolution for your files.
You need to stop and restart storybook to apply this modification.
With this webpack configuration for storybook, you should get rid of the error about the Header image, but the component still cannot be rendered correctly and you'll see this message into the storybook UI : [React Intl] Could not find required 'intl' object. <IntlProvider> needs to exist in the component ancestry.
In the following section, we'll see how to avoid this last problem and mount our components that depends on React Intl.
The .storybook/config.js file allows to configure how the stories are loaded and rendered into the Storybook UI.
To render components that used the intl context we need to wrap the story into an IntlProvider component.
You can modify the stories file to include the IntlProvider wrapper, like in the following code (the Button story previously showned was removed for simplicity).
import React from 'react';
import { storiesOf } from '@kadira/storybook';
import { IntlProvider } from 'react-intl';
import { translationMessages } from '../app/i18n';
import Header from '../app/components/Header';
const DEFAULT_LOCALE = 'en';
storiesOf('Header', module)
.add('default', () => (
<IntlProvider locale={DEFAULT_LOCALE} messages={translationMessages[DEFAULT_LOCALE]}>
<Header />
</IntlProvider>
));It's all good now, and you can finally see the Header component into the storybook UI.
But I think it will be more useful to have this setting available for all our components.
Storybook provides an API to wrap all stories into whatever components you want before rendering them into the UI.
This can be done with the addDecorator function that can be used into the global storybook settings.
So you can update the .storybook/config.js file, like into the following snippet.
import React from 'react';
import { configure, addDecorator } from '@kadira/storybook';
import { IntlProvider } from 'react-intl';
// import translation messages
import { translationMessages } from '../app/i18n';
// add a decorator to wrap stories rendering into IntlProvider
const DEFAULT_LOCALE = 'en';
addDecorator((story) => (
<IntlProvider locale={DEFAULT_LOCALE} messages={translationMessages[DEFAULT_LOCALE]}>
{ story() }
</IntlProvider>
));
// stories loader
function loadStories() {
require('../stories');
}
// initialize react-storybook
configure(loadStories, module);Now the Intl support will be available for all our stories, and the stories/index.js file can be reverted to something clearer.
import React from 'react';
import { storiesOf } from '@kadira/storybook';
import Header from './index';
storiesOf('Header', module)
.add('default', () => (
<Header />
));Storybook settings also allow you to set where the tool will be looking for stories.
As the react-boilerplate enforces it, each part of a component (code, styles, tests) should stay in the same place. So you should probably want to keep your stories into each component folder.
With our current setup, storybook will load stories from the stories/index.js file.
Let's modify the "stories loader" part of the .storybook/config.js file to look for all files matching the pattern *.stories.js.
// stories loader
const req = require.context('../app', true, /.stories.js$/);
function loadStories() {
req.keys().forEach((filename) => req(filename));
}
// initialize react-storybook
configure(loadStories, module);You need to stop and restart storybook to apply this modification.
Now we can remove the example stories folder and create a new file named index.stories.js into app/components/Button to write stories for the Button component.
import React from 'react';
import { storiesOf, action } from '@kadira/storybook';
import Button from './index';
storiesOf('Button', module)
.add('with text', () => (
<Button onClick={action('clicked')}>Hello Button</Button>
));And another one into app/components/Header to write stories for the Header component.
import React from 'react';
import { storiesOf } from '@kadira/storybook';
import Header from './index';
storiesOf('Header', module)
.add('default', () => (
<Header />
));Stories definitions can be extended with addons. Available addons are listed into a gallery page.
I found the Info addon (used into the AirBnB react-dates showcase) very useful to display some information about the components and their stories.
Steps to integrate it into our setup are the following.
- Stop the storybook if it's still running (ctrl-c).
- Add the info addon package:
yarn add --dev @kadira/react-storybook-addon-info - Edit the
.storybook/config.jsto import and connect the addon using thesetAddonfunction.
import React from 'react';
import { configure, addDecorator, setAddon } from '@kadira/storybook';
import infoAddon from '@kadira/react-storybook-addon-info';
...
setAddon(infoAddon);
...- Rebuild the dependencies dll:
npm run build:dll - Restart the storybook:
npm run storybook - Now the story for the Button can be modified to use the
addWithInfofunction instead of the defaultadd.
import React from 'react';
import { storiesOf, action } from '@kadira/storybook';
import Button from './index';
storiesOf('Button', module)
.addWithInfo('with text',
`
The default use case for the button component.
`,
() => (
<Button onClick={action('clicked')}>Hello Button</Button>
));The question mark button at the top-right gives access to an info page about the component, its properties and the story.
Like the Info Addon, a nice grid background is rendered into the react-dates storybook.
If you want something similar into your project you can simply add an head.html file into the .storybook directory and fill it with the following content.
<style>
body {
background-color: rgba(0, 0, 0, 0.05);
background-image: repeating-linear-gradient(0deg, transparent, transparent 7px, rgba(0, 0, 0, 0.2) 1px, transparent 8px), repeating-linear-gradient(90deg, transparent, transparent 7px, rgba(0, 0, 0, 0.2) 1px, transparent 8px);
background-size: 8px 8px;
}
</style>Storybook injects tags from head.html into the iFrame used to render your stories/components.
The configuration files are available into this Gist.
👍 Thank you!