🇺🇸English

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

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 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:

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:

Weekly Installs

77

Repository

inertia-rails/skills

GitHub Stars

35

First Seen

Feb 13, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

codex76

opencode76

gemini-cli75

github-copilot74

amp73

kimi-cli72