Storybook - Configuration

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