---
id: inertia-rails/skills/inertia-rails-controllers
version: "92a1bb97"
license: MIT
install: manual
updated: 2026-02-13
---

# inertia-rails-controllers — Master server-side Inertia patterns in Rails controllers. Learn when to use render inertia with explicit props, how to defer expensive queries, share data across pages, and handle validation errors correctly. Covers prop types, flash messages, and the critical inertia_location rule for external redirects.

Publisher: inertia-rails · Stars: 64 · Updated: 2026-02-13

Install (manual): `git clone https://github.com/inertia-rails/skills`

## SKILL.md

# 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.

| Situation | Syntax | Component path |
|-----------|--------|----------------|
| Action loads data | `render inertia: { users: data }` | Inferred from controller/action |
| Action loads NO data (static page) | Empty action or `render inertia: {}` | Inferred from controller/action |
| Rendering a different page | `render inertia: 'errors/show', props: { error: e }` | Explicit path |

**Rule of thumb:** If your action touches the database, it MUST call `render inertia:` with data.
If the action body is empty, the page receives only shared props (from `inertia_share`).

```ruby
# CORRECT — data passed as props
def index
  render inertia: { users: users_data, stats: InertiaRails.defer { ExpensiveQuery.run } }
end

# CORRECT — static page, no data needed
def index; end

# WRONG — @posts is NEVER sent to the frontend (without alba-inertia)
def index
  @posts = Post.all
end
```

> **Note:** If the project uses the `alba-inertia` gem (check `Gemfile`), instance
> variables are auto-serialized as props and explicit `render inertia:` is not needed.
> See the `alba-inertia` skill for that convention.

## Prop Types

**`InertiaRails.defer`** — NOT `inertia.defer`, NOT `Inertia.defer`. All prop helpers are module methods on `InertiaRails`.

| Type | Syntax | Behavior |
|------|--------|----------|
| Regular | `{ key: value }` | Always evaluated, always included |
| Lazy | `-> { expensive_value }` | Included on initial page render, lazily evaluated on partial reloads |
| Optional | `InertiaRails.optional { ... }` | Only evaluated on partial reload requesting it |
| Defer | `InertiaRails.defer { ... }` | Loaded after initial page render |
| Defer (grouped) | `InertiaRails.defer(group: 'name') { ... }` | Grouped deferred — fetched in parallel |
| Once | `InertiaRails.once { ... }` | Resolved once, remembered across navigations |
| Merge | `InertiaRails.merge { ... }` | Appended to existing array (infinite scroll) |
| Deep merge | `InertiaRails.deep_merge { ... }` | Deep merged into existing object |
| Always | `InertiaRails.always { ... }` | Included even in partial reloads |
| Scroll | `InertiaRails.scroll { ... }` | Scroll-aware prop for infinite scroll |

```ruby
def index
  render inertia: {
    filters: filter_params,
    messages: -> { messages_scope.as_json },
    stats: InertiaRails.defer { Dashboard.stats },
    chart: InertiaRails.defer(group: 'analytics') { Dashboard.chart },
    countries: InertiaRails.once { Country.pluck(:name, :code) },
    posts: InertiaRails.merge { @posts.as_json },
    csrf: InertiaRails.always { form_authenticity_token },
  }
end
```

### Deferred Props — Full Stack Example

Server defers slow data, client shows fallback then swaps in content:

```ruby
# Controller
def show
  render inertia: {
    basic_stats: Stats.quick_summary,
    analytics: InertiaRails.defer { Analytics.compute_slow },
  }
end
```

```tsx
// Page component — child reads deferred prop from page props
import { Deferred, usePage } from '@inertiajs/react'

export default function Dashboard({ basic_stats }: Props) {
  return (
    <>
      <QuickStats data={basic_stats} />
      <Deferred data="analytics" fallback={<div>Loading analytics...</div>}>
        <AnalyticsPanel />
      </Deferred>
    </>
  )
}

function AnalyticsPanel() {
  const { analytics } = usePage<{ analytics: Analytics }>().props
  return <div>{analytics.revenue}</div>
}
```

## Shared Data

Use `inertia_share` in controllers — it needs controller context (`current_user`,
request). The initializer only handles `config.*` settings (version, flash_keys).

```ruby
class ApplicationController < ActionController::Base
  # Static
  inertia_share app_name: 'MyApp'

  # Using lambdas (most common)
  inertia_share auth: -> { { user: current_user&.as_json(only: [:id, :name, :email, :role]) } }

  # Conditional
  inertia_share if: :user_signed_in? do
    { notifications: -> { current_user.unread_notifications_count } }
  end
end
```

Lambda and action-scoped variants are in [`references/configuration.md`](references/configuration.md).

