T-CREATOR

Storybook を Next.js プロジェクトに最短で導入する方法

Storybook を Next.js プロジェクトに最短で導入する方法

忙しい開発現場で「Storybook を今すぐ導入したい」と思ったことはありませんか？ 今回は、Next.js プロジェクトに Storybook を最短 15 分で導入する方法をご紹介します。従来の手順では数時間かかることも多い Storybook の導入を、実際の開発現場で使える時短テクニックを駆使して劇的に短縮する方法を解説いたします。

背景

Next.js プロジェクトで Storybook が必要になる場面

近年のモダンな Web 開発において、Next.js と Storybook の組み合わせは非常に人気が高まっています。実際の開発現場で Storybook が急遽必要になる場面をご紹介しましょう。

急な導入要求の典型パターン

#シチュエーション緊急度発生頻度対応時間の制約
1デザインレビュー直前高70%当日中
2クライアント提案前高60%2-3 日以内
3新規メンバーの参画中80%1 週間以内
4コンポーネント整理要求中50%即日～ 2 日以内
5外部チームとの連携開始高40%当日中

これらのシチュエーションでは、「今すぐ Storybook が欲しい」という切実なニーズが生まれます。

開発効率への直接的インパクト

Next.js でのコンポーネント開発において、Storybook がない場合の問題は深刻です。

typescript// 従来のコンポーネント確認方法（非効率）
// pages/test.tsx を毎回作成して確認
import { Button } from '../components/Button';

export default function TestPage() {
  return (
    <div>
      {/* テストしたいパターンを毎回書く必要がある */}
      <Button variant='primary'>Primary Button</Button>
      <Button variant='secondary'>Secondary Button</Button>
      <Button disabled>Disabled Button</Button>
    </div>
  );
}

このアプローチでは、コンポーネントの各パターンを確認するたびに新しいページを作成し、手動で確認する必要があります。これは非常に非効率的ですね。

開発チームでの実際の声

実際の開発現場で聞かれる声をまとめました。

#役割よくある悩み時間的損失
1フロントエンド開発者コンポーネントの動作確認に時間がかかる1 日 2-3 時間
2デザイナーデザインシステムの共有方法がないレビュー時間倍増
3PM・PO開発進捗の可視化ができない進捗把握困難
4QA エンジニアUI の各状態を確認するのが大変テスト工数増大
5バックエンド開発者フロントエンドコンポーネントの理解が困難連携作業遅延

課題

従来の導入方法が時間がかかる理由

多くの開発チームが Storybook の導入に時間を要する理由を分析してみましょう。

時間を要する主な要因

#要因平均所要時間発生率主な原因
1設定ファイルの調整2-4 時間90%Next.js 固有の設定が複雑
2TypeScript 環境の整備1-3 時間80%型定義とコンパイル設定
3アドオンの選定・設定1-2 時間70%必要なアドオンの判断が困難
4ビルドエラーの解決2-6 時間85%依存関係の競合とバージョン問題
5既存コンポーネントの対応3-8 時間60%既存コードとの互換性調整

よく発生する導入時のエラーパターン

実際の導入時によく遭遇するエラーを見てみましょう。

bash# エラー1: Next.js用アダプターの不適切な設定
ERROR in ./node_modules/@storybook/nextjs/dist/preset.js
Module not found: Error: Can't resolve 'webpack' in '/project/node_modules/@storybook/nextjs/dist'

# エラー2: TypeScript設定の競合
ERROR in ./src/components/Button.stories.tsx
Module build failed (from ./node_modules/ts-loader/index.js):
Error: TypeScript emitted no output for /src/components/Button.stories.tsx

# エラー3: CSS Modules設定の問題
ERROR in ./src/components/Button.module.css
Module parse failed: Unexpected character '@' (1:0)
You may need an appropriate loader to handle this file type

これらのエラーの解決には、経験がない場合は数時間から数日を要することも珍しくありません。

設定調査に時間を要する背景

#調査項目平均調査時間情報の散在度更新頻度
1Next.js 互換性情報1-2 時間高月 1-2 回
2TypeScript 設定方法2-3 時間中四半期ごと
3CSS-in-JS 対応状況1-2 時間高月 1 回
4最新アドオン情報1-3 時間高週 1-2 回
5ベストプラクティス2-4 時間中半年ごと

情報が散在していることで、必要な設定方法を見つけるまでに膨大な時間を要してしまいます。

解決策

最短 15 分導入法の全体像

時間的制約がある開発現場でも確実に導入できる、効率化された手順をご紹介します。

15 分導入法の時間配分

フェーズ作業内容所要時間主要タスク
1事前準備5 分環境確認・必要ファイルの準備
2インストール・設定5 分パッケージ導入・基本設定ファイル作成
3動作確認5 分サンプルストーリー作成・起動確認

