Skip to main content

Storybook React: Installation & Setup Guide

Storybook is a development environment and UI workbench that lets you build React components in isolation, independent of your application's routing, state management, or styling. Installing Storybook takes just a few minutes with the official scaffolding CLI, which auto-detects your project structure and installs the correct loaders for your build setup. After setup, you'll have a local dev server running on localhost:6006 with hot module reloading, component browsing, and an add-on ecosystem ready to extend with testing, accessibility, and performance tooling.

How Do You Install Storybook in a React Project?​

The quickest way to install Storybook is to use the official scaffolding command, which detects your React setup and installs the right dependencies and loaders. Run this command in your project root:

npx storybook@latest init

This interactive wizard will:

  • Detect your project type (React, Vue, Angular, etc.) and your build tool (webpack, Vite, TypeScript support).
  • Install @storybook/react, @storybook/addon-essentials, and peer dependencies.
  • Create a .storybook/ folder with configuration files.
  • Generate an example story in src/stories/ to show the pattern.
  • Add a storybook npm script to your package.json.

If you're starting from scratch without a React build tool, Storybook handles that too—it bundles webpack or Vite automatically. For existing projects with Vite, the scaffolder detects it and sets up @storybook/builder-vite instead of webpack, which is faster for development.

What Happens During Storybook Init?​

When you run npx storybook@latest init, the scaffolder creates a .storybook/ directory with two essential files:

.storybook/main.ts (or .js) defines your Storybook configuration:

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

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

export default config;

This configuration tells Storybook:

  • Where to find story files (by glob pattern: src/**/*.stories.tsx).
  • Which add-ons to load (essentials include controls, actions, and viewport plugins).
  • Which framework and build tool to use (@storybook/react-webpack5 or @storybook/builder-vite).
  • How to auto-generate documentation from JSDoc and controls.

.storybook/preview.ts sets up global decorators, theming, and preview settings:

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

const preview: Preview = {
  parameters: {
    layout: 'centered',
    docs: {
      canvas: { sourceState: 'shown' },
    },
  },
  decorators: [
    (Story) => (
      <div style={{ padding: '2rem' }}>
        <Story />
      </div>
    ),
  ],
};

export default preview;

The decorators array wraps every story in common markup (like padding or a theme provider), so you don't repeat it in every story file.

How Do You Start the Storybook Dev Server?​

After init, Storybook adds a script to package.json:

npm run storybook

This spins up a local dev server (usually localhost:6006) with hot module reloading. Open it in your browser and you'll see the Storybook UI: a left panel showing all stories organized by component, a center canvas displaying the selected story, and a right panel with add-on controls (like Props Inspector).

The dev server watches for changes to .stories.tsx files and hot-reloads the preview in real time. If you modify a story's code or a component's source, the story updates instantly without a page refresh.

Configuring TypeScript in Storybook​

If your React project uses TypeScript, Storybook auto-detects tsconfig.json and compiles .stories.ts files correctly. However, you may want to ensure type safety for your story meta and args. Update .storybook/main.ts to use TypeScript:

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

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

export default config;

Setting typescript.check to true tells Storybook's Webpack loader to validate TypeScript syntax in story files during the build, catching type errors before runtime.

Setting Up CSS and Tailwind​

By default, Storybook imports CSS from your project. If you use Tailwind CSS, import it in .storybook/preview.ts:

import '../src/index.css'; // Your Tailwind imports

const preview: Preview = {
  parameters: {
    layout: 'centered',
  },
};

export default preview;

If you have scoped or modular CSS, Storybook's webpack configuration handles it automatically. For advanced styling setups (emotion, styled-components, or CSS-in-JS libraries), the scaffolder detects these and configures the loaders.

Verifying Your Installation​

After running npm run storybook, open localhost:6006 in your browser. You should see the Storybook UI with at least one example story (typically a Button component). Click the story in the sidebar and verify:

  1. The component renders in the center canvas.
  2. The right panel shows "Controls" and allows you to toggle props.
  3. The sidebar shows story organization (grouped by component).

If you see errors in the browser console, check:

  • Is src/stories/ populated with .stories.tsx files?
  • Do your components import correctly (no missing CSS or peer dependencies)?
  • Is your Node version 16+? (Storybook 7.x requires Node 16 or later.)

Key Takeaways​

  • One-command setup: npx storybook@latest init auto-detects your project and installs all dependencies and loaders.
  • .storybook/main.ts defines behavior: Story glob patterns, add-ons, framework, and build tool configuration live here.
  • .storybook/preview.ts sets global context: Decorators, theme providers, and global parameters are added here.
  • Dev server hot-reloads: npm run storybook starts a live dev server on localhost:6006 that reloads as you edit story files.
  • TypeScript supported out-of-the-box: Enable type checking in main.ts for caught errors before build time.
  • CSS and Tailwind auto-imported: Storybook detects your styling setup and configures loaders automatically; import global CSS in preview.ts if needed.

Frequently Asked Questions​

What Node version does Storybook require?​

Storybook 7.x and later require Node 16.0 or higher; Node 18+ is recommended for faster builds and better compatibility with modern tooling. Check your Node version with node --version and upgrade via nvm or your system's Node package manager if needed.

Can I use Storybook with a Vite-based React project?​

Yes. If your project uses Vite, the scaffolder auto-detects it and installs @storybook/builder-vite, which builds stories faster than webpack. Vite support is stable in Storybook 7.x and later, offering build times 5–10 times faster than webpack for development.

How do I exclude certain files from Storybook?​

In .storybook/main.ts, modify the stories glob to exclude patterns. For example, to exclude test files: stories: ['../src/**/*.stories.@(ts|tsx)', '!../src/**/*.test.ts']. However, the best practice is to use a naming convention like *.stories.tsx exclusively for story files.

Does Storybook support environment variables?​

Yes. Storybook reads from .env and .env.local at build time. Prefix variables with STORYBOOK_ (e.g., STORYBOOK_API_URL=https://api.example.com) for them to be available in stories via process.env.STORYBOOK_API_URL.

Further Reading​