Storybookとは？使い方をv10.6で解説｜導入・Next.js連携・CSF Next・テスト

Storybookの使い方を、2026年10月26日公開の最新版10.6.4を前提に、インストールから最初のストーリー、Next.jsとの連携、Vitestでのテスト、CI組み込みまで順に解説します。検索で上位に出る解説の多くはStorybook 6〜7時代（2018〜2024年）に書かれたもので、storiesOf 記法や addon-essentials の追加手順は今のStorybookでは動きません。次のメジャー版であるStorybook 11（2026年10月時点でアルファ版）で変わる点も先回りして押さえます。

まとめ：Storybookの使い方の要点

• Storybookとは：UIコンポーネントをアプリから切り離して単体で描画し、そのまま文書化・テストに回す開発環境。本体はMITライセンスで無償。
• 導入：プロジェクトのルートで npm create storybook@latest。10系はNode.js 20.19以上または22.12以上が必要で、設定ファイルはESMで書く。
• 起動と共有：npm run storybook で開発サーバー（生成されるスクリプトはポート6006を指定）、npm run build-storybook で静的サイトを storybook-static/ に出力。
• 書き方：既定はCSF3（default exportのメタ＋named exportのストーリー）。型推論を強めたCSF NextはReact・Vue・Angular・Web Componentsでプレビュー提供中。
• Next.js：公式推奨は @storybook/nextjs-vite。Server Componentsは実験フラグ experimentalRSC で描画できる。
• テスト：play関数を @storybook/addon-vitest がVitestのブラウザモードで実行する。Webpack系フレームワークでは使えない。
• Storybook 11：Node.js 22.12以上・TypeScript 5.9以上・Next.js 15以上が必要になり、test-runnerの公式サポートは終わる。

Storybookとは｜UIを隔離して開発・文書化・テストする環境

Storybookは、React・Vue・Angular・Svelte・Web Componentsなどで書いたUIコンポーネントを、ルーティングやAPI通信から切り離して単体で描画する開発環境です。ボタンの「通常」「無効」「読み込み中」のように、コンポーネントが取りうる状態を1つずつ「ストーリー」として書くと、サイドバーから選ぶだけでその状態を再現できます。ログイン後の深い画面にしか出ないエラー表示も、固定の入力値で呼び出せます。

書いたストーリーは、開発中の確認、propsの型から起こす自動生成ドキュメント、インタラクションテストと見た目の差分検出の入力に再利用されます。ここが単なるコンポーネントカタログとの違いです。国内ではデジタル庁デザインシステムのStorybookとGitHub｜React 19版・Figma v2.18.2の入手と取り込み手順のように、公開コンポーネント集の閲覧基盤として使われています。

守備範囲の外にあるものも先に押さえておきます。画面遷移をまたぐE2Eテスト、APIサーバーとの結合検証、本番アプリのビルドはStorybookの役割ではありません。FigmaのデザインデータとStorybookも自動では同期しないため、デザイントークンや命名規則を人が決めて実装へ落とす運用が要ります。何をコンポーネントとして切り出すかの指針はアトミックデザインとは？5階層の分類基準とReactコンポーネント設計・3階層縮退が土台になります。

Storybook 10.6の動作要件と11で変わる点（2026年10月時点）

10系の現行版と、古い記事の手順が動かない理由

npmレジストリでは、storybook パッケージの latest は10.6.4（2026年10月26日公開）、next タグは11.0.0-alpha.8 です。10.0.0は2025年10月28日の公開で、10.6.0（2026年9月2日）ではAIエージェント向けの storybook skills コマンドが加わりました。公式のCHANGELOGを版ごとに追うと、10系の変更は次のとおりです。

古いチュートリアルで失敗する原因はほぼこの表に集まります。@storybook/addon-essentials はnpm上に8系までの版（最新8.6.19）しかなく、9系・10系向けの版は公開されていません。設定ファイルに module.exports が残っていても起動しません。Node.jsの条件は公式の移行ガイドに「Storybook 10 now requires Node.js version 20.19+ or 22.12+」とあり、require(esm) をフラグなしで使える範囲に合わせたものです。