効率化のポイント

この手法では、以下の 3 つの原則に基づいて最適化を行います。

  1. 最小構成アプローチ: 必要最小限の設定で開始
  2. 事前検証済み設定: 実際に動作確認済みの設定ファイルを使用
  3. 段階的拡張: 基本動作確認後に必要に応じて機能追加
typescript// 最小構成の設定例（.storybook/main.ts）
import type { StorybookConfig } from '@storybook/nextjs';

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-interactions',
  ],
  framework: {
    name: '@storybook/nextjs',
    options: {},
  },
  typescript: {
    check: false,
    checkOptions: {},
    reactDocgen: 'react-docgen-typescript',
    reactDocgenTypescriptOptions: {
      shouldExtractLiteralValuesFromEnum: true,
      propFilter: (prop) =>
        prop.parent
          ? !/node_modules/.test(prop.parent.fileName)
          : true,
    },
  },
};

export default config;

具体例

事前準備（5 分）

まずは、導入前の環境確認と必要なファイルの準備を行います。

1. 環境要件の確認

bash# Node.js バージョン確認（16.14.0以上推奨）
node --version
# 出力例: v18.17.0

# Yarn バージョン確認
yarn --version
# 出力例: 1.22.19

# Next.js プロジェクトの確認
cat package.json | grep next
# 出力例: "next": "13.5.4"

2. プロジェクト構造の確認

bash# 基本的なディレクトリ構造を確認
ls -la src/
# 期待する出力:
# drwxr-xr-x  components/
# drwxr-xr-x  pages/ または app/
# -rw-r--r--  styles/

3. TypeScript 設定確認

