Storybook を起動したら真っ白な画面が表示されて困っていませんか？開発中に突然 Storybook が動かなくなると、コンポーネントの確認ができず作業が止まってしまいますよね。

この記事では、Storybook の起動失敗やビルドエラーでお悩みの方に向けて、効果的な解決方法を 15 のチェックポイントに分けてご紹介します。基本的な確認事項から高度なトラブルシューティングまで、段階的に問題を特定して解決できるよう構成しました。

背景

Storybook の仕組みと起動プロセス

Storybook は独自の Webpack ベースのビルドシステムを使用し、コンポーネントを独立した環境で動作させています。

mermaidCopy codeflowchart TD
    start[yarn storybook] --> config[設定ファイル読み込み]
    config --> deps[依存関係解決]
    deps --> webpack[Webpack ビルド]
    webpack --> server[開発サーバー起動]
    server --> browser[ブラウザ表示]

    config --> error1[設定エラー]
    deps --> error2[依存関係エラー]
    webpack --> error3[ビルドエラー]
    server --> error4[サーバーエラー]
    browser --> error5[表示エラー]

上記の図では、Storybook の起動から表示までの一連の流れと、各段階で発生しうるエラーポイントを示しています。

真っ白画面が発生する一般的な原因

Storybook で真っ白画面が発生する原因は大きく分けて以下の 5 つです：

#	原因カテゴリ	具体的な問題例
1	環境問題	Node.js バージョン不適合、依存関係の競合
2	設定問題	main.js 設定ミス、webpack 設定エラー
3	キャッシュ問題	古いビルドキャッシュが残存
4	ポート問題	既に使用中のポートへのバインド失敗
5	アドオン問題	互換性のないアドオンの使用

課題

起動時の問題

初回セットアップでの起動失敗

新規プロジェクトで Storybook をセットアップした際に起動に失敗するケースでは、以下の問題が考えられます。

typescriptCopy code// よくある初回セットアップのエラー例
Error: Cannot resolve module '@storybook/react'

このエラーは依存関係が正しくインストールされていない場合に発生します。

既存プロジェクトでの突然の起動不可

これまで正常に動作していた Storybook が突然起動しなくなる場合には、以下の要因が関係している可能性があります：

• 依存関係の自動更新による互換性問題
• 開発環境の変更（Node.js バージョンアップなど）
• キャッシュファイルの破損

ビルド時の問題

依存関係エラー

package.json に記載された依存関係と node_modules の実際のバージョンが異なる場合に発生します。

javascriptCopy code// 典型的な依存関係エラーメッセージ
Module not found: Error: Can't resolve 'react-dom/client'

設定ファイルの問題

.storybook/main.js の設定に問題がある場合、ビルドプロセスが正常に完了しません。

javascriptCopy code// 問題のある設定例
module.exports = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: [
    '@storybook/addon-essentials',
    // 存在しないアドオンを指定
    '@storybook/addon-nonexistent',
  ],
};

バージョン互換性の問題

Storybook 本体とアドオン、または React や TypeScript との間でバージョン互換性に問題がある場合です。

解決策

基本チェック（5 項目）

以下の基本チェックから始めることで、多くの一般的な問題を解決できます。

1. Node.js/npm バージョン確認

まずは環境の基盤となる Node.js とパッケージマネージャーのバージョンを確認しましょう。

bashCopy code# 現在のバージョンを確認
node --version
npm --version
yarn --version

Storybook が推奨する Node.js バージョンは以下の通りです：

Storybook バージョン	推奨 Node.js バージョン
7.x	Node.js 16.x 以上
6.x	Node.js 14.x 以上
5.x	Node.js 12.x 以上

バージョンが古い場合は、以下のコマンドでアップデートを行います。

bashCopy code# Node.jsのアップデート（nvmを使用している場合）
nvm install node
nvm use node

2. 依存関係の再インストール

依存関係の問題を解決するため、クリーンインストールを実行します。

bashCopy code# node_modulesとlock fileを削除
rm -rf node_modules
rm package-lock.json  # または yarn.lock

その後、依存関係を再インストールします。

bashCopy code# 再インストール実行
yarn install
# または
npm install

3. キャッシュクリア

Storybook と関連ツールのキャッシュをクリアして、古い情報による問題を解消します。

bashCopy code# Storybookキャッシュクリア
npx storybook dev --no-manager-cache