Storybook 11で予定されている破壊的変更

Storybook 11はアルファ版の段階で、正式版の時期は未発表です。それでも移行ガイドの「From version 10.x to 11.0.0」には、すでに次の変更が並んでいます。

• Node.js 22.12以上、TypeScript 5.9以上が必須になる（TypeScript 7はStorybookが使うコンパイラAPIを持たないため、typescript の参照先を6系に向ける）
• Next.js 15未満とVite 6.3未満のサポートを打ち切る（10系の @storybook/nextjs-vite はNext.js 14.1以上・Vite 5以上を受け付ける）
• Webpack版の @storybook/nextjs は非推奨になり、Storybook 12で削除される予定（11では動くが、実行のたびに警告が出る）
• @storybook/test-runner の公式サポートが終わり、Vite系フレームワークではVitestアドオンへの移行を推奨
• Vitestアドオンの下限がVitest 4.0になり、vitest.workspace ファイルは作らず test.projects で設定する
• storybook dev が既定でブラウザを開かなくなる（開くには --open）
• Yarn PnPのサポートを削除し、argTypes の defaultValue も削除

11への移行作業の大半はtest-runnerとWebpack系フレームワークに集中します。10系でこの2つを使っているなら、11を待たずにVite系とVitestアドオンへ寄せておくべきです。

Storybookのインストールと起動手順

npm create storybookによる初期設定の生成

既存のReactやNext.jsプロジェクトのルートで次を実行します。依存関係からフレームワークを判定し、必要なパッケージと設定ファイルを入れます。--features で入れる機能を指定すると、対話の質問を減らせます。

npm create storybook@latest

# ドキュメント・テスト・アクセシビリティ検査をまとめて入れる場合
npm create storybook@latest --features docs test a11y

10.6.4でこのコマンドに --features docs test a11y を付けると、.storybook/main.ts と .storybook/preview.tsx、src/stories/ のサンプル（Button・Header・Page）が生成されます。package.json には storybook（storybook dev -p 6006）と build-storybook（storybook build）の2つのスクリプトが入ります。アドオンはDocs・Accessibility・Vitestに加えて、Chromatic連携の @chromatic-com/storybook も自動で入り、Vitestのブラウザモードで使うPlaywrightのブラウザもダウンロードされます。生成される main.ts は次の形です。

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

const config: StorybookConfig = {
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    '@chromatic-com/storybook',
    '@storybook/addon-vitest',
    '@storybook/addon-a11y',
    '@storybook/addon-docs',
  ],
  framework: '@storybook/react-vite',
};
export default config;

自動判定が外れたときは --type react や --type nextjs でフレームワークを明示できます。

開発サーバーの起動と静的ビルドによるチーム共有

npm run storybook        # 開発サーバー（スクリプトが -p 6006 を指定）
npm run build-storybook  # storybook-static/ に静的サイトを出力

# ポートを変える・CIで対話とブラウザ起動を止める
npx storybook dev -p 9009 --exact-port
npx storybook dev --ci

-p で指定したポートが埋まっていると、Storybookは別のポートで起動します。--exact-port を付けると、そのポートが使えないときにエラーで止まります。CIやコンテナで固定ポートを前提にするなら付けておくほうが安全です。開発サーバーの脆弱性CVE-2026-114125の対象版の確かめ方と修正手順はStorybookの脆弱性CVE-2026-114125とはで整理しています。build-storybook の出力は静的ファイルだけなので、ブランチごとにビルドしてレビュー用URLを配れば、デザイナーが実装済みの状態を自分で確認できます。

CSF3による最初のストーリーの作成

メタ（default export）とストーリー（named export）の役割

ストーリーはCSF3（Component Story Format 3）で書くのが既定です。1ファイルの default export が「どのコンポーネントのストーリー群か」を表すメタ、named export が個々のストーリーです。型は使っているフレームワークのパッケージ（React + Viteなら @storybook/react-vite）から読み込みます。次の例は、初期設定で src/stories/ に生成されるサンプルの Button をそのまま使います。

