Skip to main content

Storybook

What is Storybook​

Storybook is an open-source UI component development environment and documentation tool. It is MIT licensed and currently at version 8.x. With ~20M weekly npm downloads and ~86k GitHub stars, it is the industry-standard tool for developing, testing, and documenting UI components in isolation.

Why we recommend it​

  • Isolated component development — build and view components outside your application. Handle edge cases, loading states, and error states without navigating through the full app.
  • Living documentation — stories are executable documentation. Autodocs generates doc pages automatically from your component types and JSDoc comments.
  • Visual & interaction testing — play functions let you write interaction tests directly in stories. Pair with Chromatic for visual regression testing across commits.
  • Accessibility testing — the built-in a11y addon (powered by axe-core) flags accessibility violations as you develop, catching issues before code review.
  • Vite-native (v8+) — Storybook 8 uses Vite as its default builder, aligning with our stack and sharing your existing Vite configuration.
  • TypeScript-first — full TypeScript support with Meta and StoryObj types for type-safe story definitions.

When to use​

  • Component library or design system development
  • Projects with many reusable UI components (dashboards, admin panels, form-heavy apps)
  • Teams where designers review UI independently from the running application
  • When you want visual documentation of component variants and their props
  • When testing components in various states without spinning up the full app — complements Vitest unit tests and Playwright E2E tests

When NOT to use​

  • Small projects with few custom components — the setup and maintenance overhead isn't justified
  • Backend-heavy applications with minimal custom UI
  • Prototypes or throwaway projects where speed matters more than documentation
  • When the team won't commit to maintaining stories — stale stories are worse than no stories
caution

Stories require maintenance. Establish a convention that every new React component ships with a corresponding .stories.tsx file. Without this discipline, your Storybook becomes outdated and loses its value as documentation.

Resources​