# または手動でキャッシュディレクトリを削除
rm -rf node_modules/.cache

npm/yarn のキャッシュもクリアします。

bashCopy code# npmキャッシュクリア
npm cache clean --force

# yarnキャッシュクリア
yarn cache clean

4. ポート競合確認

デフォルトポート 6006 が既に使用されている可能性を確認します。

bashCopy code# ポート使用状況確認（macOS/Linux）
lsof -i :6006

# ポート使用状況確認（Windows）
netstat -ano | findstr :6006

別のポートで起動を試します。

bashCopy code# 別ポートで起動
yarn storybook --port 6007

5. 基本設定ファイル確認

.storybook/main.js の基本的な構文エラーや設定ミスを確認します。

javascriptCopy code// 最小構成の.storybook/main.js
module.exports = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: ['@storybook/addon-essentials'],
};

設定ファイルに構文エラーがないか JavaScript linter で確認できます。

bashCopy code# ESLintでチェック
npx eslint .storybook/main.js

設定関連チェック（5 項目）

基本チェックで解決しない場合は、より詳細な設定を確認します。

6. .storybook/main.js 設定確認

Storybook の中核となる設定ファイルを詳しく見直します。

javascriptCopy code// 推奨される.storybook/main.js設定
module.exports = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx|mdx)'],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-interactions',
  ],
  framework: {
    name: '@storybook/react-webpack5',
    options: {},
  },
  // TypeScriptプロジェクトの場合
  typescript: {
    check: false,
    reactDocgen: 'react-docgen-typescript',
  },
};

stories パスが正しく設定されているか確認しましょう。

bashCopy code# stories ファイルの存在確認
find src -name "*.stories.*" -type f

7. webpack 設定の問題

カスタム webpack 設定が原因でビルドが失敗している可能性があります。

javascriptCopy code// .storybook/main.js でのwebpack設定例
module.exports = {
  // ... 他の設定
  webpackFinal: async (config) => {
    // カスタムエイリアスの追加
    config.resolve.alias = {
      ...config.resolve.alias,
      '@': path.resolve(__dirname, '../src'),
    };

    // カスタムローダーの追加
    config.module.rules.push({
      test: /\.scss$/,
      use: ['style-loader', 'css-loader', 'sass-loader'],
    });

    return config;
  },
};

webpack 設定に問題がある場合は、一時的にカスタム設定を無効にして起動を試します。

javascriptCopy code// 最小限のwebpack設定
module.exports = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: ['@storybook/addon-essentials'],
  // webpackFinal を一時的にコメントアウト
};

8. TypeScript 設定確認

TypeScript プロジェクトの場合、tsconfig.json の設定が Storybook と競合している可能性があります。

jsonCopy code// .storybook/tsconfig.json（推奨設定）
{
  "extends": "../tsconfig.json",
  "compilerOptions": {
    "allowSyntheticDefaultImports": true,
    "jsx": "react-jsx"
  },
  "include": ["../src/**/*", "../stories/**/*"],
  "exclude": ["../src/**/*.test.*"]
}

TypeScript 設定で問題が発生する場合の一時的な回避方法：

javascriptCopy code// .storybook/main.js でTypeScriptチェックを無効化
module.exports = {
  // ... 他の設定
  typescript: {
    check: false,
    reactDocgen: 'react-docgen-typescript',
    reactDocgenTypescriptOptions: {
      shouldExtractLiteralValuesFromEnum: true,
      propFilter: (prop) =>
        prop.parent
          ? !/node_modules/.test(prop.parent.fileName)
          : true,
    },
  },
};

9. CSS/スタイル設定問題

CSS ファイルやスタイリングライブラリの設定が正しく行われていない場合があります。

javascriptCopy code// styled-componentsを使用している場合の設定例
// .storybook/main.js
module.exports = {
  addons: [
    '@storybook/addon-essentials',
    // styled-components用の設定
    {
      name: '@storybook/addon-styling-webpack',
      options: {
        rules: [
          {
            test: /\.css$/,
            use: [
              'style-loader',
              {
                loader: 'css-loader',
                options: { importLoaders: 1 },
              },
              {
                loader: 'postcss-loader',
                options: {
                  implementation:
                    require.resolve('postcss'),
                },
              },
            ],
          },
        ],
      },
    },
  ],
};

Tailwind CSS を使用している場合の設定：

