inertia-rails

<essential_principles>

How Inertia Rails Works

Inertia is a bridge between Rails and modern JavaScript frameworks (React, Vue, Svelte). It lets you build SPAs using classic server-side routing and controllers—no client-side routing or separate APIs needed.

1. Server-Driven Architecture

Controllers render Inertia responses instead of views. Data flows from Rails to JavaScript components as props:

render inertia: 'Users/Show', props: { user: user.as_json }

2. No Client-Side Routing

Routes live in config/routes.rb. Inertia intercepts link clicks and form submissions, making XHR requests that return JSON with component name and props. The client swaps components without full page reloads.

3. Convention-Based Component Resolution

By default, render inertia: { user: } in UsersController#show renders app/frontend/pages/users/show.(jsx|vue|svelte). Override with explicit component names when needed.

4. Validation via Redirects

Unlike typical SPAs returning 422 JSON responses, Inertia follows traditional Rails patterns:

1. Controller validates and redirects back on failure
2. Errors are flashed and shared as props
3. Form state is preserved automatically

5. Shared Data Pattern

Use inertia_share in controllers to provide data to all pages (current_user, flash messages, notifications). Data is included in every response—use sparingly. </essential_principles>

1. Set up Inertia in a Rails project
2. Create a new page/component
3. Build a form with validation
4. Add shared data (auth, flash, etc.)
5. Handle redirects and navigation
6. Debug an Inertia issue
7. Test an Inertia controller
8. Optimize with partial reloads
9. Something else

Wait for response before proceeding.

After reading the workflow, follow it exactly.

<verification_loop>

After Every Change

1. Does the page render? Check Rails logs for Inertia response
2. Are props received? Console.log props in component
3. Does navigation work? Click links - should not full-reload
4. Do forms submit? Check Network tab for XHR requests
5. Are errors displayed? Test validation failures

# Rails debug - check response type
render inertia: 'Page', props: { debug: true }

// Frontend debug - log all props
console.log(usePage().props)

Report to the user:

• "Inertia response: ✓"
• "Props received: X keys"
• "Navigation: SPA mode ✓/✗"
• "Ready for testing" </verification_loop>

<reference_index>

Domain Knowledge

All in references/:

Core: setup.md, responses.md, forms.md, validation.md Data Flow: shared-data.md, links.md Quality: testing.md Cookbook: cookbook.md (shadcn/ui, Inertia Modal, meta tags, error types) </reference_index>

<workflows_index>

Workflows

All in workflows/:

File	Purpose
setup-inertia.md	Install and configure Inertia Rails
create-page.md	Build new pages with props
build-form.md	Forms with validation and useForm
shared-data.md	Share auth/flash across all pages
navigation.md	Links, redirects, router methods
debug-inertia.md	Find and fix Inertia issues
testing.md	Test Inertia controllers
partial-reloads.md	Optimize with selective data loading
</workflows_index>