inertia-rails-architecture
Server-driven architecture patterns for Inertia Rails + React. Load this FIRST when building any Inertia page or feature — it routes to the right skill. Decision matrix for data loading, forms, navigation, state management. NEVER useEffect+fetch, NEVER redirectto for external URLs (use inertialocation), NEVER react-hook-form (use Form component). MUST invoke when adding pages, models with views, CRUD, or displaying data in an Inertia Rails app. ALWAYS render inertia: { key: value } to pass data — @ivars are NOT auto-passed as props.
- Installs
- 538
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/inertia-rails/skills --skill inertia-rails-architecture- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads inertia-rails-architecture automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Inertia Rails Architecture
Server-driven architecture for Rails + Inertia.js + React when building pages, forms, navigation, or data refresh. Inertia is NOT a traditional SPA — the server owns routing, data, and auth. React handles rendering only.
The Core Mental Model
The server is the source of truth. React receives data as props and renders UI. There is no client-side router, no global state store, no API layer.
Before building any feature, ask:
- Where does the data come from? → If server: controller prop. If user interaction:
useState. - Who owns this state? → If it's in the URL or DB: server owns it (use props). If it's ephemeral UI: React owns it.
- Am I reaching for a React/SPA pattern? → Check the decision matrix below first — Inertia likely has a server-driven equivalent.
Decision Matrix
| Need | Solution | NOT This |
|---|---|---|
| Page data from server | Controller props | useEffect + fetch |
| Global data (auth, config) | inertia_share + usePage() | React Context / Redux |
| Flash messages / toasts | Rails flash + usePage().flash | inertia_share / React state |
| Form submission | <Form> component | fetch/axios + useState |
| Navigate between pages | <Link> / router.visit | react-router / window.location |
| Refresh specific data | router.reload({ only: [...] }) | React Query / SWR |
| Expensive server data | InertiaRails.defer | useEffect + loading state |
| Infinite scroll | InertiaRails.scroll + <InfiniteScroll> | Client-side pagination |
| Stable reference data | InertiaRails.once | Cache in React state |
| Real-time updates (core) | ActionCable + router.reload | Polling with setInterval |
| Simple polling (MVP/prototyping) | usePoll (auto-throttles in background tabs) | setInterval + router.reload |
| URL-driven UI state (dialogs, tabs) | Controller reads params → prop, router.get to update | useEffect + window.location |
| Ephemeral UI state | useState / useReducer | Server props |
| External API calls | Dedicated API endpoint | Mixing with Inertia props |
Rules (by impact)
| # | Impact | Rule | WHY |
|---|---|---|---|
| 1 | CRITICAL | Never useEffect+fetch for page data | Inertia re-renders the full component on navigation; a useEffect fetch creates a second data lifecycle that drifts from props and causes stale UI |
| 2 | CRITICAL | Never check auth client-side | Auth state in React can be spoofed; server-side checks are the only real gate. Client-side "guards" give false security |
| 3 | CRITICAL | Use <Form>, not fetch/axios | <Form> handles CSRF, redirect-following, error mapping, file detection, and history state — fetch duplicates or breaks all of this |
| 4 | HIGH | Use <Link> and router, not <a> or window.location | <a> triggers a full page reload, destroying all React state and layout persistence |
| 5 | HIGH | Use partial reloads, not React Query/SWR | React Query adds a second cache layer that conflicts with Inertia's page-based caching and versioning |
| 5b | HIGH | Use usePoll only for MVPs; prefer ActionCable for production real-time | usePoll is convenient but wastes bandwidth — every interval hits the server even when nothing changed. ActionCable pushes only on actual changes |
| 6 | HIGH | Use inertia_share for global data, not React Context | Context re-renders consumers on every change; shared props are per-request and integrated with partial reloads |
| 7 | HIGH | Use Rails flash for notifications, not shared props | Flash auto-clears after one response; shared props persist until explicitly changed, causing stale toasts |
| 8 | MEDIUM | Use deferred/optional props for expensive queries | Blocks initial render otherwise — user sees blank page until slow query finishes |
| 9 | MEDIUM | Use persistent layouts for state preservation | Without persistent layout, layout remounts on every navigation — scroll position, audio playback, and component state are lost |
| 10 | MEDIUM | Keep React components as renderers, not data fetchers | Mixing data-fetching into components makes them untestable and breaks Inertia's server-driven model |
Skill Map
Common workflows span multiple skills — load all listed for complete coverage:
| Workflow | Load these skills |
|---|---|
| New page with props | inertia-rails-controllers + inertia-rails-pages + inertia-rails-typescript |
| Form with validation | inertia-rails-forms + inertia-rails-controllers |
| shadcn form inputs | inertia-rails-forms + shadcn-inertia |
| Flash toasts | inertia-rails-controllers + inertia-rails-pages + shadcn-inertia |
| Deferred/lazy data | inertia-rails-controllers + inertia-rails-pages |
| URL-driven dialog/tabs | inertia-rails-controllers + inertia-rails-pages |
| Alba serialization | alba-inertia + inertia-rails-typescript |
| Testing controllers | inertia-rails-testing + inertia-rails-controllers |
References
MANDATORY — READ ENTIRE FILE before building a new Inertia page or feature:
references/AGENTS.md (~430 lines) — full-stack examples for
each pattern in the decision matrix above.
MANDATORY — READ ENTIRE FILE when unsure which Inertia pattern to use:
references/decision-trees.md (~70 lines) — flowcharts
for choosing between prop types, navigation methods, and data strategies.
Do NOT load references for quick questions about a single pattern already covered in the decision matrix above.
When You DO Need a Separate API
Not everything belongs in Inertia's request cycle. Use a traditional API endpoint when:
| Signal | Why | Example |
|---|---|---|
| Non-browser consumer | Inertia's JSON envelope (component, props, url, version) is designed for the frontend adapter — other consumers can't use it | Mobile API, CLI tools, payment webhooks |
| Large-dataset search | Dataset is too big to load as a prop; each input needs per-keystroke server filtering. Use raw fetch for the search, let Inertia handle post-selection side effects via props. | City/address autocomplete, postal code lookup |
| Binary/streaming response | Inertia can only deliver JSON props. Use a separate route with a standard download response. | PDF/CSV export, file downloads |
FAQ
What does the inertia-rails-architecture skill do?
Server-driven architecture patterns for Inertia Rails + React. Load this FIRST when building any Inertia page or feature — it routes to the right skill. Decision matrix for data loading, forms, navigation, state management. NEVER useEffect+fetch, NEVER redirectto for external URLs (use inertialocation), NEVER react-hook-form (use Form component). MUST invoke when adding pages, models with views, CRUD, or displaying data in an Inertia Rails app. ALWAYS render inertia: { key: value } to pass data — @ivars are NOT auto-passed as props.
How do I install inertia-rails-architecture?
Run npx skills add https://github.com/inertia-rails/skills --skill inertia-rails-architecture in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/inertia-rails-architecture/ (personal) or .claude/skills/inertia-rails-architecture/ (project).
Which AI agents can use inertia-rails-architecture?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is inertia-rails-architecture safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains inertia-rails-architecture?
It is published by inertia-rails in inertia-rails/skills. It has 538 recorded installs.
More from inertia-rails/skills
inertia-rails-pages
inertia-rails/skills
Page components, persistent layouts, Link/router navigation, Head, Deferred, WhenVisible, InfiniteScroll, and URL-driven state for Inertia Rails. React examples inline; Vue and Svelte equivalents in references. Use when building pages, adding navigation, implementing persistent layouts, infinite scroll, lazy-loaded sections, or working with client-side Inertia APIs (router.reload, router.replaceProp, prefetching).
inertia-rails-controllers
inertia-rails/skills
ALWAYS render inertia: { key: data } to pass data as props — instance variables are NOT auto-passed (only alba-inertia does that). Rails controller patterns for Inertia.js: render inertia, prop types (defer, optional, merge, scroll), shared data, flash, PRG redirects, validation errors. Use when writing controllers that load data, display records, or serve Inertia responses. CRITICAL: external URLs (Stripe/OAuth) MUST use inertialocation, NEVER redirectto.
inertia-rails-forms
inertia-rails/skills
Full-stack form handling for Inertia Rails: create, edit, delete, multi-step wizard, and file upload forms with validation errors and progress tracking. React examples inline; Vue and Svelte equivalents in references. Use when building any form, handling file uploads, multi-step forms, client-side validation, or wiring form submission to Rails controllers. NEVER react-hook-form. Use for simple forms, useForm for dynamic/programmatic control.
inertia-rails-typescript
inertia-rails/skills
Open the skill to read its SKILL.md instructions.
inertia-rails-testing
inertia-rails/skills
Open the skill to read its SKILL.md instructions.
shadcn-inertia
inertia-rails/skills
Open the skill to read its SKILL.md instructions.
Popular backend & apis skills
find-skills
vercel-labs/skills
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
entra-app-registration
microsoft/azure-skills
Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.
google-agents-cli-adk-code
google/agents-cli
This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).
embedded-captions
heygen-com/hyperframes
Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.
entra-agent-id
microsoft/azure-skills
Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).
neon
neondatabase/agent-skills
Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.