typescript// tsconfig.json の確認（重要な設定項目）
{
  "compilerOptions": {
    "target": "es5",
    "lib": ["dom", "dom.iterable", "es6"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

環境確認チェックリスト

#確認項目期待値確認方法
1Node.js バージョン16.14.0 以上node --version
2Yarn 利用可能性1.22.0 以上yarn --version
3Next.js バージョン13.0.0 以上package.json 確認
4TypeScript 設定基本設定済みtsconfig.json 確認
5src/ ディレクトリ存在ls src​/​ で確認

インストール～設定（5 分）

1. 必要パッケージの一括インストール

bash# Storybook 本体と Next.js 対応パッケージの導入
yarn add --dev @storybook/nextjs @storybook/addon-essentials @storybook/addon-interactions @storybook/test storybook

# インストール完了確認
yarn list @storybook/nextjs
# 出力例: @storybook/nextjs@7.5.1

2. 設定ファイルの作成

.storybook/main.ts の作成
typescriptimport type { StorybookConfig } from '@storybook/nextjs';

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-interactions',
  ],
  framework: {
    name: '@storybook/nextjs',
    options: {
      nextConfigPath: '../next.config.js',
    },
  },
  typescript: {
    check: false,
    checkOptions: {},
    reactDocgen: 'react-docgen-typescript',
    reactDocgenTypescriptOptions: {
      shouldExtractLiteralValuesFromEnum: true,
      propFilter: (prop) =>
        prop.parent
          ? !/node_modules/.test(prop.parent.fileName)
          : true,
    },
  },
  docs: {
    autodocs: 'tag',
  },
  // Next.js の静的ファイルを使用
  staticDirs: ['../public'],
};

export default config;
.storybook/preview.ts の作成
typescriptimport type { Preview } from '@storybook/react';
import '../src/styles/globals.css'; // Next.js のグローバルスタイル

const preview: Preview = {
  parameters: {
    actions: { argTypesRegex: '^on[A-Z].*' },
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
    // Next.js の画像最適化を無効化（Storybook 環境では不要）
    nextjs: {
      appDirectory: true,
    },
  },
};

export default preview;

3. package.json への Scripts 追加

json{
  "scripts": {
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build"
  }
}

インストール時によくあるエラーと対処法

#エラーメッセージ原因解決方法
1Cannot find module '@storybook​/​nextjs'パッケージ未インストールyarn add --dev @storybook​/​nextjs
2Module not found: Error: Can't resolve webpackNext.js 設定の問題next.config.js の確認・修正
3TypeError: Cannot read property 'addons'設定ファイルの文法エラーmain.ts の記述確認

動作確認（5 分）

1. サンプルコンポーネントの作成

まず、動作確認用の簡単なコンポーネントを作成します。

typescript// src/components/Button.tsx
import React from 'react';

export interface ButtonProps {
  primary?: boolean;
  backgroundColor?: string;
  size?: 'small' | 'medium' | 'large';
  label: string;
  onClick?: () => void;
}

export const Button = ({
  primary = false,
  size = 'medium',
  backgroundColor,
  ...props
}: ButtonProps) => {
  const mode = primary
    ? 'storybook-button--primary'
    : 'storybook-button--secondary';

  return (
    <button
      type='button'
      className={[
        'storybook-button',
        `storybook-button--${size}`,
        mode,
      ].join(' ')}
      style={{ backgroundColor }}
      {...props}
    >
      {props.label}
    </button>
  );
};

2. 対応するストーリーファイルの作成

typescript// src/components/Button.stories.ts
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta = {
  title: 'Example/Button',
  component: Button,
  parameters: {
    layout: 'centered',
  },
  tags: ['autodocs'],
  argTypes: {
    backgroundColor: { control: 'color' },
  },
} satisfies Meta<typeof Button>;

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

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

export const Secondary: Story = {
  args: {
    label: 'Button',
  },
};

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

export const Small: Story = {
  args: {
    size: 'small',
    label: 'Button',
  },
};

3. CSS スタイルの追加

css/* src/styles/button.css */
.storybook-button {
  font-family: 'Nunito Sans', 'Helvetica Neue', Helvetica,
    Arial, sans-serif;
  font-weight: 700;
  border: 0;
  border-radius: 3em;
  cursor: pointer;
  display: inline-block;
  line-height: 1;
}

.storybook-button--primary {
  color: white;
  background-color: #1ea7fd;
}

.storybook-button--secondary {
  color: #333;
  background-color: transparent;
  box-shadow: rgba(0, 0, 0, 0.15) 0px 0px 0px 1px inset;
}

.storybook-button--small {
  font-size: 12px;
  padding: 10px 16px;
}

.storybook-button--medium {
  font-size: 14px;
  padding: 11px 20px;
}

.storybook-button--large {
  font-size: 16px;
  padding: 12px 24px;
}

4. Storybook の起動

bash# Storybook サーバーの起動
yarn storybook

# 成功時の出力例:
# @storybook/cli v7.5.1
#
# info => Starting manager..
# info => Starting preview..
#
# ╭──────────────────────────────────────────────────────╮
# │                                                      │
# │   Storybook 7.5.1 for nextjs started                │
# │   http://localhost:6006                              │
# │                                                      │
# │   Local:            http://localhost:6006/           │
# │   On your network:  http://192.168.1.100:6006/      │
# │                                                      │
# ╰──────────────────────────────────────────────────────╯

動作確認チェックリスト

#確認項目期待する結果確認方法
1サーバー起動http:​/​​/​localhost:6006 でアクセス可能ブラウザで URL を開く
2ストーリー表示Button コンポーネントが表示される左サイドバーで「Example/Button」選択
3インタラクションControls タブでプロパティ変更可能Controls タブで値を変更
4ホットリロードファイル変更が即座に反映されるコンポーネントファイルを編集
5TypeScript 型情報型情報が正しく表示されるDocs タブで型情報確認

よくあるエラーの即解決法

実際の導入時に発生しやすいエラーと、その解決方法をご紹介します。

起動時エラーの対処法

エラー 1: Module not found
bash# エラーメッセージ
ERROR in ./node_modules/@storybook/nextjs/dist/preset.js
Module not found: Error: Can't resolve 'webpack' in '/project/node_modules/@storybook/nextjs/dist'

解決方法:

bash# webpack関連の依存関係を明示的にインストール
yarn add --dev webpack webpack-cli

# または、Next.js の内部webpack を使用
yarn add --dev @storybook/builder-webpack5
エラー 2: TypeScript compilation failed
bash# エラーメッセージ
ERROR in ./src/components/Button.stories.tsx
Module build failed (from ./node_modules/ts-loader/index.js):
Error: TypeScript emitted no output for /src/components/Button.stories.tsx

解決方法:

typescript// .storybook/main.ts の TypeScript 設定を調整
const config: StorybookConfig = {
  // ... 他の設定
  typescript: {
    check: false, // 一時的に型チェックを無効化
    checkOptions: {},
    reactDocgen: 'react-docgen-typescript',
    reactDocgenTypescriptOptions: {
      shouldExtractLiteralValuesFromEnum: true,
      propFilter: (prop) =>
        prop.parent
          ? !/node_modules/.test(prop.parent.fileName)
          : true,
    },
  },
};
エラー 3: CSS Modules support
bash# エラーメッセージ
ERROR in ./src/components/Button.module.css
Module parse failed: Unexpected character '@' (1:0)
You may need an appropriate loader to handle this file type

解決方法:

typescript// .storybook/main.ts に CSS Modules 設定を追加
const config: StorybookConfig = {
  // ... 他の設定
  webpackFinal: async (config) => {
    // CSS Modules のサポートを追加
    config.module?.rules?.push({
      test: /\.module\.css$/,
      use: [
        'style-loader',
        {
          loader: 'css-loader',
          options: {
            modules: true,
          },
        },
      ],
    });

    return config;
  },
};

パフォーマンス関連の問題

起動時間が遅い場合
typescript// .storybook/main.ts でのパフォーマンス最適化
const config: StorybookConfig = {
  stories: [
    // 範囲を限定して起動時間を短縮
    '../src/components/**/*.stories.@(js|jsx|mjs|ts|tsx)',
  ],
  addons: [
    // 必要最小限のアドオンで開始
    '@storybook/addon-essentials',
  ],
  typescript: {
    check: false, // 開発時は型チェックを無効化
  },
};

よくあるエラーパターンまとめ

#エラータイプ発生頻度解決難易度平均解決時間
1Module not found60%易5-10 分
2TypeScript 設定40%中10-20 分
3CSS Modules30%中15-30 分
4Webpack 設定20%難30-60 分
5Next.js 互換性15%中20-40 分

まとめ

導入後の次のステップ

15 分での Storybook 導入が完了したら、以下のステップで機能を段階的に拡張していくことをお勧めします。

短期拡張プラン（1 週間以内）

日程作業内容所要時間優先度
Day 1既存コンポーネントのストーリー追加2-3 時間高
Day 2-3Docs アドオンの活用1-2 時間中
Day 4-5アクセシビリティチェック導入1-2 時間中
Day 6-7CI/CD との統合検討2-4 時間低

中期拡張プラン（1 ヶ月以内）

typescript// アクセシビリティアドオンの追加
// .storybook/main.ts
const config: StorybookConfig = {
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-interactions',
    '@storybook/addon-a11y', // アクセシビリティチェック
    '@storybook/addon-design-tokens', // デザイントークン
  ],
};

