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

default_render: true TRAP: This setting only auto-infers the component name from controller/action — it does NOT auto-pass instance variables as props. Writing @posts = Post.all in an action with default_render: true renders the correct component but sends zero data to the frontend. Instance variables are only auto-serialized as props when alba-inertia gem is configured — check Gemfile before relying on this. Without it, you MUST use render inertia: { posts: data } to pass any data to the page.

Empty actions (def index; end) are correct ONLY for pages that need no data (e.g., a static dashboard page, a login form). If the action queries the database, it MUST call render inertia: with data.