inertia-rails-controllers

Inertia Rails Controllers

Server-side patterns for Rails controllers serving Inertia responses.

Before adding a prop, ask:

• Needed on every page? → inertia_share in a base controller (InertiaController), not a per-action prop
• Expensive to compute? → InertiaRails.defer — page loads fast, data streams in after
• Only needed on partial reload? → InertiaRails.optional — skipped on initial load
• Reference data that rarely changes? → InertiaRails.once — cached across navigations

NEVER:

• Use redirect_to for external URLs (Stripe, OAuth, SSO) — it returns 302 but the Inertia client tries to parse the response as JSON, causing a broken redirect. Use inertia_location (returns 409 + X-Inertia-Location header).
• Use errors.full_messages for validation errors — it produces flat strings without field keys, so errors can't be mapped to the corresponding input fields on the frontend. Use errors.to_hash(true).
• Use inertia.defer, Inertia.defer, or inertia_rails.defer — the correct syntax is InertiaRails.defer { ... }. All prop helpers are module methods on the InertiaRails constant.
• Assume instance variables are auto-passed as props — they are NOT (unless alba-inertia gem is configured). Every action that passes props to the frontend MUST call render inertia: { key: data }.
• Use success/error as flash keys without updating config.flash_keys — Rails defaults to notice/alert. Custom keys must be added to both the initializer config and the FlashData TypeScript type.

Render Syntax