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 |
1---2name: inertia-rails-architecture3description: 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 redirect_to for external URLs (use inertia_location), 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.4---5
6# Inertia Rails Architecture
7
8Server-driven architecture for Rails + Inertia.js + React when building pages,
9forms, navigation, or data refresh. Inertia is NOT a traditional SPA — the
10server owns routing, data, and auth. React handles rendering only.
11
12## The Core Mental Model
13
14The server is the source of truth. React receives data as props and renders UI.
15There is no client-side router, no global state store, no API layer.
16
17**Before building any feature, ask:**
18- **Where does the data come from?** → If server: controller prop. If user interaction: `useState`.
19- **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.
20- **Am I reaching for a React/SPA pattern?** → Check the decision matrix below first — Inertia likely has a server-driven equivalent.
21
22## Decision Matrix
23
24| Need | Solution | NOT This |
25|------|----------|----------|
26| Page data from server | Controller props | useEffect + fetch |
27| Global data (auth, config) | `inertia_share` + `usePage()` | React Context / Redux |
28| Flash messages / toasts | Rails `flash` + `usePage().flash` | inertia_share / React state |
29| Form submission | `<Form>` component | fetch/axios + useState |
30| Navigate between pages | `<Link>` / `router.visit` | react-router / window.location |
31| Refresh specific data | `router.reload({ only: [...] })` | React Query / SWR |
32| Expensive server data | `InertiaRails.defer` | useEffect + loading state |
33| Infinite scroll | `InertiaRails.scroll` + `<InfiniteScroll>` | Client-side pagination |
34| Stable reference data | `InertiaRails.once` | Cache in React state |
35| Real-time updates (core) | ActionCable + `router.reload` | Polling with setInterval |
36| Simple polling (MVP/prototyping) | `usePoll` (auto-throttles in background tabs) | setInterval + router.reload |
37| URL-driven UI state (dialogs, tabs) | Controller reads `params` → prop, `router.get` to update | useEffect + window.location |
38| Ephemeral UI state | `useState` / `useReducer` | Server props |
39| External API calls | Dedicated API endpoint | Mixing with Inertia props |
40
41## Rules (by impact)
42
43| # | Impact | Rule | WHY |
44|---|--------|------|-----|
45| 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 |
46| 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 |
47| 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 |
48| 4 | HIGH | Use `<Link>` and `router`, not `<a>` or window.location | `<a>` triggers a full page reload, destroying all React state and layout persistence |
49| 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 |
50| 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 |
51| 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 |
52| 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 |
53| 8 | MEDIUM | Use deferred/optional props for expensive queries | Blocks initial render otherwise — user sees blank page until slow query finishes |
54| 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 |
55| 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 |
56
57## Skill Map
58
59Common workflows span multiple skills — load all listed for complete coverage:
60
61| Workflow | Load these skills |
62|----------|-------------------|
63| New page with props | `inertia-rails-controllers` + `inertia-rails-pages` + `inertia-rails-typescript` |
64| Form with validation | `inertia-rails-forms` + `inertia-rails-controllers` |
65| shadcn form inputs | `inertia-rails-forms` + `shadcn-inertia` |
66| Flash toasts | `inertia-rails-controllers` + `inertia-rails-pages` + `shadcn-inertia` |
67| Deferred/lazy data | `inertia-rails-controllers` + `inertia-rails-pages` |
68| URL-driven dialog/tabs | `inertia-rails-controllers` + `inertia-rails-pages` |
69| Alba serialization | `alba-inertia` + `inertia-rails-typescript` |
70| Testing controllers | `inertia-rails-testing` + `inertia-rails-controllers` |
71
72## References
73
74**MANDATORY — READ ENTIRE FILE** before building a new Inertia page or feature:
75[`references/AGENTS.md`](references/AGENTS.md) (~430 lines) — full-stack examples for
76each pattern in the decision matrix above.
77
78**MANDATORY — READ ENTIRE FILE** when unsure which Inertia pattern to use:
79[`references/decision-trees.md`](references/decision-trees.md) (~70 lines) — flowcharts
80for choosing between prop types, navigation methods, and data strategies.
81
82**Do NOT load** references for quick questions about a single pattern already
83covered in the decision matrix above.
84
85## When You DO Need a Separate API
86
87Not everything belongs in Inertia's request cycle. Use a traditional API endpoint when:
88
89| Signal | Why | Example |
90|--------|-----|---------|
91| 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 |
92| 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 |
93| Binary/streaming response | Inertia can only deliver JSON props. Use a separate route with a standard download response. | PDF/CSV export, file downloads |
inertia-rails