// src/stories/Button.stories.ts
import type { Meta, StoryObj } from '@storybook/react-vite';
import { fn } from 'storybook/test';
import { Button } from './Button';

const meta = {
  component: Button,
  tags: ['autodocs'],
  args: { label: '送信する', onClick: fn() },
} satisfies Meta<typeof Button>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Primary: Story = {
  args: { primary: true },
};

export const Large: Story = {
  args: { size: 'large' },
};

メタの args に共通の初期値を置き、各ストーリーでは差分だけを上書きします。fn() で作ったモック関数はActionsパネルに呼び出しを記録し、play関数の中で呼ばれたかを検証する対象にもなります。

args・argTypesによるControlsパネルの入力設定

args を定義するとControlsパネルに入力欄が現れ、コードを書き換えずにpropsを差し替えて、長い文言や真偽値の組み合わせで表示が崩れないかを試せます。入力欄の種類は argTypes で変えます。

const meta = {
  component: Button,
  argTypes: {
    size: { control: 'select', options: ['small', 'medium', 'large'] },
    backgroundColor: { control: 'color' },
  },
} satisfies Meta<typeof Button>;

decorators・parametersによる表示環境の設定

テーマや状態管理のProviderの中でしか正しく描画されないコンポーネントは、decorators で包みます。以下のThemeProviderはアプリ側で用意する例示用のコンポーネントで、import先とpropsは使用する実装に合わせます。.storybook/preview.tsx に書けば全ストーリーに、メタに書けばそのファイルのストーリーだけに効きます。配置や背景のように描画結果ではなく表示のされ方を決める設定は parameters に置きます。

// .storybook/preview.tsx
import type { Preview } from '@storybook/react-vite';
import { ThemeProvider } from '../src/theme';

const preview: Preview = {
  decorators: [
    (Story) => (
      <ThemeProvider>
        <Story />
      </ThemeProvider>
    ),
  ],
  parameters: {
    layout: 'centered',
  },
};

export default preview;

ストーリーに載せるコンポーネントと状態の選び方

Storybookに向くのは、propsだけで見た目が決まるプレゼンテーショナルなコンポーネントです。内部でAPIを呼ぶコンポーネントをそのまま載せると、モックの準備がストーリーの大半を占めます。データ取得は親に寄せ、表示部分だけを切り出してからストーリーにすると、保守の手間が下がります。

状態は「見た目が変わる分岐」を1ストーリーずつにします。ボタンなら通常・無効・読み込み中、一覧なら0件・1件・上限件数・長い文言、フォームなら入力エラーです。Controlsで試せば足りる組み合わせはストーリーにせず、レビューで繰り返し見る状態だけを残します。

CSF Next（CSF Factories）による型安全なストーリー定義

CSF NextはCSFの次の形式で、main.ts を defineMain（React + Viteなら @storybook/react-vite/node から読み込む）で定義したうえで、definePreview → preview.meta → meta.story と関数をつないで書きます。前段の設定から型が引き継がれるため、プレビューに登録したアドオンの parameters まで補完と型検査が効きます。公式ドキュメントの位置づけは10.6時点でも「preview」で、対象はReact・Vue・Angular・Web Componentsです。

// .storybook/preview.tsx
import { definePreview } from '@storybook/react-vite';
import addonA11y from '@storybook/addon-a11y';

export default definePreview({
  addons: [addonA11y()],
  parameters: { layout: 'centered' },
});

// src/stories/Button.stories.ts
import preview from '../../.storybook/preview';
import { Button } from './Button';

const meta = preview.meta({ component: Button });

export const Primary = meta.story({
  args: { label: '送信する', primary: true },
});

CSF3からの書き換えは npx storybook automigrate csf-factories で一括実行できます。ファイル単位で少しずつ移せますが、1つのファイルの中でCSF3とCSF Nextを混ぜることはできません。自動移行コマンドを使う場合、CSF2のファイルは先にCSF3へ上げる必要があります。

