Back to Details

inertia-rails

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<essential_principles>
<essential_principles>

How Inertia Rails Works

Inertia Rails 工作原理

Inertia is a bridge between Rails and modern JavaScript frameworks (React, Vue, Svelte). It lets you build SPAs using classic server-side routing and controllers—no client-side routing or separate APIs needed.
Inertia 是Rails与现代JavaScript框架（React、Vue、Svelte）之间的桥梁。它允许你使用经典的服务器端路由和控制器来构建单页应用（SPA）——无需客户端路由或独立的API。

1. Server-Driven Architecture

1. 服务器驱动架构

Controllers render Inertia responses instead of views. Data flows from Rails to JavaScript components as props:
ruby
render inertia: 'Users/Show', props: { user: user.as_json }
控制器渲染Inertia响应而非视图。数据以props的形式从Rails流向JavaScript组件：
ruby
render inertia: 'Users/Show', props: { user: user.as_json }

2. No Client-Side Routing

2. 无客户端路由

Routes live in 
config/routes.rb
. Inertia intercepts link clicks and form submissions, making XHR requests that return JSON with component name and props. The client swaps components without full page reloads.
路由定义在
config/routes.rb
中。Inertia会拦截链接点击和表单提交，发起XHR请求，返回包含组件名称和props的JSON数据。客户端无需重新加载整个页面即可切换组件。

3. Convention-Based Component Resolution

3. 基于约定的组件解析

By default, 
render inertia: { user: }
in 
UsersController#show
renders 
app/frontend/pages/users/show.(jsx|vue|svelte)
. Override with explicit component names when needed.
默认情况下，
UsersController#show
中的
render inertia: { user: }
会渲染
app/frontend/pages/users/show.(jsx|vue|svelte)
组件。必要时可通过显式指定组件名称来覆盖默认规则。

4. Validation via Redirects

4. 通过重定向实现验证

Unlike typical SPAs returning 422 JSON responses, Inertia follows traditional Rails patterns:
  1. Controller validates and redirects back on failure
  2. Errors are flashed and shared as props
  3. Form state is preserved automatically
与典型SPA返回422 JSON响应不同，Inertia遵循传统Rails模式：
  1. 控制器验证失败时重定向回原页面
  2. 错误信息会被闪存并作为props共享
  3. 表单状态会自动保留

5. Shared Data Pattern

5. 共享数据模式

Use 
inertia_share
in controllers to provide data to all pages (current_user, flash messages, notifications). Data is included in every response—use sparingly. </essential_principles>
<intake> **What would you like to do?**
  1. Set up Inertia in a Rails project
  2. Create a new page/component
  3. Build a form with validation
  4. Add shared data (auth, flash, etc.)
  5. Handle redirects and navigation
  6. Debug an Inertia issue
  7. Test an Inertia controller
  8. Optimize with partial reloads
  9. Something else
Wait for response before proceeding. </intake>
<routing> | Response | Workflow | |----------|----------| | 1, "setup", "install", "start", "new" | `workflows/setup-inertia.md` | | 2, "page", "component", "create", "render" | `workflows/create-page.md` | | 3, "form", "validation", "submit", "useForm" | `workflows/build-form.md` | | 4, "shared", "auth", "flash", "current_user" | `workflows/shared-data.md` | | 5, "redirect", "navigate", "link", "router" | `workflows/navigation.md` | | 6, "debug", "fix", "error", "not working" | `workflows/debug-inertia.md` | | 7, "test", "spec", "minitest", "rspec" | `workflows/testing.md` | | 8, "partial", "reload", "optimize", "only" | `workflows/partial-reloads.md` | | 9, other | Clarify, then select workflow or references |
After reading the workflow, follow it exactly. </routing>
<verification_loop>
在控制器中使用
inertia_share
可为所有页面提供数据（如current_user、闪存消息、通知）。这些数据会包含在每个响应中——请谨慎使用。 </essential_principles>
<intake> **你想要进行什么操作？**
  1. 在Rails项目中搭建Inertia
  2. 创建新页面/组件
  3. 构建带验证的表单
  4. 添加共享数据（身份验证、闪存等）
  5. 处理重定向与导航
  6. 调试Inertia问题
  7. 测试Inertia控制器
  8. 用部分加载优化性能
  9. 其他操作
