# Inertia Rails: props instead of an API, and where that trade bites

> The Rails adapter for Inertia.js lets a Rails controller hand props straight to a React, Vue or Svelte component, so a monolith can be a single-page application without a REST layer, a GraphQL schema or a client-side data fetching layer. The cost is a JavaScript build chain and a second way of doing forms.

**inertiajs/inertia-rails** — The Rails adapter for Inertia.js.

- Repository: https://github.com/inertiajs/inertia-rails
- Website: https://inertia-rails.dev/
- Stars: 1,247 · Forks: 104
- Language: Ruby
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/inertiajs-inertia-rails

## The whole loop is a controller and a component

Inertia sits between traditional server-rendered applications and full single-page applications, and the adapter makes that concrete in a way that is easy to grasp.

The pitch in the README is single-page React, Vue and Svelte applications powered by your existing Rails controllers, routes and authentication, with no API required. The mechanism is that a Rails action renders props instead of a template, and a frontend component receives them:

```ruby
# app/controllers/users_controller.rb
class UsersController < ApplicationController
  def index
    render inertia: {
      users: User.active.map { |user| user.as_json(only: [:id, :name, :email]) }
    }
  end
end
```

```jsx
// app/frontend/pages/users/index.jsx
import { Link } from '@inertiajs/react'

const Users = ({ users }) => (
  <>
    {users.map((user) => (
      <div key={user.id}>
        <Link href={`/users/${user.id}`}>{user.name}</Link>
        <p>{user.email}</p>
      </div>
    ))}
  </>
)

export default Users
```

The README describes it as the whole loop: the controller returns props, the component renders them. There are no REST endpoints, no GraphQL, no client-side data fetching and no state-management headaches, and the state that would live in a client-side cache lives in the Rails request cycle where it already did.

What makes it feel like a normal application is the navigation. Links and form submits are intercepted and turned into XHR visits, so navigation feels instant, and the server is still writing plain Rails. The URL bar still changes, the browser back button still works, and the server still decides what to render.

The gem is `inertia_rails` on RubyGems, the licence is MIT with the text in `LICENSE.txt`, the last push was on 2026-10-16, and the recent releases are v3.22.0 from 2026-07-17, v3.21.2 from 2026-06-09 and v3.21.1 from 2026-05-19.

## Installation is a gem and a generator

Adding Inertia to an existing Rails application is two commands:

```bash
bundle add inertia_rails
bin/rails generate inertia:install
```

The generator does the setup work. The README says the installer sets up Vite, the chosen framework and example pages, which is the part that decides how much of an afternoon this costs. Vite is the bundler, the framework is React, Vue or Svelte, and the example pages give you something running to compare against.

The alternative is to start from a starter kit instead of adding to an application you already have. The README describes the kits as having authentication, Vite, optional SSR and Kamal deployment already wired up. There are three of them, and they are the same stack as the Rails one with a different frontend.

The React kit is React 19 with TypeScript and shadcn/ui, the Vue kit is Vue 3 with TypeScript and shadcn-vue, and the Svelte kit is Svelte 5 with TypeScript and shadcn-svelte.

Two things are worth noticing about that list. The kits are versioned to current releases of the frameworks, so a kit is a snapshot of a moving target and will age. And Kamal is in the list, which says something about the deployment story: the application is a Rails application that also happens to serve a compiled frontend, and the deployment story is Rails deployment.

The full walkthrough is split into two guides, a server-side setup and a client-side setup, and the documentation site, `inertia-rails.dev`, carries everything else, from how it works through pages and layouts, forms and validation, shared data, partial reloads, deferred props, server-side rendering, testing and a configuration reference.

## The features that are shaped like Rails

Most of the Inertia feature list is really a list of things a Rails developer already expects, re-expressed in a single-page application.

Forms come first, because that is where the two models collide. Validation errors flow from Rails to your components automatically, with no manual wiring, which means the `errors` object a Rails form used to carry in a flash now arrives as props on the same request.

Shared data is the second. The current user, flash messages and permissions are available on every page automatically, which is the equivalent of a before-action that assigns to a view helper, and it removes the need for every component to fetch the session user.

Partial reloads refresh only the data you need, so an interaction does not have to be a full page load. Deferred props are the complementary idea, where the page loads fast and the expensive data is fetched afterwards, with built-in loading states for the part that has not arrived yet.

The Rails generators are the fourth, and they are a different kind of feature: they scaffold entire CRUD interfaces, controllers with matching components, which is the part of a framework that saves the most time in a project that is mostly administration screens.

History encryption is the fifth and the most interesting one for anyone with sensitive data. It keeps sensitive data private even in browser history, and it is toggleable per page, which means a page that carries a token in its props can opt out while a page that does not can leave the default alone.

And the DevTools feature inspects every request's props, headers and route in the browser's own DevTools in Chrome or Firefox, on by default in development. For a framework whose whole model is a request that returns props, seeing the props of the last request is the debugging tool that every other framework of this shape has had to build.

## SSR, testing and the pieces that are not just Rails in a hat

Three features need more than an adapter.

Server-side rendering is the first, and the description is that it gives full SSR for SEO and fast first paint, with your React, Vue or Svelte application rendered on Rails. That is a bigger commitment than it sounds, because rendering a frontend on the server means the server has to know how to build and run that frontend, and a mistake in the build now shows up as a server error rather than as a missing asset.

The testing support is the second. RSpec and Minitest matchers that feel native, and the README says you can assert on props, components and more. Asserting on props is the interesting part, because props are the contract between the Rails action and the component, and a test that asserts on them is testing the thing that the framework actually transports.