採用の判断はこう考えます。React + TypeScriptの新規プロジェクトで、プレビュー版のAPI変更に対応できるならCSF Nextを採用できます。安定したAPIを優先する場合はCSF3を選びます。数百ファイルのCSF3を抱えるプロジェクトは、API変更の可能性が残るプレビュー段階のうちは移行を急がず、11での扱いを見てから codemod で一括移行するほうが手戻りが少なくなります。11のアルファ版では、メタの args に as const が不要になる、メタの args のキーはすべて引数でなければならない、といったCSF Nextの仕様変更がすでに入っています。

アドオン・autodocsによる文書生成とアクセシビリティ検査

autodocsによるprops表・説明文の自動生成

メタに tags: ['autodocs'] を付けると、そのコンポーネントの全ストーリーとpropsの型情報からDocsページが生成されます。propsにJSDocコメントを書けば、その文がDocsの説明欄に入るため、説明だけが古びる状態を避けられます。

Actionsによるイベント記録とAccessibilityアドオンによる自動検査

Actionsはクリックなどのイベントで呼ばれた関数と引数をパネルに記録します。@storybook/addon-a11y を入れると各ストーリーにアクセシビリティ検査のタブが付き、コントラスト比の不足やARIA属性の誤りをストーリー単位で指摘します。自動検査で拾えるのは機械的に判定できる問題に限られ、キーボード操作やスクリーンリーダーでの確認は別に要ります。Vitestアドオンと組み合わせると、この検査がテストとしても走ります。ただし初期設定で生成される preview の a11y.test は 'todo' で、違反はテスト画面に表示されるだけです。CIで落としたいなら 'error' に変えます。

Next.jsとStorybookの連携設定

@storybook/nextjs-viteと@storybook/nextjsの選び方

Next.js向けのフレームワークパッケージは2つあります。公式ドキュメントはVite版を「recommended」としており、独自のWebpackやBabelの設定がないプロジェクトでは、npm create storybook@latest が自動でVite版を選びます。

10.6.4の @storybook/nextjs-vite が受け付けるのはNext.js 14.1以上・15系・16系、Vite 5〜8系です。StorybookはNext.jsの開発サーバーを使わず、自前のVite（またはWebpack）でストーリーをビルドします。Webpack版から移るときは npx storybook automigrate nextjs-to-nextjs-vite が package.json と設定ファイルを書き換えます。

next/image・ルーター・Server Componentsの扱い

Next.js向けパッケージは next/image、next/font、ルーター、環境変数をStorybook上で扱えるようにします。next/navigationを使うコンポーネントでは、ストーリーのメタまたはpreviewのparametersに nextjs: { appDirectory: true } を設定します。useRouter や useSearchParams の戻り値を変えて表示を確かめたいときは、@storybook/nextjs-vite/navigation.mock などのモックを使います。

App RouterのServer Componentsは、.storybook/main.ts の features に experimentalRSC: true を足すとブラウザ上で描画できます。ただしファイルシステムやNode.js専用のライブラリに触れるServer Componentは描画できません。ページファイルがそうしたモジュールに依存している場合も、そのままimportするとViteのビルドが失敗することがあります。どちらも、依存をモックに差し替えるか、表示部分を別ファイルへ切り出してストーリーから読み込みます。Server ComponentsとClient Componentsの境界はReact Server Components（RSC）とは？サーバー・クライアントの違いと使い分けを実装例で解説、ページごとの描画方式はNext.jsのレンダリング方式｜SSG・ISR・SSR・CSRの違いとApp Routerでの選び方で整理しています。

Storybookのテスト自動化とCI連携

play関数・Vitestアドオンによるインタラクションテスト

ストーリーに play 関数を書くと、描画後にユーザー操作を再現して結果を検証できます。検証に使う expect などは storybook/test から読み込みます（旧 @storybook/test から移設）。

import { expect } from 'storybook/test';