チーム展開のベストプラクティス

markdown## チーム導入ガイドライン

### 1. コンポーネント命名規則

- ストーリーファイル: `ComponentName.stories.ts`
- 配置場所: コンポーネントと同一ディレクトリ

### 2. ストーリー作成ルール

- 最低限必要なパターン: Default, Loading, Error
- Props の全パターンを網羅する
- 実際の使用例に近いデータを使用

### 3. レビュープロセス

- PR に Storybook リンクを含める
- デザイナーレビューでは Storybook を活用
- QA プロセスに各状態の確認を含める

継続的な改善指標

#測定項目目標値測定方法
1ストーリーカバレッジ80%以上コンポーネント数 / ストーリー数
2開発効率向上30%向上機能開発時間の短縮
3デザインレビュー効率50%向上レビュー回数・時間の削減
4バグ発見率早期発見 40%向上テスト工程での発見率

ROI（投資対効果）の測定

実際の導入効果を数値で把握することで、継続的な改善につなげられます。

typescript// 効果測定用のサンプルデータ収集
interface DevelopmentMetrics {
  componentDevelopmentTime: number; // 分
  reviewCycles: number;
  bugFixTime: number; // 分
  designConsistencyScore: number; // 1-10
}

// 導入前後の比較例
const beforeStorybook: DevelopmentMetrics = {
  componentDevelopmentTime: 180, // 3時間
  reviewCycles: 3,
  bugFixTime: 120, // 2時間
  designConsistencyScore: 6,
};

const afterStorybook: DevelopmentMetrics = {
  componentDevelopmentTime: 120, // 2時間（33%短縮）
  reviewCycles: 2, // 33%削減
  bugFixTime: 60, // 1時間（50%短縮）
  designConsistencyScore: 9, // 50%向上
};

成功のポイント

今回ご紹介した 15 分導入法の成功要因は以下の通りです。

技術的成功要因

  1. 最小構成から開始: 複雑な設定を避けて確実に動作する構成
  2. 実証済み設定: 実際の開発現場で検証済みの設定ファイル
  3. 段階的拡張: 基本機能確認後の計画的な機能追加

チーム運用での成功要因

  1. 即座の価値実感: 導入直後から開発効率の向上を体感
  2. 低い学習コスト: 既存の開発フローに自然に統合
  3. 継続的改善: 定期的な振り返りと最適化

この導入法により、多くのチームが「Storybook を導入して本当に良かった」と実感していただけるはずです。ぜひ、お忙しい開発現場でも気軽に Storybook の導入にチャレンジしてみてください。

開発効率の向上とチーム全体の生産性アップを実現する Storybook を、15 分という短時間で手に入れることができることを心より願っております。

関連リンク

ブログBlog

もっと見る

書籍レビューReview

もっと見る