inertia-rails-architecture
Master the server-driven mental model behind Inertia Rails: the server owns routing, data, and auth while React renders UI only. This skill routes you to the right pattern for pages, forms, navigation, and data refresh through a decision matrix covering data sources, state ownership, and common anti-patterns to avoid.
Inertia Rails Architecture teaches the server-driven mental model and decision matrix for building Inertia pages and features.
AI-generated summary based on this skill's SKILL.md
Install
inertia-rails/skills/inertia-rails-architecture
git clone https://github.com/inertia-rails/skills
cp -r skills/skills/inertia-rails-architecture ~/.claude/skills/inertia-rails-architecturenpx skillfed install inertia-rails/skills/inertia-rails-architectureFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
What is the core Inertia Rails architecture and server-driven mental model?
Inertia Rails follows a server-driven architecture where the Rails server owns routing, authentication, authorization, and data fetching. React components render the UI only. The server sends props to React via Inertia responses; React never directly fetches data or manages auth. This eliminates the need for a separate JSON API and keeps business logic server-side, making Inertia Rails simpler than traditional SPAs while remaining interactive.
How do inertia rails architecture patterns guide data loading, forms, navigation, and state?
Inertia Rails provides a decision matrix for these workflows: data loading happens server-side before rendering; forms post to Rails controllers which validate and re-render; navigation uses Inertia's Link component to preserve layout and fetch only changed props; state lives on the server (session, database) or in React for UI-only concerns. This matrix prevents common mistakes like useEffect+fetch and ensures consistent request handling across your app.
What are critical anti-patterns to avoid when building pages with inertia and react?
Inertia Rails discourages useEffect+fetch (breaks server-driven model), client-side auth checks (auth belongs on server), and mixing separate API calls with Inertia requests (use one path). Avoid storing sensitive data in React state and don't bypass the server for data fetching. Instead, let Rails handle all data loading and pass props down; use Inertia's Link for navigation and form submissions through controllers.
When should I use a separate API versus the Inertia request cycle in Rails?
Use the Inertia request cycle for page renders, form submissions, and navigation—the default path. Reserve a separate API for non-UI clients (mobile apps, third-party integrations) or real-time needs (WebSockets via ActionCable). For most Inertia Rails workflows, a separate API adds unnecessary complexity. If you need real-time updates, ActionCable integrates with Inertia; for CRUD operations, use Inertia's partial reloads and controller props.
How does inertia rails state management work for flash messages and persistent layouts?
Inertia Rails manages state through shared data (global props available to all pages), flash messages (stored in session, passed as props), and persistent layouts (React components that survive navigation). The server controls flash lifecycle; React receives it as a prop and can display it. Persistent layouts wrap pages and maintain state across route changes. This keeps state management simple and server-centric, avoiding Redux or Context API for most use cases.
What's the difference between Inertia Link component and anchor tags in Rails?
Inertia Rails Link component preserves the persistent layout and fetches only changed props, avoiding full page reloads. Anchor tags trigger full page reloads, losing layout state and re-rendering everything. Use Link for in-app navigation; use anchors only for external links. Link also handles partial reloads (refetch specific props) and respects the server-driven model by routing through Rails controllers rather than client-side routing.
SKILL.md
rendered from the published skill — quoted content, verbatim
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
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 3 files
skills/inertia-rails-architecture/SKILL.md
skills/inertia-rails-architecture/references/AGENTS.md
skills/inertia-rails-architecture/references/decision-trees.md