inertia-rails-setup

Inertia Rails のセットアップ

このスキルでは、好みのフロントエンドフレームワークを使って、Ruby on Rails アプリケーションに Inertia.js をセットアップする方法を説明します。

おすすめ：公式スターターキット

新しいプロジェクトで手早く始めるには、公式スターターキットをクローンするのが最適です。スターターキットには、認証、shadcn/ui コンポーネント、TypeScript、オプションの SSR サポートが最初から含まれています。

React スターターキット（おすすめ）

git clone https://github.com/inertia-rails/react-starter-kit myapp
cd myapp
bin/setup

含まれる機能：

• React 19 + TypeScript
• shadcn/ui コンポーネントライブラリ（20 個以上のコンポーネント）
• ユーザー認証（ログイン、登録、パスワードのリセット）
• 設定ページ（プロフィール、パスワード、メールアドレス、セッション、外観）
• 複数のレイアウト（サイドバー、ヘッダー、認証用の各種レイアウト）
• ダークモード対応
• Kamal デプロイ設定
• オプションの SSR サポート
• Sonner トースト通知によるフラッシュメッセージ

Vue スターターキット

git clone https://github.com/inertia-rails/vue-starter-kit myapp
cd myapp
bin/setup

Svelte スターターキット

git clone https://github.com/inertia-rails/svelte-starter-kit myapp
cd myapp
bin/setup

スターターキットのカスタマイズ

クローンした後：

1. アプリ名を変更します：

   # Update config/application.rb
   module YourAppName
     class Application < Rails::Application
   

2. データベース設定を更新します：

   # Edit config/database.yml with your settings
   

3. 不要なサンプルページを削除します：

   # Delete from app/frontend/pages/ and corresponding controllers
   

4. 独自のページを追加します：

   bin/rails generate controller Products index show
   # Create app/frontend/pages/products/index.tsx
   

5. レイアウトをカスタマイズします：

   • メインアプリは app/frontend/layouts/app-layout.tsx を編集します
   • ナビゲーションは app/frontend/components/nav-main.tsx を編集します

---

別の方法：ジェネレーターを使ったセットアップ

ゼロから始める場合や、既存の Rails アプリに Inertia を追加する場合は、次の方法を使います。

クイックセットアップ

# Create new Rails app (if needed)
rails new myapp --skip-javascript

# Add inertia_rails gem
bundle add inertia_rails

# Run the generator
bin/rails generate inertia:install

ジェネレーターでは、次の項目を選択します：

• フロントエンドフレームワーク（React、Vue、Svelte）
• TypeScript のサポート
• Tailwind CSS の統合

手動セットアップの手順

1. Gem を追加する

# Gemfile
gem 'inertia_rails'

bundle install

2. Vite Rails をインストールする（まだの場合）

bundle add vite_rails
bundle exec vite install

3. ルートレイアウトを設定する

app/views/layouts/application.html.erb を作成または更新します：

<!DOCTYPE html>
<html>
  <head>
    <meta name="viewport" content="width=device-width,initial-scale=1">
    <%= csp_meta_tag %>
    <%= inertia_ssr_head %>
    <%= vite_client_tag %>
    <%= vite_javascript_tag 'application' %>
  </head>
  <body>
    <%= yield %>
  </body>
</html>

4. フロントエンドの依存関係をインストールする

React の場合：

npm install @inertiajs/react @inertiajs/vite react react-dom

Vue 3 の場合：

npm install @inertiajs/vue3 @inertiajs/vite vue

Svelte の場合：

npm install @inertiajs/svelte @inertiajs/vite svelte

5. フロントエンドのエントリーポイントを設定する

app/frontend/entrypoints/application.js を作成します：

React：

import { createInertiaApp } from '@inertiajs/react'
import { createRoot } from 'react-dom/client'
import { inertia } from '@inertiajs/vite'

createInertiaApp({
  resolve: inertia.resolvePages('../pages'),
  setup({ el, App, props }) {
    createRoot(el).render(<App {...props} />)
  },
})

Vue 3：

import { createApp, h } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import { inertia } from '@inertiajs/vite'

createInertiaApp({
  resolve: inertia.resolvePages('../pages'),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .mount(el)
  },
})

Svelte：

import { createInertiaApp } from '@inertiajs/svelte'
import { inertia } from '@inertiajs/vite'

createInertiaApp({
  resolve: inertia.resolvePages('../pages'),
  setup({ el, App }) {
    new App({ target: el })
  },
})

6. ページディレクトリを作成する

mkdir -p app/frontend/pages

7. イニシャライザーを設定する

config/initializers/inertia_rails.rb を作成します：

# frozen_string_literal: true