**Evaluation order:** Multiple `inertia_share` calls merge top-down. If a child
controller shares the same key as a parent, the child's value wins. Block and lambda
shares are lazily evaluated per-request — they don't run for non-Inertia requests.

## Flash Messages

Flash is automatic. Configure exposed keys if needed:

```ruby
# config/initializers/inertia_rails.rb
InertiaRails.configure do |config|
  config.flash_keys = %i[notice alert toast] # default: %i[notice alert]
end
```

Use standard Rails flash in controllers:
```ruby
redirect_to users_path, notice: "User created!"
# or
flash.alert = "Something went wrong"
redirect_to users_path
```

## Redirects & Validation Errors

After create/update/delete, always redirect (Post-Redirect-Get). Standard Rails
`redirect_to` works. The Inertia-specific part is validation error handling:

```ruby
def create
  @user = User.new(user_params)
  if @user.save
    redirect_to users_path, notice: "Created!"
  else
    redirect_back_or_to new_user_path, inertia: { errors: @user.errors.to_hash(true) }
  end
end
```

**`to_hash` vs `to_hash(true)`:** `to_hash` gives `{ name: ["can't be blank"] }`,
`to_hash(true)` gives `{ name: ["Name can't be blank"] }`. Keys must match input
`name` attributes — mismatched keys mean errors won't display next to the right field.

**NEVER use `errors.full_messages`** — it produces flat strings without field keys,
so errors can't be mapped to the corresponding input fields on the frontend.

## Authorization as Props

Pass permissions as per-resource `can` hash — frontend controls visibility,
server enforces access. See `inertia-rails-controllers` + `inertia-rails-pages` skills.

**MANDATORY — READ ENTIRE FILE** when implementing authorization props:
[`references/authorization.md`](references/authorization.md) (~40 lines) — full-stack
`can` pattern with Action Policy/Pundit/CanCanCan examples.

**Do NOT load** if not passing permission data to the frontend.

## External Redirects (`inertia_location`)

**CRITICAL:** `redirect_to` for external URLs breaks Inertia — the client
receives a 302 but tries to handle it as an Inertia response (JSON), not a
full page redirect. `inertia_location` returns 409 with `X-Inertia-Location`
header, which tells the client to do `window.location = url`.

```ruby
# Stripe checkout — MUST use inertia_location, not redirect_to
def create
  checkout_session = Current.user.payment_processor.checkout(
    mode: "payment",
    line_items: "price_xxx",
    success_url: enrollments_url,
    cancel_url: course_url(@course),
  )
  inertia_location checkout_session.url
end
```

Use `inertia_location` for any URL outside the Inertia app: payment
providers, OAuth, external services.

## History Encryption

Encrypts page data in browser history state — `config.encrypt_history = Rails.env.production?`.
Use `redirect_to path, inertia: { clear_history: true }` on logout/role change.
Full setup with server-side and client-side examples is in
[`references/configuration.md`](references/configuration.md).

## Configuration

See [`references/configuration.md`](references/configuration.md) for all
`InertiaRails.configure` options (version, encrypt_history, flash_keys, etc.).

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| 302 loop on Stripe/OAuth redirect | `redirect_to` for external URL | Use `inertia_location` — it returns 409 + `X-Inertia-Location` header |
| Errors don't display next to fields | Error keys don't match input `name` | `to_hash` keys must match input `name` attributes exactly |
| TS2305: `postsPath` not found in `@/routes` | js-routes not regenerated after adding routes | Run `rails js_routes:generate` after changing `config/routes.rb` |

## Related Skills
- **Form error display** → `inertia-rails-forms`
- **Flash toast UI** → `inertia-rails-pages` (access) + `shadcn-inertia` (Sonner)
- **Deferred on client** → `inertia-rails-pages` (`<Deferred>` component)
- **Type-safe props** → `inertia-rails-typescript` or `alba-inertia` (serializers)
- **Testing** → `inertia-rails-testing`

## References

**MANDATORY — READ ENTIRE FILE** when using advanced prop types (`merge`,
`scroll`, `deep_merge`) or combining multiple prop options:
[`references/prop-types.md`](references/prop-types.md) (~180 lines) — detailed behavior,
edge cases, and combination rules for all prop types.

**Do NOT load** `prop-types.md` for basic `defer`, `optional`, `once`, or `always`
usage — the table above is sufficient.

Load [`references/configuration.md`](references/configuration.md) (~180 lines) only when
setting up `InertiaRails.configure` for the first time or debugging configuration
issues. **Do NOT load** for routine controller work.


[View on SkillFed](https://skillfed.io/inertia-rails/skills/inertia-rails-controllers) · [View on GitHub](https://github.com/inertia-rails/skills)