inertia-rails-setup

Inertia Rails プロジェクトのセットアップ

スタックを検出し、推奨する依存関係を提示して、CLAUDE.md の設定を生成します。

プロジェクトごとに一度実行します。 スタックが変更された場合は、再実行してください。

絶対に行わないでください：

• Gemfile に inertia_rails gem がない状態でセットアップを実行すること。すべてのスキルはこの gem が存在することを前提としています。見つからない場合は、まずインストールするようユーザーに伝えてください。
• 既存の ## Inertia Rails Stack を読み込まずに CLAUDE.md で上書きすること。ユーザーが手動でカスタマイズしている可能性があります。自動生成されたブロックのみを置き換えてください。
• vite.config.ts に @/ の解決エイリアスを追加すること。vite-plugin-ruby がすでに提供しています。追加するのは tsconfig.json のみです。
• プロジェクトで jbuilder が使われていて、ユーザーが切り替えに関心を示していない場合に alba-inertia を推奨すること。提案はしても、強く勧めないでください。プロジェクトで blueprinter が使われている場合は、直接的なアップグレード先として提案できます。
• ユーザーがインストールしていないスキルの CLAUDE.md ブロックを生成すること。「alba-inertia スキルは適用されません」と伝えるのは正しいですが、gem が存在しないのに「alba-inertia を使ってください」と伝えるのは誤りです。

ステップ 1：現在のスタックを検出する

Gemfile（Gemfile.lockではありません）と package.json を読み込み、以下を確認します。

確認対象	意味
inertia_rails gem	Inertia Rails がインストール済み（必須）
package.json の @inertiajs/react	React フロントエンド
package.json の @inertiajs/vue3	Vue 3 フロントエンド
package.json の @inertiajs/svelte	Svelte フロントエンド
alba-inertia gem	規約ベースのレンダリングが有効
alba と typelizer gems（alba-inertia なし）	規約ベースのレンダリングを使わない Alba シリアライゼーション
pagy gem	Pagy ページネーション
kaminari gem	Kaminari ページネーション
rspec-rails gem	RSpec テスト
js-routes gem	型付きフロントエンド用パスヘルパー
devise gem	Devise 認証
pundit gem	Pundit 認可
action_policy gem	Action Policy 認可
ルートに components.json が存在する	shadcn がインストール済み（React：shadcn/ui、Vue：shadcn-vue、Svelte：shadcn-svelte）

ステップ 2：不足している依存関係を推奨する

検出したスタックを提示した後、スキルの機能を利用可能にする依存関係のうち、まだインストールされていないものを提案します。複数選択可能な AskUserQuestion を使用して、推奨項目を提示してください。

不足しているものだけを推奨します。 ステップ 1 ですでに検出された項目は省略してください。

依存関係	種類	インストールコマンド	利用可能になる機能
alba + typelizer + alba-inertia	gems	bundle add alba typelizer alba-inertia	規約ベースのレンダリング、Ruby からの TypeScript 型の自動生成。render inertia: { ... } の定型コードと手動の TS インターフェースが不要になります。alba-inertia スキルが利用可能になります。
js-routes	gem	bundle add js-routes	React で型付きパスヘルパー（usersPath()、userPath(id)）を利用でき、URL 文字列をハードコードする必要がなくなります。
pagy	gem	bundle add pagy	Inertia と相性のよいメタデータを備えた軽量なページネーション。
shadcn/ui（React）	npx	npx shadcn@latest init	Inertia 用に調整された、構築済みの React コンポーネント。shadcn-inertia スキルが利用可能になります。
shadcn-vue（Vue）	npx	npx shadcn-vue@latest init	Inertia 用に調整された、構築済みの Vue コンポーネント。shadcn-vue-inertia スキルが利用可能になります。
shadcn-svelte（Svelte）	npx	npx shadcn-svelte@latest init	Inertia 用に調整された、構築済みの Svelte コンポーネント（bits-ui）。shadcn-svelte-inertia スキルが利用可能になります。

ユーザーが明らかに別の選択肢を選んでいる場合、その代替となる gem は推奨しないでください（例：Kaminari がある場合に Pagy を提案しないでください。ただし、プロジェクトで jbuilder または blueprinter が使われている場合は alba を提案できます）。

ステップ 3：選択された依存関係をインストールする

依存関係ごとのインストール後のスキャフォールディング：

1. alba-inertia — ApplicationResource もスキャフォールディングします：

   # app/resources/application_resource.rb
   class ApplicationResource
     include Alba::Resource
     helper Typelizer::DSL
     helper Alba::Inertia::Resource
     include Rails.application.routes.url_helpers
   end
   

   Typelizer のイニシャライザーも追加します：

   # config/initializers/typelizer.rb
   Typelizer.configure do |config|
     config.output_dir = Rails.root.join("app/frontend/types/generated")
   end
   

2. js-routes — ジェネレーターが存在する場合は rails generate js_routes を実行します
3. shadcn — フレームワークに応じて初期化します：
   • React：npx shadcn@latest init
   • Vue：npx shadcn-vue@latest init
   • Svelte：npx shadcn-svelte@latest init 初期化後、tsconfig.json に @/ の解決エイリアスが存在しない場合は追加します

ステップ 4：CLAUDE.md を生成する

プロジェクトルートにある CLAUDE.md を探すか、作成します。## Inertia Rails Stack が 存在する場合は、次の ## またはファイル末尾までを置き換えます。存在しない場合は、末尾に追加します。

必須 — CLAUDE.md のブロックを組み立てる前に、ファイル全体を読むこと： references/claude-md-templates.md（約90行）— 各スタック構成（シリアライズ、UI、ページネーション、テスト、ルーティング、 認可）に対応するすべてのテンプレートブロックが含まれています。検出したスタックに基づいて、カテゴリごとに1つのブロックを選びます。

ステップ 4 までテンプレートファイルを読み込まないでください — ステップ 1〜3 で使用するブロックを決定します。

トラブルシューティング

症状	原因	対処方法
npx shadcn@latest init が "No framework detected" で失敗する	vite.config.ts がないか、設定が誤っている	init の実行前に、vite-plugin-ruby が設定され、package.json に tailwindcss が含まれていることを確認します
Typelizer が誤ったディレクトリに型を生成する	initializer に output_dir がないか、設定が誤っている	config/initializers/typelizer.rb を追加し、config.output_dir = Rails.root.join("app/frontend/types/generated") を設定します
@/ インポートが解決されない	tsconfig.json ではなく vite.config.ts にエイリアスが追加されている	vite-plugin-ruby が Vite のエイリアスを処理するため、TypeScript 用の @/ パスが必要なのは tsconfig.json のみです
CLAUDE.md に矛盾する指示がある	## Inertia Rails Stack セクションが複数存在する	重複を削除します — 自動生成されたブロックは1つだけにしてください
スキルが alba-inertia を参照しているが、インストールされていない	セットアップが実行されていない、または alba が選択されていない	セットアップを再実行します。gem が存在しない場合、CLAUDE.md には「alba-inertia skill DOES NOT apply」と記載されているはずです
js_routes:generate が失敗する	js-routes gem はインストールされているが、ジェネレーターがまだ実行されていない	まず rails generate js_routes を実行して設定ファイルを作成し、その後 rails js_routes:generate を実行します

ステップ 5：概要

ユーザーに以下を伝えます。

1. インストールされたもの
2. 使用しているスタックに関連するスキル（および無視するスキル）
3. CLAUDE.md の ## Inertia Rails Stack を確認すること — 個々のスキルにある一般的な例よりも優先されます