javascriptCopy code// .storybook/preview.js でTailwindをインポート
import '../src/index.css'; // Tailwind CSSのベースファイル

export const parameters = {
  actions: { argTypesRegex: '^on[A-Z].*' },
  controls: {
    matchers: {
      color: /(background|color)$/i,
      date: /Date$/,
    },
  },
};

10. アドオン設定確認

インストールされているアドオンが正常に動作しているかを確認します。

bashCopy code# インストール済みアドオンの確認
yarn list | grep @storybook

問題のあるアドオンを特定するため、アドオンを一つずつ無効化してテストします。

javascriptCopy code// .storybook/main.js でアドオンを段階的に確認
module.exports = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: [
    '@storybook/addon-essentials',
    // 他のアドオンを一時的にコメントアウト
    // '@storybook/addon-interactions',
    // '@storybook/addon-docs'
  ],
};

高度なトラブルシューティング（5 項目）

基本チェックと設定チェックで解決しない場合の高度な対処法です。

11. ブラウザコンソールエラー確認

ブラウザの開発者ツールで JavaScript エラーを詳しく調査します。

mermaidCopy codesequenceDiagram
    participant B as ブラウザ
    participant S as Storybook Server
    participant W as Webpack

    B->>S: ページリクエスト
    S->>W: バンドル生成
    W-->>S: バンドルファイル
    S-->>B: HTMLとJS配信
    B->>B: JS実行
    Note over B: エラー発生時は<br/>コンソールに出力

よくあるブラウザコンソールエラーと対処法：

エラーメッセージ	原因	対処法
ChunkLoadError	動的インポートの失敗	キャッシュクリア、再ビルド
TypeError: Cannot read properties	undefined オブジェクトへのアクセス	props や state の初期値設定
SyntaxError: Unexpected token	JavaScript 構文エラー	該当ファイルの構文確認

12. Storybook ログ解析

ターミナルに出力される Storybook のログを詳しく解析します。

bashCopy code# 詳細ログ出力でStorybook起動
yarn storybook --loglevel verbose

ログの重要なセクション：

bashCopy code# 1. 依存関係解決フェーズ
info => Loading presets
info => Loading custom manager config

# 2. webpack設定フェーズ
info => Using default Webpack5 setup
info => Loading 1 config file in "./.storybook"

# 3. ビルドフェーズ
webpack built preview [hash] in [time]ms

エラーログの解読例：

bashCopy code# よくあるエラーログパターン
ERROR in ./src/components/Button/Button.stories.tsx
Module not found: Error: Can't resolve './Button'

13. 開発環境固有の問題

異なる環境間での動作差異を確認します。

bashCopy code# 環境変数の確認
echo $NODE_ENV
echo $PATH

# システム情報の確認
uname -a  # Linux/macOS
systeminfo  # Windows

Docker 環境での実行確認：

dockerfileCopy code# Dockerfile.storybook
FROM node:18-alpine

WORKDIR /app
COPY package.json yarn.lock ./
RUN yarn install

COPY . .
EXPOSE 6006

CMD ["yarn", "storybook"]

14. CI/CD 環境での問題

継続的インテグレーション環境での Storybook ビルド失敗を解決します。

yamlCopy code# .github/workflows/storybook.yml
name: Build Storybook
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'yarn'

      - name: Install dependencies
        run: yarn install --frozen-lockfile

      - name: Build Storybook
        run: yarn build-storybook

CI 環境特有の設定：

javascriptCopy code// .storybook/main.js でCI環境用設定
const isCI = process.env.CI === 'true';

module.exports = {
  // ... 他の設定
  features: {
    // CI環境では詳細チェックを無効化
    buildStoriesJson: !isCI,
  },
};

15. バージョンアップグレード対応

Storybook のメジャーバージョンアップ時の問題に対処します。

bashCopy code# Storybookの自動アップグレード
npx storybook@latest upgrade

手動でのバージョン確認と更新：

bashCopy code# 現在のバージョン確認
npx storybook --version

# 利用可能な最新版確認
npm view @storybook/react versions --json

アップグレード後の設定ファイル調整例：

javascriptCopy code// Storybook 7.x への移行例
// 旧: .storybook/main.js (v6.x)
module.exports = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: ['@storybook/addon-essentials'],
  framework: '@storybook/react',
};

// 新: .storybook/main.js (v7.x)
module.exports = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: ['@storybook/addon-essentials'],
  framework: {
    name: '@storybook/react-webpack5',
    options: {},
  },
};

