Storybook - Configuration

Configure Storybook for optimal development experience with the right addons, builders, and framework integrations.

Key Concepts

Main Configuration

.storybook/main.ts is the primary configuration file:

import type { StorybookConfig } from '@storybook/react-vite';

const config: StorybookConfig = { stories: ['../src//*.mdx', '../src//*.stories.@(js|jsx|mjs|ts|tsx)'], addons: [ '@storybook/addon-essentials', '@storybook/addon-interactions', '@storybook/addon-a11y', ], framework: { name: '@storybook/react-vite', options: {}, }, docs: { autodocs: 'tag', }, };

export default config;

Preview Configuration

.storybook/preview.ts configures how stories are rendered:

import type { Preview } from '@storybook/react'; import '../src/index.css';

const preview: Preview = { parameters: { controls: { matchers: { color: /(background|color)$/i, date: /Date$/i, }, }, }, globalTypes: { theme: { description: 'Global theme for components', defaultValue: 'light', toolbar: { title: 'Theme', icon: 'circlehollow', items: ['light', 'dark'], dynamicTitle: true, }, }, }, };

export default preview;

Addons

Addons extend Storybook functionality:

• @storybook/addon-essentials - Core addons bundle

• @storybook/addon-interactions - Interaction testing

• @storybook/addon-a11y - Accessibility testing

• @storybook/addon-links - Story navigation

• @storybook/addon-coverage - Code coverage

• storybook-dark-mode - Dark mode toggle

Best Practices

1. Use TypeScript Configuration

Type-safe configuration prevents errors:

import type { StorybookConfig } from '@storybook/react-vite';

const config: StorybookConfig = { stories: ['../src//*.mdx', '../src//*.stories.@(ts|tsx)'], addons: [ '@storybook/addon-essentials', '@storybook/addon-interactions', ], framework: { name: '@storybook/react-vite', options: { builder: { viteConfigPath: './vite.config.ts', }, }, }, };

export default config;

2. Configure Story Patterns

Specify where stories are located:

