How inertiajs/inertia-rails works
1. What this repository is
- This is a Ruby gem for Rails that implements the server side of Inertia.js for Rails apps.
- It bridges Rails controllers/routes/sessions with React, Vue, or Svelte components, so the app behaves like an SPA without a separate API layer.
2. Primary architectural boundary
- The core boundary is between:
- Rails request handling on the server
- Inertia component rendering on the client
- The browser never talks to a standalone API; instead, Rails returns Inertia responses containing page/component names and props.
3. Core runtime flow
- A Rails controller calls the Inertia render path.
- The library converts controller data into Inertia props, applies prop rules, and returns either:
- a normal Rails HTML response for the initial request, or
- a JSON Inertia response for XHR/SPA navigation.
- The client-side Inertia adapter then swaps pages without full reloads.
4. Main server-side subsystems in lib/inertia_rails
- controller.rb, helper.rb, renderer.rb: the main integration surface for Rails controllers and views.
- props_resolver.rb plus the prop classes (lazy, defer, merge, once, cached, optional, scroll, etc.): manage how page data is evaluated and transmitted.
- configuration.rb, current.rb, errors.rb, testing.rb: framework integration, request context, and test helpers.
- middleware.rb, flash_extension.rb, extensions/*: hooks into Rails request/response behavior, flash, debugging, and error handling.
5. Prop model is a major design concept
- Props are not just hashes; they can carry behavior:
- deferred/lazy values for delayed loading
- cached/once/merge semantics for partial reloads and state preservation
- scroll metadata and other transport-related metadata
- This makes prop resolution a distinct layer in the architecture, not just controller serialization.
6. Server-side rendering path
- SSR is supported through ssr.rb and ssr_renderer.rb.
- The repo also includes a Puma plugin in lib/puma/plugin/inertia_ssr.rb, showing SSR can run as a server-side process attached to the app runtime.
- SSR is an optional boundary: initial page HTML can be rendered on the server for faster first paint/SEO, then the client takes over.
7. Rails engine and view integration
- lib/inertia_rails/engine.rb packages the gem as a Rails engine.
- app/views/inertia.html.erb and app/controllers/inertia_rails/static_controller.rb provide the minimal Rails-facing entry points used by the engine and initial app bootstrapping.
8. Generators are a second major subsystem
- The lib/generators and lib/generators/inertia_templates trees generate:
- controllers
- scaffolded CRUD pages
- starter frontend files for React, Vue, and Svelte
- optional Tailwind and TypeScript setup
- There are parallel template sets for “standard” and “tailwind” variants, so installation is customizable by frontend stack.
9. Project setup and developer experience
- bin/ scripts and Rakefile support gem tasks, versioning, setup, and publishing.
- .devcontainer and .github/workflows/* indicate the project is built and validated with containerized dev environments, CI, docs deployment, release automation, and gem publishing.
10. Documentation is a separate frontend app
- docs/ is a VitePress site, with a custom theme and markdown plugins.
- It has its own Node toolchain and build pipeline, separate from the Ruby gem runtime.
- Architecture-wise, docs are not part of the gem execution path, but they are a key companion system for distribution and onboarding.
11. Testing architecture
- spec/ is the main test suite, with a full dummy Rails app under spec/dummy for end-to-end behavior.
- There are focused specs for props, rendering, middleware, SSR, request/response behavior, generators, and framework adapters.
- test/ contains integration coverage as well, so the repo validates both library internals and Rails integration behavior.
12. Important external dependencies and ecosystems
- The library sits inside the Rails ecosystem and depends on Rails conventions heavily.
- It interoperates with frontend ecosystems through Inertia adapters for React/Vue/Svelte.
- Optional SSR and docs introduce Node-based tooling, but the production runtime center remains the Ruby/Rails app.
13. How to think about the diagram
- Draw the gem as a Rails middleware/engine + controller rendering layer in the center.
- On one side: Rails app, routes, controllers, flash/session, testing dummy app.
- On the other side: Inertia client adapters and component frameworks.
- Above/below that path: SSR process and generator/templates/docs tooling as supporting subsystems.
Main entry points: engine.rb Engine · renderer_spec.rb Specs · controller.rb Controller · props_resolver.rb Props resolver
Components 22
Rails integration
Server-side Rails engine, controller surface, view entrypoints, and runtime hooks.
- Engine · Gem entrypoint that mounts the library into Rails.
lib/inertia_rails/engine.rb - Controller · Controller API for rendering Inertia responses and sharing state.
lib/inertia_rails/controller.rb - Helper · View-side helper methods for Inertia integration.
lib/inertia_rails/helper.rb - Renderer · Converts controller intent into HTML or JSON Inertia responses.
lib/inertia_rails/renderer.rb - Config · Framework configuration and app-level settings.
lib/inertia_rails/configuration.rb - Current · Per-request state and shared current values.
lib/inertia_rails/current.rb - Middleware · Request/response integration around Rails and Inertia behavior.
lib/inertia_rails/middleware.rb - Extensions · Adapters for request mapping, debugging, and error-handling integrations.
lib/inertia_rails/extensions/request.rb - Flash · Bridges Rails flash data into Inertia behavior.
lib/inertia_rails/flash_extension.rb
Prop system
Behavioral prop types and resolution rules that shape Inertia payloads.
- Props resolver · Resolves, transforms, and serializes page props.
lib/inertia_rails/props_resolver.rb - Prop types · Lazy, deferred, cached, once, merge, optional, and scroll semantics.
lib/inertia_rails/lazy_prop.rb
SSR
Server-side rendering path and its Puma entrypoint.
- SSR core · SSR request handling and orchestration.
lib/inertia_rails/ssr.rb - SSR renderer · Executes server-side rendering for page components.
lib/inertia_rails/ssr_renderer.rb - Puma plugin · Attaches SSR behavior to a Puma runtime.
lib/puma/plugin/inertia_ssr.rb
Generators
Rails generators and templates for app installation and scaffolding.
- Install generator · Installs the gem into a host app and chooses frontend stack templates.
lib/generators/inertia/install/install_generator.rb - Scaffold generator · Generates CRUD pages and controller scaffolding for Inertia apps.
lib/generators/inertia/scaffold/scaffold_generator.rb - Templates · Frontend-specific controller and page templates for React, Vue, and Svelte.
lib/generators/inertia_templates/controller/controller_generator.rb
Docs site
VitePress documentation and custom theme.
- Docs app · Standalone documentation frontend and content pipeline.
docs/.vitepress/config.mts
Testing
Dummy Rails app and automated coverage for library behavior.
- Dummy app · Full Rails host used to validate integration behavior end to end.
spec/dummy/config/application.rb - Specs · Focused coverage for props, rendering, middleware, SSR, generators, and adapters.
spec/inertia/renderer_spec.rb - Integration tests · Additional integration coverage in the test/ tree.
test/integration/inertia_test.rb
Tooling
Repo scripts, packaging, CI, and release automation.
- Rake tasks · Task entrypoints for versioning, setup, and gem publishing.
Rakefile
Connections 23
- Engine → Controller: loads · Engine wires the controller integration into Rails.
- Engine → Helper: loads · Engine exposes helper methods to views.
- Engine → Config: configures · Engine installs library configuration into the app.
- Controller → Renderer: renders via · Controller delegates response construction to the renderer.
- Controller → Props resolver: builds props · Controller provides page data for prop resolution.
- Renderer → Props resolver: serializes · Renderer uses resolved props when producing responses.
- Props resolver → Prop types: applies rules · Resolver interprets lazy, cached, merge, and related prop behaviors.
- Controller → Current: uses · Controller reads request-scoped state.
- Middleware → Current: sets context · Middleware establishes per-request context.
- Middleware → Flash: extends flash · Middleware participates in flash propagation.
- Extensions → Middleware: hooks into · Extensions connect debugging and request mapping behavior.
- SSR core → SSR renderer: delegates · SSR core hands off actual rendering work.
- Puma plugin → SSR core: boots · Puma plugin starts or connects to SSR runtime.
- Install generator → Templates: installs · Install flow selects and copies starter templates.
- Scaffold generator → Templates: uses · Scaffold flow reuses frontend page templates.
- Docs app → Engine: documents · Docs explain the gem runtime and Rails integration.
- Dummy app → Engine: exercises · Dummy Rails app validates the engine and integration surface.
- Specs → Props resolver: tests · Specs cover prop behavior and resolution.
- Specs → Renderer: tests · Specs cover HTML and JSON response rendering.
- Specs → SSR core: tests · Specs cover SSR behavior and integration.
- Specs → Install generator: tests · Specs cover generator installation flows.
- Integration tests → Dummy app: runs on · Integration tests use the dummy Rails application.
- Rake tasks → Install generator: supports · Tasks help with gem packaging and release workflows.