Storybook Addons: Performance & Visual Debugging

Storybook's add-on ecosystem extends core features with specialized tools for performance analysis, visual debugging, design token inspection, and component documentation. The default @storybook/addon-essentials bundle includes Controls, Actions, Viewports, and Docs. Additional add-ons like @storybook/addon-measure (for spacing and layout inspection), @storybook/addon-designs (for design file integration), and community packages like @storybook/addon-performance help you test components holistically without leaving the Storybook UI. This article covers the most impactful add-ons for React development and how to configure them.

Essential Add-ons Included by Default

When you install Storybook, @storybook/addon-essentials includes:

• Controls: Interactive form fields for props (covered in Article 3).
• Actions: Log callback invocations in a side panel.
• Viewport: Render stories at different screen sizes and device breakpoints.
• Docs: Auto-generate documentation from stories and JSDoc.
• Highlights: Visually outline components and guide the eye.

These cover most use cases. However, you can install additional add-ons for specialized needs.

Measuring Spacing and Layout with addon-measure

The @storybook/addon-measure add-on displays rulers and guides on your story, showing pixel measurements, spacing, and alignment. Install it:

npm install --save-dev @storybook/addon-measure

Add it to .storybook/main.ts:

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(ts|tsx)'],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-measure',
  ],
  framework: '@storybook/react-webpack5',
};

export default config;

In Storybook, click the measure icon in the top toolbar. A ruler appears on the component's edges showing:

• Element dimensions: Width and height in pixels.
• Spacing: Padding and margin values.
• Guides: Alignment lines for layout analysis.

This is invaluable when checking if spacing matches your design system (e.g., 16px padding) or debugging unexpected margins.

Analyzing Performance with addon-performance

The @storybook/addon-performance add-on measures render time and detects performance bottlenecks:

npm install --save-dev @storybook/addon-performance

Add to .storybook/main.ts:

const config: StorybookConfig = {
  addons: [
    '@storybook/addon-essentials',
    {
      name: '@storybook/addon-performance',
      options: {
        minPassTime: 100, // Story must render in <100ms to pass
      },
    },
  ],
};

export default config;

Open the Performance tab (in the right panel) and the add-on displays:

• Render time: How long React took to render the component.
• Pass/fail badge: Does render time meet your threshold (100ms default)?
• Performance profile: Detailed breakdown of React rendering phases.

For a Button component rendering in 5ms, you'll see a green pass badge. For a complex Data Table taking 350ms, you'll see a red fail badge, prompting optimization investigation.

Inspecting Design Tokens with addon-design-tokens

If your design system uses design tokens (reusable color, spacing, typography values), the @storybook/addon-design-tokens add-on displays them:

npm install --save-dev @storybook/addon-design-tokens

Configure it in .storybook/preview.ts:

import { withDesignTokens } from '@storybook/addon-design-tokens';
import { tokens } from '../src/design/tokens.json';

const preview: Preview = {
  decorators: [withDesignTokens(tokens)],
};

export default preview;

Create a src/design/tokens.json file with your design tokens:

{
  "colors": {
    "primary": "#3498db",
    "success": "#2ecc71",
    "danger": "#e74c3c"
  },
  "spacing": {
    "xs": "4px",
    "sm": "8px",
    "md": "16px",
    "lg": "32px"
  },
  "typography": {
    "fontSize": {
      "xs": "12px",
      "sm": "14px",
      "md": "16px",
      "lg": "20px"
    }
  }
}

Open the Design Tokens panel and see all tokens organized by category. Click a token to apply it to your story's CSS, verifying that components use the correct values.

Integrating Designs with addon-designs

Link Figma or Sketch designs directly to stories using @storybook/addon-designs:

npm install --save-dev @storybook/addon-designs

Add to .storybook/main.ts:

const config: StorybookConfig = {
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-designs',
  ],
};

export default config;

Link a design file in your story's parameters:

