storybook-rsbuild

Storybook Rsbuild

目標

Rsbuild で Storybook をセットアップするか、既存の Storybook を移行します。バージョンの互換性、パッケージ名、インストールコマンド、設定の変換パターンなど、正確な情報は上流のドキュメント storybook.rsbuild.rs にあります。このスキルは作業の振り分けと行動チェックリストを担い、ドキュメントの内容を重複して記載するものではありません。

原則（必ず従うこと）

1. 信頼できる情報源は上流のドキュメントです。 バージョン表、インストールコマンド、設定の変換パターンについて、該当する storybook.rsbuild.rs のページを取得してください。トレーニングで得た知識をもとに、バージョン指定やパッケージ名を推測しないでください。エコシステムの変化はモデルの既存知識より速いためです。

2. フレームワークガイドの Requirements テーブルをもとにバージョンを固定します。 各フレームワークガイドのページ（例：https://storybook.rsbuild.rs/guide/framework/react）には、標準となる互換バージョン範囲が記載された Requirements セクションがあります。バージョン指定の正規の情報源はここです。新規セットアップでは、最新の安定版 storybook メジャーバージョンと、それに対応する storybook-rsbuild メジャーバージョンをインストールしてください。ほかの場所にあるコードスニペットのバージョン番号をもとに固定しないでください。正規の情報源はドキュメントのみです。

3. @rsbuild/core を直接指定します。 storybook-<framework>-rsbuild は @rsbuild/core をピア依存関係として指定していますが、バージョン指定とロックファイルの監査を明確にし、将来フレームワークパッケージのリリースでピア依存関係が削除されてもビルドが予期せず壊れないよう、プロジェクト自身の devDependencies にも @rsbuild/core を追加してください。

4. 移行は順序の決まった2つのフェーズを実行する1つの作業です。両方とも必須です。 フェーズA：新しいフレームワークパッケージをインストールして設定を更新します。旧フレームワークパッケージ、旧ビルダーパッケージ、旧 webpackFinal／viteFinal ブロックはそのまま残し、検証でロールバックできる状態にしておきます。フェーズB：検証に合格したら、同じ作業内ですぐに旧フレームワークパッケージ（例：@storybook/react-webpack5、@storybook/vue3-vite）、旧ビルダーパッケージ（例：@storybook/builder-webpack5、@storybook/builder-vite）、旧 webpackFinal／viteFinal ブロックを削除します。両方のビルダーのフレームワークパッケージが package.json に残ったまま終了する移行は未完了です。これらを残すことは、このスキルの評価で最もよく見られる、気付かれにくいリグレッションです。フェーズAだけでは有効な終了地点になりません。検証を実行した場合は、クリーンアップも必ず実行してください。

5. アドオンを保持し、黙って削除しないでください。 移行時、webpack 専用アドオン（例：@storybook/addon-styling-webpack）は、webpackAddons を介して渡し（上流の自動変換に処理させる）、または Rsbuild ネイティブの同等パイプライン（@rsbuild/plugin-postcss、tools.postcss など）に置き換える必要があります。スタイリングアドオンを削除し、storybook build に合格しても、ストーリーのツリー表示が視覚的に壊れている移行はリグレッションです。

6. 作業範囲を守ります。 モノレポでは、ストーリーをホストするパッケージのみを変更してください。移行に厳密に必要な場合を除き、ビジネスソースファイルは編集しないでください。

ステップ1 — シナリオの判定

package.json とプロジェクト構成を確認し、既存の Storybook の状態を判定します。