请先回复，再继续下一步。 </intake>
<routing> | 响应内容 | 工作流 | |----------|----------| | 1, "setup", "install", "start", "new" | `workflows/setup-inertia.md` | | 2, "page", "component", "create", "render" | `workflows/create-page.md` | | 3, "form", "validation", "submit", "useForm" | `workflows/build-form.md` | | 4, "shared", "auth", "flash", "current_user" | `workflows/shared-data.md` | | 5, "redirect", "navigate", "link", "router" | `workflows/navigation.md` | | 6, "debug", "fix", "error", "not working" | `workflows/debug-inertia.md` | | 7, "test", "spec", "minitest", "rspec" | `workflows/testing.md` | | 8, "partial", "reload", "optimize", "only" | `workflows/partial-reloads.md` | | 9, other | 先明确需求，再选择对应工作流或参考文档 |
阅读工作流后，请严格按照其步骤操作。 </routing>
<verification_loop>

After Every Change

每次修改后需检查

  1. Does the page render? Check Rails logs for Inertia response
  2. Are props received? Console.log props in component
  3. Does navigation work? Click links - should not full-reload
  4. Do forms submit? Check Network tab for XHR requests
  5. Are errors displayed? Test validation failures
ruby
undefined
  1. 页面是否正常渲染？ 查看Rails日志中的Inertia响应
  2. 是否接收到props？ 在组件中用console.log打印props
  3. 导航是否正常工作？ 点击链接——不应触发整页刷新
  4. 表单是否能提交？ 在网络标签页查看XHR请求
  5. 错误信息是否显示？ 测试验证失败场景
ruby
undefined

Rails debug - check response type

Rails调试 - 检查响应类型

render inertia: 'Page', props: { debug: true }

```javascript
// Frontend debug - log all props
console.log(usePage().props)
Report to the user:
  • "Inertia response: ✓"
  • "Props received: X keys"
  • "Navigation: SPA mode ✓/✗"
  • "Ready for testing" </verification_loop>
<reference_index>
render inertia: 'Page', props: { debug: true }

```javascript
// 前端调试 - 打印所有props
console.log(usePage().props)
向用户反馈：
  • "Inertia响应: ✓"
  • "接收到的props数量: X个"
  • "导航: SPA模式 ✓/✗"
  • "已准备好测试" </verification_loop>
<reference_index>

Domain Knowledge

领域知识

All in 
references/
:
Core: setup.md, responses.md, forms.md, validation.md Data Flow: shared-data.md, links.md Quality: testing.md Cookbook: cookbook.md (shadcn/ui, Inertia Modal, meta tags, error types) </reference_index>
<workflows_index>
所有内容位于
references/
目录下：
核心内容: setup.md, responses.md, forms.md, validation.md 数据流: shared-data.md, links.md 质量保障: testing.md 实用指南: cookbook.md（shadcn/ui、Inertia模态框、元标签、错误类型） </reference_index>
<workflows_index>

Workflows

工作流

All in 
workflows/
:
FilePurpose
setup-inertia.mdInstall and configure Inertia Rails
create-page.mdBuild new pages with props
build-form.mdForms with validation and useForm
shared-data.mdShare auth/flash across all pages
navigation.mdLinks, redirects, router methods
debug-inertia.mdFind and fix Inertia issues
testing.mdTest Inertia controllers
partial-reloads.mdOptimize with selective data loading
</workflows_index>
所有内容位于
workflows/
目录下：
文件用途
setup-inertia.md安装并配置Inertia Rails
create-page.md构建带props的新页面
build-form.md构建带验证的表单及useForm使用
shared-data.md在所有页面共享身份验证/闪存数据
navigation.md链接、重定向、路由方法
debug-inertia.md排查并修复Inertia问题
testing.md测试Inertia控制器
partial-reloads.md用选择性数据加载优化性能
</workflows_index>