InertiaRails.configure do |config|
  # Asset versioning
  config.version = -> { ViteRuby.digest }

  # Flash keys exposed to frontend
  config.flash_keys = %i[notice alert]

  # Required for Inertia.js v3
  config.use_script_element_for_initial_page = true
  config.use_data_inertia_head_attribute = true
  config.always_include_errors_hash = true

  # Deep merge shared data with page props
  # config.deep_merge_shared_data = true

  # Encrypt history for sensitive data (requires HTTPS)
  # config.encrypt_history = Rails.env.production?
end

8. 共有データを設定する

app/controllers/application_controller.rb で設定します：

class ApplicationController < ActionController::Base
  inertia_share do
    {
      flash: {
        notice: flash.notice,
        alert: flash.alert
      },
      auth: {
        user: current_user&.as_json(only: [:id, :name, :email])
      }
    }
  end
end

9. 最初のページを作成する

コントローラー：

# app/controllers/home_controller.rb
class HomeController < ApplicationController
  def index
    render inertia: { message: 'Welcome to Inertia Rails!' }
  end
end

ルート：

# config/routes.rb
Rails.application.routes.draw do
  root 'home#index'
end

ページコンポーネント（React）：

// app/frontend/pages/home/index.jsx
export default function Home({ message }) {
  return (
    <div>
      <h1>{message}</h1>
    </div>
  )
}

ページコンポーネント（Vue）：

<script setup>
defineProps(['message'])
</script>

<template>
  <div>
    <h1>{{ message }}</h1>
  </div>
</template>

10. 開発サーバーを起動する

# Terminal 1: Rails server
bin/rails server

# Terminal 2: Vite dev server
bin/vite dev

設定オプションのリファレンス

オプション	デフォルト	説明
version	nil	キャッシュを無効化するためのアセットバージョン
layout	'application'	デフォルトのレイアウトテンプレート
flash_keys	[:notice, :alert]	共有するフラッシュキー
deep_merge_shared_data	false	プロパティをディープマージする
encrypt_history	false	ブラウザー履歴を暗号化する
ssr_enabled	false	SSR を有効にする
ssr_url	'http://localhost:13714'	SSR サーバーの URL
default_render	false	Inertia を自動でレンダリングする
root_dom_id	'app'	ルート要素の ID
use_script_element_for_initial_page	false	初期ページのデータに <script> タグを使用する（v3 で必須）
use_data_inertia_head_attribute	false	head タグに data-inertia 属性を使用する（v3 で必須）
always_include_errors_hash	nil	ページプロパティに errors オブジェクトを常に含める
prop_transformer	identity	プロパティキーを変換する（例：camelCase）
component_path_resolver	"path/action"	コンポーネント名のカスタム解決
parent_controller	'::ApplicationController'	静的ルートのベースコントローラー
expose_shared_prop_keys	true	ページメタデータに共有プロパティのキーを含める
precognition_prevent_writes	false	プリコグニション中の DB 書き込みを防ぐ

環境変数

すべての設定オプションは、INERTIA_ プレフィックス付きの環境変数でも設定できます：

INERTIA_SSR_ENABLED=true
INERTIA_ENCRYPT_HISTORY=true

Inertia.js v3 へのアップグレード

既存の Inertia.js v2 プロジェクトをアップグレードする場合：

必須の設定変更

Inertia Rails のイニシャライザーに、以下を追加します。

config.use_script_element_for_initial_page = true
config.use_data_inertia_head_attribute = true
config.always_include_errors_hash = true

破壊的変更

• React 19+ が必要です
• Svelte 5+ と Runes 構文が必要です
• ES2022 のビルドターゲットが必要です
• ESM のみ — CommonJS はサポートされません
• Axios を削除 — 組み込みの XHR を使用します（Axios を引き続き使用するには axiosAdapter() を使用してください）
• イベント名の変更：invalid → httpException、exception → networkError
• router.cancel() → router.cancelAll()
• Head の属性：inertia → data-inertia

Vite プラグインをインストールする

npm install @inertiajs/vite

vite.config.js を更新します。

import inertia from '@inertiajs/vite'

export default defineConfig({
  plugins: [
    inertia(),
    // ... other plugins
  ],
})

Vite プラグインは、以下を提供します。

• ページコンポーネントの自動解決
• SSR のセットアップの簡略化（開発時に別のエントリーポイントが不要）
• プロバイダー／プラグイン向けの withApp コールバック

トラブルシューティング

「Cannot find module '@inertiajs/react'」

npm install を実行して、依存関係をインストールしてください。

エラーが表示されず、ページが真っ白になる

ブラウザーのコンソールで JavaScript のエラーを確認してください。Vite 開発サーバーが実行中であることを確認してください。

Props が更新されない

render json: ではなく、render inertia: を使用していることを確認してください。

CSRF トークンのエラー

Inertia は CSRF を自動的に処理します。protect_from_forgery が有効になっていることを確認してください。