Skip to content

Latest commit

 

History

History
171 lines (115 loc) · 10.7 KB

overview.md

File metadata and controls

171 lines (115 loc) · 10.7 KB
Raw
title
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 storybook dev and storybook build CLI commands.

Configure your Storybook project

Storybook's main configuration (i.e., the main.js|ts) defines your Storybook project's behavior, including the location of your stories, the addons you use, feature flags and other project-specific settings. This file should be in the .storybook folder in your project's root directory. You can author this file in either JavaScript or TypeScript. Listed below are the available options and examples of how to use them.

<CodeSnippets paths={[ 'common/main-config-typical.js.mdx', 'common/main-config-typical.ts.mdx', ]} />

ℹ️ This configuration file is a preset and, as such, has a powerful interface, which can be further customized. Read our documentation on writing presets to learn more.

Configuration element Description
stories The array of globs that indicates the location of your story files, relative to main.js
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: { name: '@storybook/svelte-vite', options:{} }
core Configures Storybook's internal features
core: { disableTelemetry: true, }
docs Configures Storybook's auto-generated documentation
docs: { autodocs: 'tag' }
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; }
viteFinal Customize Storybook's Vite setup when using the vite builder
viteFinal: async (config: Vite.InlineConfig, options: Options) => { return config; }
env Defines custom Storybook environment variables.
env: (config) => ({...config, EXAMPLE_VAR: 'Example var' }),

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 (defaults to true as of v7.0)
features: { storyStoreV7: true }
buildStoriesJson Generates index.json and stories.json files to help story loading with the on-demand mode (defaults to true when storyStoreV7 is true)
features: { buildStoriesJson: true }
legacyMdx1 Enables support for MDX version 1 as a fallback. Requires @storybook/mdx1-csf
features: { legacyMdx1: true }

Configure story loading

By default, Storybook will load stories from your project based on a glob (pattern matching string) in .storybook/main.js|ts that matches all files in your project with extension .stories.*. The intention is for you to colocate a story file along 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:

<CodeSnippets paths={[ 'common/storybook-main-js-md-files.js.mdx', 'common/storybook-main-js-md-files.ts.mdx', ]} />

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/components directory, you could adjust your stories configuration field into the following:

<CodeSnippets paths={[ 'common/main-config-stories-with-object.js.mdx', 'common/main-config-stories-with-object.ts.mdx', ]} />

When Storybook starts, it will look for any file containing the stories extension inside the packages/components directory and generate the titles for your stories.

With a directory

You can also simplify your Storybook configuration and load the stories using a directory. For example, if you want to load all the stories inside a packages/MyStories, you can adjust the configuration as such:

<CodeSnippets paths={[ 'common/storybook-storyloading-with-directory.js.mdx', 'common/storybook-storyloading-with-directory.ts.mdx', ]} />

With a custom implementation

You can also adjust your Storybook configuration and implement custom logic to load 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:

<CodeSnippets paths={[ 'common/main-config-stories-with-logic.js.mdx', 'common/main-config-stories-with-logic.ts.mdx', ]} />

On-demand story loading

As your Storybook grows, it gets challenging to load all of your stories performantly, slowing down the loading times and yielding a large bundle. Out of the box, Storybook loads your stories on demand rather than during boot-up to improve the performance of your Storybook. If you need to load all of your stories during boot-up, you can disable this feature by setting the storyStoreV7 feature flag to false in your configuration as follows:

<CodeSnippets paths={[ 'common/main-config-features-story-store-v7.js.mdx', 'common/main-config-features-story-store-v7.ts.mdx', ]} />

Known limitations

Because of the way stories are currently indexed in Storybook, loading stories on demand with storyStoreV7 has a couple of minor limitations at the moment:

  • CSF formats from version 1 to version 3 are supported. The storiesOf construct is not.
  • CustomstorySort functions are allowed based on a restricted API.

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 UI, 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:

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.