export const ClickSubmit: Story = {
  play: async ({ args, canvas, userEvent }) => {
    await userEvent.click(canvas.getByRole('button', { name: '送信する' }));
    await expect(args.onClick).toHaveBeenCalledTimes(1);
  },
};

@storybook/addon-vitest は、ストーリーをVitestのテストに変換し、PlaywrightのChromiumを使うブラウザモードで実行します。10.6.4のpeerDependenciesが受け付けるのはVitest 4系と5系です。ストーリーごとにテストファイルを書き足す必要はありません。描画が通ることそのものがスモークテストになり、play関数があればその検証も走ります。

セットアップすると vite.config.ts の test.projects に name: 'storybook' のプロジェクトが追加され、npx vitest --project=storybook で実行できます。preview を書き換えた直後などにViteが新しい依存を見つけると、テスト中に再読み込みが起きて「Vite unexpectedly reloaded a test」と表示され、テストファイルの読み込みに失敗することがあります。再実行すれば通りますが、CIで安定させるなら警告が示す依存を optimizeDeps.include に足しておきます。Vitest本体の設定はVitestの使い方と書き方：読み方・設定からReact Testing Libraryのコンポーネントテストまで【Vitest 5対応】、ブラウザモードの仕組みはVitest Browser Modeの使い方｜Playwrightでの導入・headless設定とjsdomとの使い分け【Vitest 5対応】で解説しています。

注意点は、このアドオンがViteを前提にしていることです。@storybook/nextjs や @storybook/react-webpack5 では使えず、従来のtest-runnerに頼ることになります。そのtest-runnerは11で公式サポートが終わるため、Webpack系のまま新たにテストを組むのは避けるべきです。

GitHub ActionsによるStorybookテストのCI実行

CIではStorybookを起動せず、Vitestのプロジェクト指定でストーリーのテストだけを走らせます。package.json にスクリプトを足し、公式のCIガイドと同じくPlaywright入りのコンテナで実行します。

// package.json
"scripts": {
  "test-storybook": "vitest --project=storybook"
}

# .github/workflows/test-ui.yml
name: UI Tests
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    container:
      # npx playwright --version で確かめた版とタグをそろえる
      image: mcr.microsoft.com/playwright:v1.64.1-noble
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22.12.0
      - run: npm ci
      - run: npm run test-storybook

Node.jsを22.12にしておくと、11へ上げたときにCIを触らずに済みます。テストが失敗したときに該当ストーリーへのリンクを出したい場合は、公開済みStorybookのURLをVitestプラグインの storybookUrl に渡します。

ChromaticによるPull Request単位の見た目の差分検出

見た目の意図しない変化を止めたいときは、Storybookのメンテナーが運営するChromaticを使います。ストーリーごとのスクリーンショットを前回と比べ、Pull Requestで差分を承認か却下します。導入手順と料金の数え方はChromaticとは？Storybook連携のビジュアルテスト自動化と料金・TurboSnapを解説で扱っています。Chromatic以外の選択肢も含めた比較はVRT（ビジュアルリグレッションテスト）とは？仕組み・ツールの選び方とPlaywright実装にまとめました。

似たツールとの住み分け｜テストライブラリ・E2Eとの役割分担

Storybookは「どの状態を確かめるか」を定義する場所で、その状態に何を検査するかは各ツールの仕事です。競合ではなく層が違います。

play関数の canvas.getByRole はTesting Libraryと同じクエリなので、要素の取り方はReact Testing Libraryのuser-eventとクエリ実践｜getByRole・findBy・fireEventの使い分けの作法がそのまま通用します。Storybookを入れてもユニットテストやE2Eは残り、コンポーネントテストの入口がストーリーに1本化されます。

Storybookの費用｜本体のライセンスとChromaticの料金

Storybook本体と公式アドオンはMITライセンスのオープンソースで、商用でも無償です。運用にはストーリーの保守工数がかかり、CIや公開先の契約によって実行・ホスティング料金も発生します。Chromaticでビジュアルテストを行う場合は、プランと使用量に応じた料金も確認します。2026年10月27日時点のChromaticの料金ページは次の構成でした。

