inertia-rails-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Inertia Rails Project Setup

Inertia Rails项目设置

Detect stack, offer recommended deps, generate CLAUDE.md configuration.

Run once per project. Re-run when the stack changes.

NEVER:

Run setup without
```
inertia_rails
```
gem in Gemfile — all skills assume it exists. If missing, tell the user to install it first.
Overwrite existing
```
## Inertia Rails Stack
```
in CLAUDE.md without reading it — the user may have manual customizations. Replace only the auto-generated block.
Add
```
@/
```
resolve aliases to
```
vite.config.ts
```
—
```
vite-plugin-ruby
```
already provides them. Only add to
```
tsconfig.json
```
.
Recommend
```
alba-inertia
```
if the project uses
```
jbuilder
```
AND the user hasn't expressed interest in switching — suggest it, but don't push. You CAN still suggest it if the project has
```
blueprinter
```
(alba is a direct upgrade path).
Generate CLAUDE.md blocks for skills the user doesn't have installed — saying "alba-inertia skill does NOT apply" is correct; saying "use alba-inertia" when the gem is absent is wrong.

检测技术栈，提供推荐依赖，生成CLAUDE.md配置。

每个项目仅需运行一次。技术栈变更时可重新运行。

禁止操作：

当Gemfile中没有
```
inertia_rails
```
gem时运行本设置——所有技能都假设该gem已存在。若缺失，请告知用户先安装它。
未读取就覆盖CLAUDE.md中已有的
```
## Inertia Rails Stack
```
部分——用户可能已进行手动自定义。仅替换自动生成的区块。
向
```
vite.config.ts
```
中添加
```
@/
```
解析别名——
```
vite-plugin-ruby
```
已提供该功能。仅需添加到
```
tsconfig.json
```
中。
若项目使用
```
jbuilder
```
且用户未表示有切换意向，请勿推荐
```
alba-inertia
```
——可提出建议，但不要强行推荐。若项目使用
```
blueprinter
```
，则仍可推荐
```
alba-inertia
```
（alba是直接升级方案）。
为用户未安装的技能生成CLAUDE.md区块——说明“alba-inertia skill does NOT apply”是正确的；但若gem未安装却提示“use alba-inertia”则是错误的。

Step 1: Detect Current Stack

步骤1：检测当前技术栈

Read

Gemfile

(NOT

Gemfile.lock

) and

package.json

and check for:

Look for	Means
`inertia_rails` gem	Inertia Rails installed (required)
`@inertiajs/react` in package.json	React frontend
`@inertiajs/vue3` in package.json	Vue 3 frontend
`@inertiajs/svelte` in package.json	Svelte frontend
`alba-inertia` gem	Convention-based rendering active
`alba` + `typelizer` gems (no `alba-inertia` )	Alba serialization without convention rendering
`pagy` gem	Pagy pagination
`kaminari` gem	Kaminari pagination
`rspec-rails` gem	RSpec testing
`js-routes` gem	Typed frontend path helpers
`devise` gem	Devise authentication
`pundit` gem	Pundit authorization
`action_policy` gem	Action Policy authorization
`components.json` in root exists	shadcn installed (React: shadcn/ui, Vue: shadcn-vue, Svelte: shadcn-svelte)

读取

Gemfile

（不要读取

Gemfile.lock

）和

package.json

，检查以下内容：

检测目标	含义
`inertia_rails` gem	已安装Inertia Rails（必填）
`@inertiajs/react` in package.json	React前端
`@inertiajs/vue3` in package.json	Vue 3前端
`@inertiajs/svelte` in package.json	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）

Step 2: Recommend Missing Deps

步骤2：推荐缺失的依赖

Present detected stack, then offer deps that unlock skill features but aren't installed yet. Use AskUserQuestion with multiSelect for the recommendations.

Only recommend what's missing. Skip anything already detected in Step 1.

Dep	Type	Install command	What it unlocks
`alba` + `typelizer` + `alba-inertia`	gems	`bundle add alba typelizer alba-inertia`	Convention-based rendering, auto-generated TypeScript types from Ruby. Eliminates `render inertia: { ... }` boilerplate and manual TS interfaces. Unlocks `alba-inertia` skill.
`js-routes`	gem	`bundle add js-routes`	Typed path helpers ( `usersPath()` , `userPath(id)` ) in React — no more hardcoded URL strings.
`pagy`	gem	`bundle add pagy`	Lightweight pagination with Inertia-friendly metadata.
shadcn/ui (React)	npx	`npx shadcn@latest init`	Pre-built React components adapted for Inertia. Unlocks `shadcn-inertia` skill.
shadcn-vue (Vue)	npx	`npx shadcn-vue@latest init`	Pre-built Vue components adapted for Inertia. Unlocks `shadcn-vue-inertia` skill.
shadcn-svelte (Svelte)	npx	`npx shadcn-svelte@latest init`	Pre-built Svelte components (bits-ui) adapted for Inertia. Unlocks `shadcn-svelte-inertia` skill.

