Storybook introduction

Storybook is a powerful open-source tool for developing UI components in isolation. It provides a development environment for UI components, allowing you to build, test, and document components separately from your main application.

Why Storybook is Awesome

Component-Driven Development

Storybook encourages component-driven development, where you build and perfect individual components before assembling them into larger features or pages. This approach leads to more robust and reusable components.

Visual Testing Environment

Storybook provides a dedicated workbench where you can visualize different states of your components without needing to navigate to specific pages in your application. You can easily toggle between different component states, props configurations, and themes.

Interactive Documentation

Beyond just being a development tool, Storybook serves as living documentation for your component library. Team members can browse your Storybook to understand what components are available and how to use them, complete with props documentation and usage examples.

Addon Ecosystem

Storybook has a rich ecosystem of addons that extend its functionality:

• Controls for dynamically adjusting props
• Actions for monitoring event handlers
• Accessibility tools for ensuring components meet accessibility standards
• Viewport tools for testing responsive designs
• And many more

Integration with Testing

Storybook integrates well with testing tools, enabling visual regression testing, interaction testing, and snapshot testing of your components.

Framework Agnostic

Whether you're working with React, Vue, Angular, Svelte, or other frameworks, Storybook works with most major frontend frameworks and libraries.

Collaboration

Storybook can be published and shared with stakeholders like designers, product managers, and other developers, improving collaboration across teams. As you progress in your frontend development journey, Storybook will become an invaluable tool in your workflow, helping you create consistent, well-documented, and thoroughly tested UI components.

Install Storybook on a Next.js project

To install Storybook in a Next.js project, you either need an already existing Next.js project. If you don't, create a new project with following command:

npx create-next-app@latest

And select the following options in the installation:

What is your project names? > (The root folder name of your app)
Would you like to use TypeScript? > Yes
Would you like to use ESLint? > Yes
Would you like to use Tailwind CSS? > Yes/No (based on your preference, here we will mainly use Tailwind CSS)
Would you like your code insida a `src/` directory? > Yes
Would you like to use App Router (recommended)? > Yes
Would you like to use Torbupack for `next dev`? > Yes
Would you like to customize the import alias (`@/*` by default)? > No

Then inside your Next.js project in the terminal type following command:

npm create storybook@latest

And select following options in the Storybook installation:

Documentation: MDX, auto-generated component docs
Do you want to migrate? > (No for the @storybook/experimental-addon-test)

After the installation, ensure to add your globals.css to the Storybook preview, so that we have access to whatever style technology you're using:

import type { Preview } from "@storybook/react";
import "../src/styles/globals.css"; // the path depends where you've put your globals.css

const preview: Preview = {
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
  },
};

export default preview;

That's all there is to it!

Troubleshooting

If Storybook does not seem to work, check your package.json to have the following installed:

{
  ...
  "scripts": {
    ...
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build"
  },
  "devDependencies": {
    "@chromatic-com/storybook": "^3.2.6",
    ...
    "@storybook/addon-essentials": "^8.6.12",
    "@storybook/addon-onboarding": "^8.6.12",
    "@storybook/blocks": "^8.6.12",
    "@storybook/experimental-addon-test": "^8.6.12",
    "@storybook/experimental-nextjs-vite": "^8.6.12",
    "@storybook/nextjs": "^8.6.12",
    "@storybook/react": "^8.6.12",
    "@storybook/test": "^8.6.12",
    ...
  },
  ...
}

And your Storybook main.ts should look like this:

import type { StorybookConfig } from "@storybook/nextjs";

const config: StorybookConfig = {
  stories: ["../src/**/*.mdx", "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
  addons: [
    "@storybook/addon-essentials",
    "@storybook/addon-onboarding",
    "@chromatic-com/storybook",
    "@storybook/experimental-addon-test",
  ],
  framework: {
    name: "@storybook/nextjs",
    options: {},
  },
  staticDirs: ["../public"],
};
export default config;