storybook-configuration
Use when setting up or configuring Storybook for a project. Covers main configuration, addons, builders, and framework-specific setup.
When & Why to Use This Skill
This Claude skill streamlines the setup and optimization of Storybook for modern web development projects. It provides comprehensive guidance on configuring main settings, preview environments, and framework-specific builders such as Vite, Webpack, and Next.js. By automating complex configuration tasks and enforcing best practices for addons and TypeScript integration, it ensures a robust environment for component-driven development and UI testing.
Use Cases
- Project Initialization: Rapidly bootstrap Storybook in new projects with optimized configurations for React, Next.js, or Vue.
- Addon Integration: Seamlessly configure essential addons for accessibility (a11y), interaction testing, and documentation to enhance the development workflow.
- Build Optimization: Fine-tune Vite or Webpack configurations within Storybook to improve HMR speed and resolve path aliasing issues.
- Global Decorator Setup: Implement global providers, themes, and layout wrappers to ensure components are tested in realistic application contexts.
- Automated Documentation: Configure Autodocs and property filtering to generate clean, professional component libraries automatically.
| name | storybook-configuration |
|---|---|
| description | Use when setting up or configuring Storybook for a project. Covers main configuration, addons, builders, and framework-specific setup. |
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