inertia-rails-setup

Inertia Rails 设置

此技能可帮助你在 Ruby on Rails 应用中设置 Inertia.js，并选择所需的前端框架。

推荐：官方 Starter Kit

对于新项目，最快的入门方式是克隆官方 Starter Kit。开箱即用地提供身份验证、shadcn/ui 组件、TypeScript 和可选的 SSR 支持。

React Starter Kit（推荐）

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

包含：

• React 19 + TypeScript
• shadcn/ui 组件库（20+ 个组件）
• 用户身份验证（登录、注册、密码重置）
• 设置页面（个人资料、密码、电子邮件、会话、外观）
• 多种布局（侧边栏、页眉、身份验证变体）
• 深色模式支持
• Kamal 部署配置
• 可选的 SSR 支持
• 使用 Sonner toast 的闪信

Vue Starter Kit

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

Svelte Starter Kit

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

自定义 Starter Kit

克隆后：

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，设置导航

---

备选方案：生成器设置

如果你更倾向于从头开始，或将 Inertia 添加到现有 Rails 应用中：

快速设置

# 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	深度合并 props
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	始终在页面 props 中包含 errors 对象
prop_transformer	identity	转换 prop 键（例如，camelCase）
component_path_resolver	"path/action"	自定义组件名称解析
parent_controller	'::ApplicationController'	静态路由的基控制器
expose_shared_prop_keys	true	在页面元数据中包含共享 prop 键
precognition_prevent_writes	false	预感知期间阻止数据库写入

环境变量

所有配置选项均可通过带有 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+
• 需要使用 runes 语法的 Svelte 5+
• 需要 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 inertia:，而不是 render json:。

CSRF 令牌错误

Inertia 会自动处理 CSRF。确保已启用 protect_from_forgery。