Configure Storybook
Storybook is configured via a folder called .storybook
, which contains various configuration files.
Note that you can change the folder that Storybook uses by setting the -c
flag to your start-storybook
and build-storybook
scripts.
Configure your Storybook project
The main configuration file is main.js
. This file controls the Storybook server's behavior, so you must restart Storybook’s process when you change it. It contains the following:
// Imports the Storybook's configuration API
import type { StorybookConfig } from '@storybook/core-common';
const config: StorybookConfig = {
stories: ['../src/**/*.stories.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
staticDirs: ['../public'],
addons: [
'@storybook/addon-links',
'@storybook/addon-essentials',
'@storybook/preset-create-react-app',
'@storybook/addon-interactions',
],
typescript: {
check: false,
checkOptions: {},
reactDocgen: 'react-docgen-typescript',
reactDocgenTypescriptOptions: {
shouldExtractLiteralValuesFromEnum: true,
propFilter: (prop) => (prop.parent ? !/node_modules/.test(prop.parent.fileName) : true),
},
},
framework: '@storybook/react',
core: {
builder: 'webpack4',
},
features: {
postcss: false,
},
refs: {
'design-system': {
title: 'Storybook Design System',
url: 'https://5ccbc373887ca40020446347-yldsqjoxzb.chromatic.com',
},
},
babel: async (options) => ({
// Update your babel configuration here
...options,
}),
webpackFinal: async (config, { configType }) => {
// Make whatever fine-grained changes you need
// Return the altered config
return config;
},
};
module.exports = config;
The main.js
configuration file is a preset and, as such, has a powerful interface, but the key fields within it are:
stories
- an array of globs that indicates the location of your story files, relative tomain.js
.addons
- a list of the addons you are using.webpackFinal
- custom webpack configuration.babel
- custom babel configuration.framework
- framework specific configurations to help the loading and building process.
Customize your default story by referencing it first in the stories
array.
See all the available fields below if you need further customization.
Feature flags
Additionally, you can also provide additional feature flags to your Storybook configuration. Below is an abridged list of available features that are currently available.
Configuration element | Description |
---|---|
storyStoreV7 | Configures Storybook to load stories on demand, rather than during boot up. features: { storyStoreV7: true } |
buildStoriesJson | Generates a stories.json file to help story loading with the on demand mode. features: { buildStoriesJson: true } |
emotionAlias | Provides backwards compatibility for Emotion. See the migration documentation for context.features: { emotionAlias: false } |
babelModeV7 | Enables the new Babel configuration mode for Storybook. features: { babelModeV7: true } |
postcss | Disables the implicit PostCSS warning. See the migration documentation for context. features: { postcss: false } |
modernInlineRender | Enables Storybook's modern inline rendering mode. features: { modernInlineRender: false } |
previewMdx2 | Enables experimental support for MDX 2.features: { previewMdx2: true } |
Configure story loading
By default, Storybook will load stories from your project based on a glob (pattern matching string) in .storybook/main.js
that matches all files in your project with extension .stories.*
. The intention is you colocate a story file with the component it documents.
•
└── components
├── Button.js
└── Button.stories.js
If you want to use a different naming convention, you can alter the glob using the syntax supported by picomatch.
For example, if you wanted to pull both .md
and .js
files from the my-project/src/components
directory, you could write:
module.exports = {
stories: ['../my-project/src/components/*.@(js|md)'],
};
With a configuration object
Additionally, you can customize your Storybook configuration to load your stories based on a configuration object. For example, if you wanted to load your stories from a packages
directory, you could adjust your stories
configuration field into the following:
module.exports = {
stories: [
{
// 👇 The directory field sets the directory your stories
directory: '../packages/stories',
// 👇 The titlePrefix field will generate automatic titles for your stories
titlePrefix: 'MyComponents',
// 👇 Storybook will load all files that contain the stories extension
files: '*.stories.*',
},
],
addons: ['@storybook/addon-essentials'],
};
When Storybook starts, it will look for any file containing the stories
extension inside the packages/stories
directory and generate the titles for your stories.
With a directory
You can also simplify your Storybook configuration and load the stories based on a directory. For example, if you want to load all the stories inside a packages/MyStories
, you can adjust the configuration as such:
module.exports = {
// 👇 Storybook will load all existing stories within the MyStories folder
stories: ['../packages/MyStories'],
addons: ['@storybook/addon-essentials'],
};
With a custom implementation
You can also adjust your Storybook configuration and implement your custom logic for loading your stories. For example, suppose you were working on a project that includes a particular pattern that the conventional ways of loading stories could not solve, in that case, you could adjust your configuration as follows:
function findStories() {
// your custom logic returns a list of files
}
module.exports = {
stories: async (list) => [...list, ...findStories()],
addons: ['@storybook/addon-essentials'],
};
On-demand story loading
As your Storybook grows in size, it gets challenging to load all of your stories in a performant way, slowing down the loading times and yielding a large bundle. Starting with Storybook 6.4, you can optimize your story loading by enabling the storyStoreV7
feature flag in your configuration as follows:
module.exports = {
stories: [],
addons: ['@storybook/addon-essentials'],
features: {
storyStoreV7: true,
},
};
Once you've restarted your Storybook, you'll see an almost immediate performance gain in your loading times and also a decrease in the generated bundle.
Known limitations
This feature is experimental, and it has some limitations on what you can and cannot do in your stories files. If you plan to use it, you'll need to take into consideration the following limitations:
- CSF formats from version 1 to version 3 are supported. The
storiesOf
construct is not. - Custom
storySort
functions are allowed based on a restricted API.
Configure your project with TypeScript
If you need, you can also configure your Storybook using TypeScript. To get started, add a .babelrc
file inside your project and include the following Babel presets:
Rename your .storybook/main.js
to .storybook/main.ts
and restart your Storybook.
{
"presets": [
"@babel/preset-env",
"@babel/preset-typescript"
]
}
Using Storybook API
You can also use Storybook's API to configure your project with TypeScript. Under the hood, it mirrors the exact configuration you get by default. Below is an abridged Storybook configuration with TypeScript and additional information about each configuration element.
// Imports the Storybook's configuration API
import type { StorybookConfig } from '@storybook/core-common';
const config: StorybookConfig = {
stories: ['../src/**/*.stories.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
staticDirs: ['../public'],
addons: [
'@storybook/addon-links',
'@storybook/addon-essentials',
'@storybook/preset-create-react-app',
'@storybook/addon-interactions',
],
typescript: {
check: false,
checkOptions: {},
reactDocgen: 'react-docgen-typescript',
reactDocgenTypescriptOptions: {
shouldExtractLiteralValuesFromEnum: true,
propFilter: (prop) => (prop.parent ? !/node_modules/.test(prop.parent.fileName) : true),
},
},
framework: '@storybook/react',
core: {
builder: 'webpack4',
},
features: {
postcss: false,
},
refs: {
'design-system': {
title: 'Storybook Design System',
url: 'https://5ccbc373887ca40020446347-yldsqjoxzb.chromatic.com',
},
},
babel: async (options) => ({
// Update your babel configuration here
...options,
}),
webpackFinal: async (config, { configType }) => {
// Make whatever fine-grained changes you need
// Return the altered config
return config;
},
};
module.exports = config;
Configuration element | Description |
---|---|
stories | The array of globs that indicates the location of your story files, relative to main.ts |
staticDirs | Sets a list of directories of static files to be loaded by Storybook staticDirs:['../public'] |
addons | Sets the list of addons loaded by Storybook addons:['@storybook/addon-essentials'] |
typescript | Configures how Storybook handles TypeScript files typescript: { check: false, checkOptions: {} } |
framework | Configures Storybook based on a set of framework-specific settings framework:'@storybook/svelte' |
core | Configures Storybook's internal features.core: { builder: 'webpack5' } |
features | Enables Storybook's additional features. See table below for a list of available features features: { storyStoreV7: true } |
refs | Configures Storybook composition refs:{ example: { title: 'ExampleStorybook', url:'https://your-url.com' } } |
logLevel | Configures Storybook's logs in the browser terminal. Useful for debugging logLevel: 'debug' |
webpackFinal | Customize Storybook's Webpack setup webpackFinal: async (config:any) => { return config; } |
env | Defines custom Storybook environment variables. env: (config) => ({...config, EXAMPLE_VAR: 'Example var' }), |
Configure story rendering
To control the way stories are rendered and add global decorators and parameters, create a .storybook/preview.js
file. This is loaded in the Canvas tab, the “preview” iframe that renders your components in isolation. Use preview.js
for global code (such as CSS imports or JavaScript mocks) that applies to all stories.
The preview.js
file can be an ES module and export the following keys:
decorators
- an array of global decoratorsparameters
- an object of global parametersglobalTypes
- definition of globalTypes
If you’re looking to change how to order your stories, read about sorting stories.
Configure Storybook’s UI
To control the behavior of Storybook’s UI (the “manager”), you can create a .storybook/manager.js
file.
This file does not have a specific API but is the place to set UI options and to configure Storybook’s theme.