export const Primary: Story = {
  args: { label: 'Click me', variant: 'primary' },
  parameters: {
    design: {
      type: 'figma',
      url: 'https://www.figma.com/file/ABC123/Design-System?node-id=45%3A120',
    },
  },
};

In Storybook, open the Design tab and the Figma design appears embedded alongside the story. Designers and developers can compare the implementation to the design without context-switching.

Creating Custom Add-ons

For project-specific needs, you can create a minimal custom add-on. Here's an example that displays custom metadata:

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

interface CustomPanelProps {
  active: boolean;
}

const CustomPanel: React.FC<CustomPanelProps> = ({ active }) => (
  <div style={{ padding: '1rem' }}>
    <h3>Custom Metadata</h3>
    <p>Author: Dr. Alex Turner</p>
    <p>Last reviewed: 2026-06-02</p>
  </div>
);

addons.register('custom/metadata', () => {
  addons.addPanel('custom/metadata/panel', {
    title: 'Metadata',
    match: ({ viewMode }) => viewMode === 'story',
    render: CustomPanel,
  });
});

export const ADDON_ID = 'custom/metadata';
export const PANEL_ID = `${ADDON_ID}/panel`;

Register it in .storybook/main.ts:

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

export default config;

Custom add-ons can display test results, component statistics, or team-specific information directly in the Storybook UI.

Add-on Configuration Best Practices

Add-on	Use Case	Install Command
addon-essentials	Controls, Actions, Docs, Viewports	Installed by default
addon-measure	Spacing and layout inspection	npm install --save-dev @storybook/addon-measure
addon-performance	Render time and performance tracking	npm install --save-dev @storybook/addon-performance
addon-a11y	Accessibility audits (Article 5)	npm install --save-dev @storybook/addon-a11y
addon-designs	Figma/Sketch design embedding	npm install --save-dev @storybook/addon-designs
addon-design-tokens	Design token visualization	npm install --save-dev @storybook/addon-design-tokens

Install only add-ons your team actively uses—each adds to Storybook's build time and bundle size.

Disabling Add-ons at Runtime

You can disable specific add-ons on a per-story basis if they cause issues:

export const NoMeasure: Story = {
  args: { label: 'Button' },
  parameters: {
    measure: { disable: true },
    performance: { disable: true },
  },
};

This prevents the Measure and Performance add-ons from running on this story, useful for stories with known rendering quirks.

Key Takeaways

• addon-measure: Display rulers and spacing guides; verify components match design system spacing values.
• addon-performance: Track render time; catch slow components before shipping to production.
• addon-design-tokens: Centralize and visualize design tokens; verify components use correct values.
• addon-designs: Embed Figma/Sketch designs in Storybook; compare implementation to design instantly.
• Custom add-ons: Build specialized panels for team-specific metadata, test results, or component statistics.
• Performance matters: Only install add-ons your team uses regularly; each adds build time and bundle bloat.

Frequently Asked Questions

Does installing add-ons slow down Storybook's build time?

Yes, slightly. Each add-on adds 1–5 seconds to the initial build. For a typical project with 8–10 add-ons, expect 20–30 seconds build time. Vite builder is faster than webpack. Uninstall unused add-ons to speed up development.

Can I share custom add-ons across multiple projects?

Yes. Publish your add-on as an npm package and install it in other projects. Follow Storybook's add-on API and readme format so other developers can configure it easily.

How do I debug an add-on that's not showing up?

Check the browser console for errors. Ensure the add-on is installed (npm list @storybook/addon-xxx), registered in .storybook/main.ts, and the Storybook server is restarted. Use npm run storybook -- --debug for verbose logging.

Is addon-performance a replacement for Lighthouse or Web Vitals monitoring?

No. addon-performance measures component render time in isolation. Lighthouse and Web Vitals measure full-page performance, third-party scripts, and real-user metrics. Use both: addon-performance for component-level optimization, Lighthouse for production pages.

Further Reading

• Storybook Add-ons Directory
• Creating Storybook Add-ons
• addon-performance Documentation
• Design Tokens with Storybook