具体例

実際のエラーケースと解決手順

ここでは、実際によく遭遇するエラーケースと具体的な解決手順をご紹介します。

ケース 1: "Cannot resolve module" エラー

bashCopy codeError: Cannot resolve module '@storybook/react' from '/project/.storybook/main.js'

解決手順：

1. 依存関係の確認

bashCopy code# @storybook/reactがインストールされているか確認
yarn list @storybook/react

2. 足りない依存関係のインストール

bashCopy codeyarn add -D @storybook/react @storybook/addon-essentials

3. バージョン整合性の確認

jsonCopy code// package.json での整合性確認
{
  "devDependencies": {
    "@storybook/react": "^7.5.0",
    "@storybook/addon-essentials": "^7.5.0"
  }
}

ケース 2: TypeScript 関連エラー

bashCopy codeERROR in ./src/components/Button/Button.stories.tsx
TS2307: Cannot find module './Button' or its corresponding type declarations.

解決手順：

1. TypeScript 設定ファイルの確認

jsonCopy code// .storybook/tsconfig.json
{
  "extends": "../tsconfig.json",
  "compilerOptions": {
    "moduleResolution": "node",
    "allowSyntheticDefaultImports": true
  }
}

2. インポートパスの修正

typescriptCopy code// 修正前
import { Button } from './Button';

// 修正後（拡張子を明記）
import { Button } from './Button.tsx';
// または絶対パスを使用
import { Button } from '@/components/Button/Button';

ケース 3: CSS/スタイルが適用されない

コンポーネントは表示されるがスタイルが適用されない場合の解決方法です。

javascriptCopy code// .storybook/preview.js でグローバルスタイルをインポート
import '../src/styles/globals.css';
import '../src/index.css';

export const parameters = {
  // ... 他の設定
};

よくあるエラーメッセージと対処法

エラーメッセージ	主な原因	解決方法
EADDRINUSE: address already in use	ポート競合	別ポート使用または既存プロセス終了
Module build failed: ModuleNotFoundError	依存関係不足	該当モジュールのインストール
Invalid configuration object	webpack 設定エラー	設定ファイルの構文確認
Cannot read properties of undefined	プロパティアクセスエラー	初期値設定の確認
ChunkLoadError: Loading chunk failed	動的読み込みエラー	キャッシュクリアと再ビルド

まとめ

チェック項目の優先順位

Storybook の問題解決は以下の順序で進めることをお勧めします：

最優先（5 分以内で確認）

1. Node.js/npm バージョン確認
2. 依存関係の再インストール
3. キャッシュクリア

次優先（15 分以内で確認） 4. ポート競合確認 5. 基本設定ファイル確認 6. .storybook/main.js 設定確認

詳細確認（30 分以内で確認）
7. webpack 設定の問題 8. TypeScript 設定確認 9. CSS/スタイル設定問題 10. アドオン設定確認

高度な対処（1 時間以内で確認） 11. ブラウザコンソールエラー確認 12. Storybook ログ解析
13. 開発環境固有の問題 14. CI/CD 環境での問題 15. バージョンアップグレード対応

予防策の提案

今後同様の問題を避けるために、以下の予防策を実施することをお勧めします：

開発環境の標準化

jsonCopy code// .nvmrc でNode.jsバージョンを固定
18.17.0

jsonCopy code// package.json でengines指定
{
  "engines": {
    "node": ">=18.17.0",
    "yarn": ">=1.22.0"
  }
}

定期的なメンテナンス

bashCopy code# 月次で実行する定期メンテナンスコマンド
# 1. 依存関係の更新確認
yarn outdated

# 2. セキュリティ監査
yarn audit

# 3. キャッシュクリア
yarn cache clean

CI/CD での自動チェック

yamlCopy code# GitHub Actions でのStorybook ビルドテスト
- name: Test Storybook build
  run: |
    yarn install --frozen-lockfile
    yarn build-storybook

これらの 15 のチェックポイントを順序立てて実施することで、Storybook の起動やビルドに関する多くの問題を解決できるはずです。まずは基本チェックから始めて、段階的に問題を特定していきましょう。

関連リンク

• Storybook 公式ドキュメント
• Storybook トラブルシューティングガイド
• Webpack 設定リファレンス
• TypeScript + Storybook 設定ガイド
• Storybook GitHub リポジトリ