重要前提
安装AI Skills的关键前提是:必须科学上网,且开启TUN模式,这一点至关重要,直接决定安装能否顺利完成,在此郑重提醒三遍:科学上网,科学上网,科学上网。查看完整安装教程 →
inertia-rails-setup by inertia-rails/skills
npx skills add https://github.com/inertia-rails/skills --skill inertia-rails-setup检测技术栈,推荐依赖项,生成 CLAUDE.md 配置。
每个项目仅运行一次。 当技术栈变更时重新运行。
绝对禁止:
inertia_rails gem 的情况下运行设置 —— 所有技能都假定它存在。如果缺失,请告知用户先安装它。## Inertia Rails Stack —— 用户可能进行了手动自定义。仅替换自动生成的代码块。vite.config.ts 添加 @/ 解析别名 —— vite-plugin-ruby 已经提供了它们。只添加到 tsconfig.json。jbuilder 并且 用户没有表示出切换兴趣,则推荐 alba-inertia —— 可以建议,但不要强推。如果项目有 ,你建议它(alba 是一个直接的升级路径)。广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
blueprinter读取 Gemfile(不是 Gemfile.lock)和 package.json 并检查:
| 查找项 | 含义 |
|---|---|
inertia_rails gem | 已安装 Inertia Rails(必需) |
@inertiajs/react 在 package.json 中 | React 前端 |
@inertiajs/vue3 在 package.json 中 | Vue 3 前端 |
@inertiajs/svelte 在 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) |
展示检测到的技术栈,然后提供那些能解锁技能特性但尚未安装的依赖项。使用 AskUserQuestion 配合 multiSelect 进行推荐。
仅推荐缺失项。 跳过步骤 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 技能。 |
不要推荐用户已明确选择替代方案的 gems(例如,如果存在 Kaminari,则不要建议 Pagy;如果项目有 jbuilder 或 blueprinter,你仍然可以建议 alba)。
根据依赖项进行安装后脚手架搭建:
alba-inertia —— 同时搭建 ApplicationResource:
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
在项目根目录查找或创建 CLAUDE.md。如果存在 ## Inertia Rails Stack,则替换它(直到下一个 ## 或文件结尾)。否则,追加。
强制要求 —— 在组装 CLAUDE.md 代码块之前,完整读取整个文件:references/claude-md-templates.md(约 90 行)—— 包含每个技术栈变体(序列化、UI、分页、测试、路由、授权)的所有模板代码块。根据检测到的技术栈,每个类别选择一个代码块。
不要加载模板文件,直到步骤 4 —— 步骤 1-3 决定了使用哪些代码块。
| 症状 | 原因 | 修复方法 |
|---|---|---|
npx shadcn@latest init 失败并提示“未检测到框架” | 缺少或配置错误的 vite.config.ts | 在运行初始化之前,确保 vite-plugin-ruby 已配置且 tailwindcss 在 package.json 中 |
| 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 但未安装 | 未运行设置,或未选择 alba | 重新运行设置;如果 gem 缺失,CLAUDE.md 应说明“alba-inertia 技能不适用” |
js_routes:generate 失败 | js-routes gem 已安装但生成器尚未运行 | 首先运行 rails generate js_routes 创建配置文件,然后运行 rails js_routes:generate |
告知用户:
## Inertia Rails Stack —— 它优先于单个技能中的通用示例每周安装数
66
仓库
GitHub 星标数
35
首次出现
2026年2月13日
安全审计
安装于
opencode65
codex65
gemini-cli64
github-copilot63
amp62
kimi-cli61
Detect stack, offer recommended deps, generate CLAUDE.md configuration.
Run once per project. Re-run when the stack changes.
NEVER:
inertia_rails gem in Gemfile — all skills assume it exists. If missing, tell the user to install it first.## Inertia Rails Stack in CLAUDE.md without reading it — the user may have manual customizations. Replace only the auto-generated block.@/ resolve aliases to vite.config.ts — vite-plugin-ruby already provides them. Only add to tsconfig.json.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).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 + gems (no ) |
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 |
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 or blueprinter).
Post-install scaffolding per dep:
alba-inertia — also scaffold ApplicationResource:
class ApplicationResource
include Alba::Resource
helper Typelizer::DSL
helper Alba::Inertia::Resource
include Rails.application.routes.url_helpers
end
And add Typelizer initializer:
# config/initializers/typelizer.rb
Typelizer.configure do |config|
config.output_dir = Rails.root.join("app/frontend/types/generated")
end
2. js-routes — run rails generate js_routes if the generator exists
3. 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
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.
| 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 |
Tell the user:
## Inertia Rails Stack in CLAUDE.md — it takes precedence over generic examples in individual skillsWeekly Installs
66
Repository
GitHub Stars
35
First Seen
Feb 13, 2026
Security Audits
Gen Agent Trust HubFailSocketPassSnykPass
Installed on
opencode65
codex65
gemini-cli64
github-copilot63
amp62
kimi-cli61
GitHub Actions 官方文档查询助手 - 精准解答 CI/CD 工作流问题
47,200 周安装
typelizeralba-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) |
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. |
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 |