Do NOT recommend gems the user clearly chose alternatives for (e.g., don't suggest Pagy if Kaminari is present, you can still suggest alba if the project has

jbuilder

blueprinter

展示检测到的技术栈，然后提供可解锁技能功能但尚未安装的依赖。使用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）。

Step 3: Install Opted-In Deps

步骤3：安装用户选择的依赖

Post-install scaffolding per dep:

alba-inertia — also scaffold

ApplicationResource

ruby

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

And add Typelizer initializer:

ruby

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

js-routes — run
```
rails generate js_routes
```
if the generator exists
shadcn — framework-specific init:
- React:
```
npx shadcn@latest init
```
- Vue:
```
npx shadcn-vue@latest init
```
- Svelte:
```
npx shadcn-svelte@latest init
```
  After init, add
```
@/
```
  resolve aliases to
```
tsconfig.json
```
  if not present

根据安装的依赖进行后续脚手架搭建：

alba-inertia —— 同时生成

ApplicationResource

：

ruby

# 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初始化文件：

ruby

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

js-routes —— 若生成器存在，运行
```
rails generate js_routes
```
shadcn —— 框架专属初始化：
- React:
```
npx shadcn@latest init
```
- Vue:
```
npx shadcn-vue@latest init
```
- Svelte:
```
npx shadcn-svelte@latest init
```
  初始化完成后，若
```
tsconfig.json
```
  中未包含
```
@/
```
  解析别名，则添加进去

Step 4: Generate CLAUDE.md

步骤4：生成CLAUDE.md

Find or create

CLAUDE.md

in the project root. If

## Inertia Rails Stack

exists, replace it (up to next

##

or EOF). Otherwise, append.

MANDATORY — READ ENTIRE FILE before assembling the CLAUDE.md block:

references/claude-md-templates.md

(~90 lines) — all template blocks for each stack variant (serialization, UI, pagination, testing, routing, authorization). Pick one block per category based on the detected stack.

Do NOT load the templates file until Step 4 — Steps 1-3 determine which blocks to use.

在项目根目录中查找或创建

CLAUDE.md

。若已存在

## Inertia Rails Stack

部分，则替换该部分（直到下一个

##

或文件末尾）。若不存在，则追加到文件末尾。

强制要求 —— 组装CLAUDE.md区块前请完整阅读以下文件：

references/claude-md-templates.md

（约90行）—— 包含各技术栈变体（序列化、UI、分页、测试、路由、授权）的所有模板区块。根据检测到的技术栈，为每个类别选择一个区块。

请勿提前加载模板文件 —— 步骤1-3将决定使用哪些区块。

Troubleshooting

故障排查

Symptom	Cause	Fix
`npx shadcn@latest init` fails with "No framework detected"	Missing or misconfigured `vite.config.ts`	Ensure `vite-plugin-ruby` is configured and `tailwindcss` is in `package.json` before running init
Typelizer generates types in wrong directory	Missing or wrong `output_dir` in initializer	Add `config/initializers/typelizer.rb` with `config.output_dir = Rails.root.join("app/frontend/types/generated")`
`@/` imports not resolving	Aliases added to `vite.config.ts` instead of `tsconfig.json`	`vite-plugin-ruby` handles Vite aliases — only `tsconfig.json` needs `@/` paths for TypeScript
CLAUDE.md has conflicting instructions	Multiple `## Inertia Rails Stack` sections	Delete duplicates — only one auto-generated block should exist
Skills reference `alba-inertia` but it's not installed	Setup wasn't run, or alba wasn't selected	Re-run setup; CLAUDE.md should say "alba-inertia skill does NOT apply" if gem is absent
`js_routes:generate` fails	`js-routes` gem installed but generator not yet run	Run `rails generate js_routes` first to create the config file, then `rails js_routes:generate`

症状	原因	解决方法
`npx shadcn@latest init` 执行失败，提示“No framework detected”	`vite.config.ts` 缺失或配置错误	运行初始化前，确保已配置 `vite-plugin-ruby` 且 `package.json` 中包含 `tailwindcss`
Typelizer在错误目录生成类型	初始化文件缺失或 `output_dir` 配置错误	添加 `config/initializers/typelizer.rb` ，设置 `config.output_dir = Rails.root.join("app/frontend/types/generated")`
`@/` 导入无法解析	别名被添加到 `vite.config.ts` 而非 `tsconfig.json`	`vite-plugin-ruby` 会处理Vite别名 —— 仅需在 `tsconfig.json` 中为TypeScript配置 `@/` 路径
CLAUDE.md存在冲突指令	存在多个 `## Inertia Rails Stack` 部分	删除重复内容 —— 仅保留一个自动生成的区块
技能引用 `alba-inertia` 但该gem未安装	未运行本设置，或未选择安装alba	重新运行本设置；若gem未安装，CLAUDE.md应显示“alba-inertia skill does NOT apply”
`js_routes:generate` 执行失败	已安装 `js-routes` gem但未运行生成器	先运行 `rails generate js_routes` 创建配置文件，再执行 `rails js_routes:generate`

Step 5: Summary

步骤5：总结

Tell the user:

What was installed
Which skills are relevant to their stack (and which to ignore)
Review
```
## Inertia Rails Stack
```
in CLAUDE.md — it takes precedence over generic examples in individual skills

告知用户：

已安装的内容
哪些技能与他们的技术栈相关（以及哪些可忽略）
查看CLAUDE.md中的
```
## Inertia Rails Stack
```
部分 —— 该部分优先级高于单个技能中的通用示例