const config: StorybookConfig = { stories: [ '../src//*.mdx', '../src//.stories.@(js|jsx|ts|tsx)', // Include specific directories '../components/**/.stories.tsx', '../features//*.stories.tsx', // Exclude patterns '!../src//*.test.stories.tsx', ], };

3. Enable Autodocs

Generate documentation automatically:

const config: StorybookConfig = { docs: { autodocs: 'tag', // Autodocs for stories with 'autodocs' tag // OR autodocs: true, // Autodocs for all stories }, };

4. Configure Essential Addons

Customize addon behavior in preview:

import type { Preview } from '@storybook/react';

const preview: Preview = { parameters: { // Actions addon actions: { argTypesRegex: '^on[A-Z].*' },

// Controls addon
controls: {
  matchers: {
    color: /(background|color)$/i,
    date: /Date$/i,
  },
  exclude: ['className', 'style'],
},

// Viewport addon
viewport: {
  viewports: {
    mobile: {
      name: 'Mobile',
      styles: { width: '375px', height: '667px' },
    },
    tablet: {
      name: 'Tablet',
      styles: { width: '768px', height: '1024px' },
    },
  },
},

// Backgrounds addon
backgrounds: {
  default: 'light',
  values: [
    { name: 'light', value: '#ffffff' },
    { name: 'dark', value: '#1a1a1a' },
  ],
},

}, };

5. Add Global Decorators

Wrap all stories with providers:

import { Preview } from '@storybook/react'; import { ThemeProvider } from '../src/theme';

const preview: Preview = { decorators: [ (Story) => ( <ThemeProvider> <div style={{ padding: '2rem' }}> <Story /> </div> </ThemeProvider> ), ], };

Common Patterns

Next.js Configuration

import type { StorybookConfig } from '@storybook/nextjs';

const config: StorybookConfig = { stories: ['../src//*.mdx', '../src//*.stories.@(js|jsx|ts|tsx)'], addons: [ '@storybook/addon-essentials', '@storybook/addon-interactions', ], framework: { name: '@storybook/nextjs', options: { nextConfigPath: '../next.config.js', }, }, staticDirs: ['../public'], typescript: { reactDocgen: 'react-docgen-typescript', reactDocgenTypescriptOptions: { shouldExtractLiteralValuesFromEnum: true, propFilter: (prop) => (prop.parent ? !/node_modules/.test(prop.parent.fileName) : true), }, }, };

Vite Configuration

import type { StorybookConfig } from '@storybook/react-vite'; import { mergeConfig } from 'vite';

const config: StorybookConfig = { framework: { name: '@storybook/react-vite', options: {}, }, async viteFinal(config) { return mergeConfig(config, { resolve: { alias: { '@': '/src', }, }, define: { 'process.env.STORYBOOK': JSON.stringify(true), }, }); }, };

Webpack Configuration

import type { StorybookConfig } from '@storybook/react-webpack5'; import path from 'path';

const config: StorybookConfig = { framework: { name: '@storybook/react-webpack5', options: {}, }, webpackFinal: async (config) => { config.resolve = { ...config.resolve, alias: { ...config.resolve?.alias, '@': path.resolve(__dirname, '../src'), }, }; return config; }, };

Accessibility Testing

import type { Preview } from '@storybook/react';

const preview: Preview = { parameters: { a11y: { config: { rules: [ { id: 'color-contrast', enabled: true, }, { id: 'aria-required-attr', enabled: true, }, ], }, options: { runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa'], }, }, }, }, };

Theme Switching

import { Preview } from '@storybook/react'; import { useDarkMode } from 'storybook-dark-mode';

const preview: Preview = { decorators: [ (Story) => { const isDark = useDarkMode(); return ( <ThemeProvider theme={isDark ? darkTheme : lightTheme}> <Story /> </ThemeProvider> ); }, ], };

Code Coverage

import type { StorybookConfig } from '@storybook/react-vite';

const config: StorybookConfig = { addons: [ '@storybook/addon-coverage', ], framework: { name: '@storybook/react-vite', options: {}, }, };

// In .storybook/test-runner.ts import type { TestRunnerConfig } from '@storybook/test-runner';

const config: TestRunnerConfig = { async postRender(page, context) { // Add coverage collection await page.coverage.startJSCoverage(); }, };

export default config;

Advanced Patterns

Multi-Framework Setup

// .storybook/main.react.ts const config: StorybookConfig = { stories: ['../src/react/**/*.stories.tsx'], framework: '@storybook/react-vite', };

// .storybook/main.vue.ts const config: StorybookConfig = { stories: ['../src/vue/**/*.stories.ts'], framework: '@storybook/vue3-vite', };

Custom Addon Development

// .storybook/addons/custom-addon/register.tsx import { addons, types } from '@storybook/manager-api'; import { AddonPanel } from '@storybook/components'; import React from 'react';

addons.register('custom-addon', () => { addons.add('custom-addon/panel', { type: types.PANEL, title: 'Custom Panel', render: ({ active, key }) => ( <AddonPanel active={active} key={key}> <div>Custom addon content</div> </AddonPanel> ), }); });

// .storybook/main.ts const config: StorybookConfig = { addons: ['./addons/custom-addon/register'], };

Manager Configuration

// .storybook/manager.ts import { addons } from '@storybook/manager-api'; import { themes } from '@storybook/theming';

addons.setConfig({ theme: themes.dark, panelPosition: 'right', showPanel: true, selectedPanel: 'storybook/actions/panel', initialActive: 'sidebar', sidebar: { showRoots: true, collapsedRoots: ['other'], }, });

Anti-Patterns

❌ Don't Skip Framework Type

// Bad - No type safety const config = { framework: '@storybook/react-vite', };

// Good - Type-safe import type { StorybookConfig } from '@storybook/react-vite';

const config: StorybookConfig = { framework: { name: '@storybook/react-vite', options: {}, }, };

❌ Don't Hardcode Paths

// Bad const config: StorybookConfig = { stories: [ '/Users/username/project/src/**/*.stories.tsx', ], };

// Good const config: StorybookConfig = { stories: [ '../src/**/*.stories.tsx', ], };

❌ Don't Include Unnecessary Addons

// Bad - Too many addons slow down Storybook const config: StorybookConfig = { addons: [ '@storybook/addon-essentials', '@storybook/addon-actions', // Included in essentials '@storybook/addon-controls', // Included in essentials '@storybook/addon-backgrounds', // Included in essentials ], };

// Good - Just essentials covers most needs const config: StorybookConfig = { addons: [ '@storybook/addon-essentials', '@storybook/addon-a11y', // Additional specialized addon ], };

Related Skills

• storybook-story-writing: Writing stories for configured Storybook

• storybook-component-documentation: Using documentation addons

• storybook-play-functions: Setting up interaction testing addon