Setup Storybook
Now that youβve learned what stories are and how to browse them, letβs demo working on one of your components.
Pick a simple component from your project, like a Button, and write a .stories.js
, or a .stories.ts
file to go along with it. It might look something like this:
Go to your Storybook to view the rendered component. Itβs OK if it looks a bit unusual right now.
Depending on your technology stack, you also might need to configure the Storybook environment further.
Render component styles
Storybook isnβt opinionated about how you generate or load CSS. It renders whatever DOM elements you provide. But sometimes, things wonβt βlook rightβ out of the box.
You may have to configure your CSS tooling for Storybookβs rendering environment. Here are some setup guides for popular tools in the community.
Don't see the tool that you're looking for? Check out the styling and css page for more details.
Configure Storybook for your stack
Storybook comes with a permissive default configuration. It attempts to customize itself to fit your setup. But itβs not foolproof.
Your project may have additional requirements before components can be rendered in isolation. This warrants customizing configuration further. There are three broad categories of configuration you might need.
Build configuration like Webpack and Babel
If you see errors on the CLI when you run the yarn storybook
command, you likely need to make changes to Storybookβs build configuration. Here are some things to try:
- Presets bundle common configurations for various technologies into Storybook. In particular, presets exist for Create React App and Ant Design.
- Specify a custom Babel configuration for Storybook. Storybook automatically tries to use your projectβs config if it can.
- Adjust the Webpack configuration that Storybook uses. Try patching in your own configuration if needed.
Runtime configuration
If Storybook builds but you see an error immediately when connecting to it in the browser, in that case, chances are one of your input files is not compiling/transpiling correctly to be interpreted by the browser. Storybook supports evergreen browsers, but you may need to check the Babel and Webpack settings (see above) to ensure your component code works correctly.
Component context
If a particular story has a problem rendering, often it means your component expects a specific environment is available to the component.
A common frontend pattern is for components to assume that they render in a specific βcontextβ with parent components higher up the rendering hierarchy (for instance, theme providers).
Use decorators to βwrapβ every story in the necessary context providers. The .storybook/preview.js
file allows you to customize how components render in Canvas, the preview iframe. See how you can wrap every component rendered in Storybook with Styled Components ThemeProvider
, Vue's Fontawesome, or with an Angular theme provider component in the example below.
Load assets and resources
If you want to link to static files in your project or stories (e.g., /fonts/XYZ.woff
), use the -s path/to/folder
flag to specify a static folder to serve from when you start up Storybook. To do so, edit the storybook
and build-storybook
scripts in package.json
.
We recommend serving external resources and assets requested in your components statically with Storybook. It ensures that assets are always available to your stories.