The third is the DevTools integration, already described: every request's props, headers and route, in the browser DevTools.

The repository itself is a normal Ruby gem project, which is worth a glance. There is `lib/` for the library code, `app/` for what the gem contributes to the host application, `spec/` and `test/` for the two test frameworks the matchers target, a `docs/` directory, a `Rakefile`, a `Gemfile` and `inertia_rails.gemspec`. The tooling is RuboCop with a `.rubocop.yml`, an `.rspec` file, and lefthook, which the README mentions as the git hooks that mirror the CI checks, with a `lefthook.yml` at the root. There is also a `.devcontainer/` directory, which tells you the project can be worked on in a container.

## Inertia against Hotwire, and Inertia against an API

The README has a section called Why Inertia, and it is really two comparisons, both of which are fair.

Against Hotwire, the difference is the view layer and nothing else. Both keep you in Rails, in the same monolith, with the same server-side code. Hotwire gives you HTML over the wire with minimal JavaScript and server-rendered HTML. Inertia gives you the full React, Vue or Svelte component model and the npm ecosystem. The recommendation in the README is to choose Hotwire for minimal JavaScript and server-rendered HTML, and Inertia for a modern component architecture, which is a question about what the frontend team wants to work with rather than about which is technically better.

Against an API and a separate SPA, the difference is the layer that disappears. Both give you the same frontend frameworks, but Inertia removes the API layer entirely: one router instead of two, Rails sessions instead of a JWT or OAuth dance, and props from the controller instead of fetching inside `useEffect`. The recommendation is to choose an API for public or mobile clients and Inertia for focused web products, with the note that you can always add an API alongside Inertia later.

That last note is the honest framing of the trade. Inertia is not an argument against having an API, it is an argument against making the API the only path between your frontend and your backend. A product with a web application and a mobile client will end up with both, and the question is which one the web application uses.

The comparison and the FAQ live on the documentation site under Why Inertia, and the community resources include an Awesome Inertia Rails list of gems, tutorials and real-world applications.

## Where Inertia is the wrong tool

The limits are mostly about what the team has to know and what the team has to run.

The first is the build chain. Inertia brings Vite, a JavaScript build and a node_modules directory into a Rails application. A team that has deliberately kept JavaScript out of its stack, or that has no frontend build expertise at all, is taking on a second toolchain, a second dependency tree and a second set of failure modes, in exchange for a component model. That is the trade Hotwire exists to avoid, and the README is clear that the choice is between the two.

The second is the client surface. Inertia is built for a browser application that the server controls. A mobile client, a public API for third parties, or an integration with another system will still need an API, and the README says so, recommending an API for public and mobile clients. A team whose product is mostly mobile is choosing the wrong side of this trade.

The third is the split between two ways of doing the same thing. A Rails application with Inertia has server-rendered views in the old style for some pages, component pages for others, and a form that can be a Rails form or an Inertia form. The README's feature list is a list of places where the two meet, and each of them, forms, shared data, partial reloads, deferred props, is a place where a developer has to know which model a given page uses.

The fourth is the release cadence and the size of the surface. The gem is on its 3.x line with releases every few weeks through the summer of 2026, and it depends on a client-side library that moves as fast as React does. The adapter is the stable part of the stack; the pieces it connects are not.

The alternative, on the same axes, is Hotwire for a server-rendered application that should not carry a build chain, or an API and a separate SPA for a product with clients the server does not control. Inertia is the best of the three when the answer is a browser application that a Rails team owns end to end, and the README's own comparison is a fair summary of when that is true.

## Conclusion

Inertia Rails fits a product team that wants a modern component frontend and a Rails backend, that has decided its clients are browsers it controls, and that would rather keep session authentication and the Rails router than build and maintain an API. It is the wrong choice for a product with public or mobile clients, where the README itself recommends an API, and it is the wrong choice for a team that has no appetite for Vite and a JavaScript build, because that is the price of the component model. Before adopting it, read the forms guide, since validation errors and the redirect-after-submit flow are where the two models meet, and decide where server-side rendering is actually needed, because SSR is an extra moving part rather than a free option.

## FAQ

### How do I add Inertia to an existing Rails application?

Run `bundle add inertia_rails` and then `bin/rails generate inertia:install`, which sets up Vite, the chosen framework and example pages. Alternatively, start from a starter kit for React, Vue or Svelte that already has authentication, Vite, optional SSR and Kamal deployment wired up.

### How does Inertia pass data from a Rails controller to a component?

The action calls `render inertia:` with a hash of props and the component receives them as props. There is no REST endpoint, no GraphQL and no client-side data fetching, while links and form submits are intercepted and turned into XHR visits so the Rails router still decides what is rendered.

### Does Inertia Rails support server-side rendering?

Yes. The documentation describes full server-side rendering for SEO and fast first paint, with the React, Vue or Svelte application rendered on Rails, and the setup is split into a server-side and a client-side guide.

### How does Inertia compare to Hotwire?

Both keep the application in Rails. Hotwire serves server-rendered HTML with minimal JavaScript, while Inertia gives the full React, Vue or Svelte component model and the npm ecosystem. The README recommends Hotwire for minimal JavaScript and Inertia for a modern component architecture.

## Sources

- [inertiajs/inertia-rails on GitHub](https://github.com/inertiajs/inertia-rails)
- [License: MIT](https://github.com/inertiajs/inertia-rails/blob/master/LICENSE)
- [Project website](https://inertia-rails.dev/)
- [README](https://github.com/inertiajs/inertia-rails/blob/master/README.md)
- [Releases](https://github.com/inertiajs/inertia-rails/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/inertiajs-inertia-rails