スナップショットは「ストーリー数×ブラウザ数×ビューポート数×実行回数」で増えます。200ストーリーをChromeの1画面幅で撮るなら1回200枚、月25回のPRで無料枠の5,000枚に届きます。Starter以上で枠を超えた分は1枚0.008ドルです。TurboSnapでは、変更のあるテストの新規撮影は1枚分、変更のないテストの既存画像のコピーは0.2枚分として課金されます。ビルド全体で変更がなく撮影を省略する場合は課金されません。

Storybookを導入すべきか｜向く場面と見送る場面

導入を勧めるのは、同じコンポーネントを複数の画面やプロダクトで使い回し、開発者とデザイナーの間でUIの状態を繰り返し共有・レビューする開発です。デザインシステムの実装済みコンポーネントと状態を共有する用途にも向いており、構成要素の考え方はデザインシステムとは？構成要素と作り方、ガイドライン・スタイルガイドとの違いで整理しています。

見送ってよいのは、コンポーネントの再利用や状態別のレビューが少なく、ストーリーの保守工数が確認作業の削減量を上回る開発です。その場合は、先にVitestとReact Testing Libraryでテストを書くほうが早く効果が出ます。

導入後に失敗する典型は、ストーリーが更新されなくなるパターンです。サイドバーに描画エラーのストーリーが残っている、Docsのpropsの表が実装とずれている、新しいコンポーネントにストーリーがない。この3つが見えたら運用が止まり始めています。描画エラーはVitestアドオンで全ストーリーをCI実行し、その成功をマージの必須条件にして防ぎます。新規コンポーネントのストーリー追加漏れや説明文の古さは、レビュー項目に含めて確認します。UIの設計からコンポーネントの実装までを外部に任せたい場合は、一創のUI/UXデザインで相談を受けています。

よくある質問

Storybookとは何をするツールですか？

UIコンポーネントをアプリから切り離して単体で描画し、状態ごとに確認・文書化・テストするための開発環境です。

storiesOf記法は今でも使えますか？

使えません。storiesOf はStorybook 8で削除されており、現行の10系ではCSF3かCSF Nextで書きます。古い記事のコードはdefault exportのメタとnamed exportのストーリーに書き直します。

Storybookは無料で使えますか？

本体と公式アドオンはMITライセンスで、商用でも無料です。ビジュアルテストのChromaticは無料枠が月5,000スナップショットで、それを超える場合やChrome以外のブラウザで撮る場合は月179ドルのStarter以上が必要です。

Next.jsでStorybookは使えますか？

使えます。公式推奨の @storybook/nextjs-vite なら、next/imageやルーターが動き、Vitestアドオンでテストもできます。Server Componentsの描画は experimentalRSC フラグを使う実験的な機能です。

Storybook 11へはいつ上げるべきですか？

2026年10月時点の11はアルファ版なので、本番のプロジェクトは10.6系のままで構いません。先にNode.jsを22.12以上、TypeScriptを5.9以上、Next.jsを15以上へ上げ、test-runnerをVitestアドオンへ移しておくと、正式版が出たときの移行が小さく済みます。

Storybookのポート番号は変更できますか？

できます。storybook dev -p 9009 のように -p で指定します。指定したポートが使用中なら別のポートで起動するため、必ずそのポートで起動させたいときは --exact-port を付けます。

関連記事

• Chromaticとは？Storybook連携のビジュアルテスト自動化と料金・TurboSnapを解説
• デジタル庁デザインシステムのStorybookとGitHub｜React 19版・Figma v2.18.2の入手と取り込み手順
• Vitestの使い方と書き方：読み方・設定からReact Testing Libraryのコンポーネントテストまで【Vitest 5対応】
• React Server Components（RSC）とは？サーバー・クライアントの違いと使い分けを実装例で解説
• アトミックデザインとは？5階層の分類基準とReactコンポーネント設計・3階層縮退