inertia-rails-setup

Inertia Rails 项目设置

检测技术栈、推荐依赖项并生成 CLAUDE.md 配置。

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

绝不要：

• 在 Gemfile 中没有 inertia_rails gem 时运行设置——所有技能都假定它已存在。如果缺少，请告知用户先安装。
• 未读取 CLAUDE.md 中现有的 ## Inertia Rails Stack 就覆盖它——用户可能添加了手动自定义内容。仅替换自动生成的区块。
• 在 vite.config.ts 中添加 @/ 解析别名——vite-plugin-ruby 已提供这些别名。仅添加到 tsconfig.json。
• 如果项目使用 jbuilder 且用户没有表达切换意愿，就推荐 alba-inertia——可以提议，但不要强推。如果项目使用 blueprinter，仍然可以推荐它（alba 是直接的升级路径）。
• 为用户未安装的技能生成 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 步：推荐缺少的依赖项

先展示检测到的技术栈，再推荐尚未安装、但能启用技能功能的依赖项。使用带有 multiSelect 的 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、分页、测试、路由、 授权）。根据检测到的技术栈，为每个类别选择一个区块。

在步骤 4 之前，不要加载模板文件——步骤 1-3 会确定要使用哪些区块。

故障排除

症状	原因	修复方法
npx shadcn@latest init 失败，并显示 "No framework detected"	缺少或配置错误的 vite.config.ts	确保已配置 vite-plugin-ruby，并且在运行 init 之前，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 别名——TypeScript 只需要在 tsconfig.json 中配置 @/ 路径
CLAUDE.md 中的说明相互冲突	存在多个 ## Inertia Rails Stack 区块	删除重复区块——只应有一个自动生成的区块
Skills 引用了 alba-inertia，但它未安装	尚未运行设置，或未选择 alba	重新运行设置；如果缺少 gem，CLAUDE.md 应注明“alba-inertia skill 不适用”
js_routes:generate 失败	已安装 js-routes gem，但尚未运行生成器	先运行 rails generate js_routes 创建配置文件，然后运行 rails js_routes:generate

步骤 5：总结

告知用户：

1. 安装了什么
2. 哪些 Skills 与其技术栈相关（以及哪些应忽略）
3. 查看 CLAUDE.md 中的 ## Inertia Rails Stack——其优先级高于各个 Skill 中的通用示例