1. .storybook/ ディレクトリを確認します（モノレポの場合は、ルートと各パッケージの両方を確認します）
2. package.json にある storybook スクリプト、または依存関係／devDependencies 内の @storybook/*／storybook-*-rsbuild を確認します
3. Storybook が存在し、すでに storybook-*-rsbuild を使用している場合 → セットアップ済みです。必要に応じて設定またはトラブルシューティングに進みます
4. Storybook が存在し、Rsbuild 以外のビルダー（@storybook/*-webpack5、@storybook/*-vite など）を使用している場合 → 移行ワークフローに進みます
5. Storybook が見つからない場合 → 新規セットアップワークフローに進みます

---

新規セットアップのワークフロー

1. エコシステムとの統合を検出する

package.json の dependencies と devDependencies を確認し、次の順に調べます。

シグナル	エコシステム	統合ガイド
@rslib/core	Rslib	https://storybook.rsbuild.rs/guide/integrations/rslib
@modern-js/app-tools	Modern.js	https://storybook.rsbuild.rs/guide/integrations/modernjs
@rsbuild/core を含まない @rspack/core	Pure Rspack	https://storybook.rsbuild.rs/guide/integrations/rspack

該当する場合は、統合ガイドを読み、以下の手順と併せてその制約を上乗せして適用します。

2. UI フレームワークを検出する

アプリの依存関係（react、vue、lit など）から UI フレームワークを推定します。

UI フレームワーク	フレームワークパッケージ	ガイド
React	storybook-react-rsbuild	https://storybook.rsbuild.rs/guide/framework/react
Vue 3	storybook-vue3-rsbuild	https://storybook.rsbuild.rs/guide/framework/vue
Vanilla JS/TS	storybook-html-rsbuild	https://storybook.rsbuild.rs/guide/framework/vanilla
Web Components	storybook-web-components-rsbuild	https://storybook.rsbuild.rs/guide/framework/web-components
React Native Web	storybook-react-native-web-rsbuild	https://storybook.rsbuild.rs/guide/framework/react-native-web

3. Storybook をセットアップする

1. モノレポでは、ストーリーを配置するパッケージで作業します
2. 上記で該当したフレームワークガイドを読み、それに従います。storybook の最新の安定版メジャーバージョンと、対応する storybook-<framework>-rsbuild のメジャーバージョンをインストールします（原則 2）
3. @rsbuild/core を storybook-<framework>-rsbuild と並べて、devDependencies に直接追加します（原則 3）
4. .storybook/main.* で正しい framework: '<storybook-*-rsbuild>' を使用していることを確認します
5. package.json に storybook dev と storybook build のスクリプトがあることを確認します
6. ストーリーファイルがまだない場合は、検証の手順 2 でレンダリングできるように、最小限のサンプルストーリーを少なくとも 1 つ作成します（例：src/stories/Example.stories.*）
7. 以下の検証を実行します

移行ワークフロー

上流の移行ガイドを確認してください：https://storybook.rsbuild.rs/guide/migration

以下の手順を順番どおりに実行してください：

1. 移行タイプを判定する — .storybook/main.* の framework フィールドや core.builder、および package.json の依存関係を確認し、「from webpack5」か「from Vite」に分類して、移行ガイドの該当するセクションを選択します
2. バージョンの互換性を解決する — 移行ガイドの「Version compatibility」セクションを確認し、インストール済みの Storybook のバージョンに応じた storybook-rsbuild のメジャーバージョンを選択します
3. パッケージを置き換える — プロジェクトのパッケージマネージャー（ロックファイルから判定）を使って、移行ガイドのインストール／削除の対応表を適用します。移行に必要なパッケージのみ変更してください。新しいフレームワークパッケージと並行して、@rsbuild/core を直接の devDep として必ず追加してください（原則 3）。古いフレームワークパッケージや古い devDeps はまだ削除しないでください。削除するのは検証後です（原則 4）
4. .storybook/main.* を更新する — 検出したフレームワークに応じて、移行ガイドに記載されたとおりに設定を変更します
5. カスタムビルダーフックを移行する — 古いビルダーフック（webpackFinal／viteFinal）を検索し、見つかった場合は上流の設定ガイド（https://storybook.rsbuild.rs/guide/configuration）に従って変換します
6. アドオンの互換性に対処する — 最初はアドオンを変更せずに維持します。webpack 専用のアドオンを変更する必要がある場合は、上流の自動変換に任せるため webpackAddons 経由で指定するか、Rsbuild ネイティブの同等のアドオンに置き換えます。黙って削除してはいけません（原則 5）。推奨される対処法については、移行ガイドのアドオンセクションを参照してください
7. 検証してからクリーンアップする — 両方必須です — 以下の検証を実行します。検証に合格したら、完了を報告する前に、同じタスク内で以下のすべてを実行してください（原則 4）：
   • package.json の devDependencies から古いフレームワークパッケージを削除します（例：@storybook/react-webpack5、@storybook/vue3-webpack5、@storybook/react-vite、@storybook/vue3-vite、@storybook/html-webpack5、@storybook/web-components-webpack5 など）
   • 古いビルダーパッケージが個別に記載されている場合は削除します（例：@storybook/builder-webpack5、@storybook/builder-vite）
   • .storybook/main.* から古い webpackFinal／viteFinal ブロックを削除します
   • 利用するものがなくなった、古いビルダー専用の devDeps を削除します
   • pnpm install（またはプロジェクトのパッケージマネージャーに相当するコマンド）を再実行し、ロックファイルにクリーンアップの内容を反映します

バージョン表、パッケージ名、変換パターンなど、事実に基づく対応情報が必要で、このスキルに記載されていない場合は、上流のドキュメントを取得してください。推測してはいけません。

---

検証

1. storybook dev がエラーなしで起動する
2. ブラウザーで少なくとも 1 つのストーリーが正しく表示される（開発サーバーが問題なく起動するだけでは不十分です。stories の glob の不足やフレームワークの設定不備は、この段階で初めて明らかになることがあります）
3. HMR が動作する
4. storybook build が完了する
5. 起動ログを確認し、Rsbuild ビルダーが有効になっていることを確認する（webpack／vite ではないこと）

トラブルシューティング

• キャッシュの問題：node_modules/.cache/storybook を削除して再試行します
• 設定の残存：移行後に dev が失敗する場合は、問題を切り分けるため、一時的にカスタムの rsbuildFinal ブロックを削除してから、段階的に再追加します
• デバッグやその他の問題については、上流の移行ガイドの「Debugging」セクションと https://storybook.rsbuild.rs/guide/configuration を参照してください

エッジケース

• モノレポ：ストーリーをホストするパッケージを特定し、ルートではなくそのパッケージで作業します
• 複数の .storybook/ ディレクトリ：package.json のスクリプトで参照されているものを選択します
• TS パスエイリアス：移行後もエイリアスが維持されていることを確認します。rsbuildFinal の設定方法については、上流の設定ガイドを参照してください

設定

rsbuildFinal、ビルダーオプション、TypeScript、フレームワーク固有のオプションについては、https://storybook.rsbuild.rs/guide/configuration を確認してください