# inertiajs/inertia-rails architecture

> Architecture diagram of the GitHub repository inertiajs/inertia-rails, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/inertiajs/inertia-rails
- Repository: https://github.com/inertiajs/inertia-rails

## Overview

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: [`lib/inertia_rails/engine.rb`](https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/engine.rb) (Engine), [`spec/inertia/renderer_spec.rb`](https://github.com/inertiajs/inertia-rails/blob/master/spec/inertia/renderer_spec.rb) (Specs), [`lib/inertia_rails/controller.rb`](https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/controller.rb) (Controller), [`lib/inertia_rails/props_resolver.rb`](https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/props_resolver.rb) (Props resolver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rails_integration["Rails integration"]
  node_lib_inertia_rails_engine["Engine<br/>[engine.rb]"]
  node_lib_inertia_rails_controller["Controller<br/>Rails mixin<br/>[controller.rb]"]
  node_lib_inertia_rails_helper["Helper<br/>[helper.rb]"]
  node_lib_inertia_rails_renderer["Renderer<br/>Response builder<br/>[renderer.rb]"]
  node_lib_inertia_rails_configuration["Config<br/>[configuration.rb]"]
  node_lib_inertia_rails_current["Current<br/>Request context<br/>[current.rb]"]
  node_lib_inertia_rails_middleware["Middleware<br/>[middleware.rb]"]
  node_lib_inertia_rails_extensions["Extensions<br/>Rails hooks<br/>[request.rb]"]
  node_lib_inertia_rails_flash_extension["Flash<br/>[flash_extension.rb]"]
end

subgraph group_prop_system["Prop system"]
  node_lib_inertia_rails_props_resolver["Props resolver<br/>Prop pipeline<br/>[props_resolver.rb]"]
  node_lib_inertia_rails_prop_types["Prop types<br/>Behavioral props<br/>[lazy_prop.rb]"]
end

subgraph group_ssr["SSR"]
  node_lib_inertia_rails_ssr["SSR core<br/>SSR runtime<br/>[ssr.rb]"]
  node_lib_inertia_rails_ssr_renderer["SSR renderer<br/>Render bridge<br/>[ssr_renderer.rb]"]
  node_lib_puma_plugin_inertia_ssr["Puma plugin<br/>[inertia_ssr.rb]"]
end

subgraph group_generators["Generators"]
  node_lib_generators_install["Install generator<br/>Rails generator"]
  node_lib_generators_scaffold["Scaffold generator<br/>Rails generator"]
  node_lib_generators_templates["Templates<br/>Template sets"]
end

subgraph group_docs["Docs site"]
  node_docs_vitepress["Docs app<br/>VitePress site<br/>[config.mts]"]
end

subgraph group_testing["Testing"]
  node_spec_dummy_app["Dummy app<br/>Rails app<br/>[application.rb]"]
  node_spec_suite["Specs<br/>Test suite<br/>[renderer_spec.rb]"]
  node_test_integration["Integration tests<br/>Minitest<br/>[inertia_test.rb]"]
end

subgraph group_tooling["Tooling"]
  node_bin_rake_tasks["Rake tasks<br/>Build/release tasks"]
end

node_lib_inertia_rails_engine -->|"loads"| node_lib_inertia_rails_controller
node_lib_inertia_rails_engine -->|"loads"| node_lib_inertia_rails_helper
node_lib_inertia_rails_engine -->|"configures"| node_lib_inertia_rails_configuration
node_lib_inertia_rails_controller -->|"renders via"| node_lib_inertia_rails_renderer
node_lib_inertia_rails_controller -->|"builds props"| node_lib_inertia_rails_props_resolver
node_lib_inertia_rails_renderer -->|"serializes"| node_lib_inertia_rails_props_resolver
node_lib_inertia_rails_props_resolver -->|"applies rules"| node_lib_inertia_rails_prop_types
node_lib_inertia_rails_controller -->|"uses"| node_lib_inertia_rails_current
node_lib_inertia_rails_middleware -->|"sets context"| node_lib_inertia_rails_current
node_lib_inertia_rails_middleware -->|"extends flash"| node_lib_inertia_rails_flash_extension
node_lib_inertia_rails_extensions -->|"hooks into"| node_lib_inertia_rails_middleware
node_lib_inertia_rails_ssr -->|"delegates"| node_lib_inertia_rails_ssr_renderer
node_lib_puma_plugin_inertia_ssr -->|"boots"| node_lib_inertia_rails_ssr
node_lib_generators_install -->|"installs"| node_lib_generators_templates
node_lib_generators_scaffold -->|"uses"| node_lib_generators_templates
node_docs_vitepress -.->|"documents"| node_lib_inertia_rails_engine
node_spec_dummy_app -->|"exercises"| node_lib_inertia_rails_engine
node_spec_suite -->|"tests"| node_lib_inertia_rails_props_resolver
node_spec_suite -->|"tests"| node_lib_inertia_rails_renderer
node_spec_suite -->|"tests"| node_lib_inertia_rails_ssr
node_spec_suite -->|"tests"| node_lib_generators_install
node_test_integration -->|"runs on"| node_spec_dummy_app
node_bin_rake_tasks -.->|"supports"| node_lib_generators_install

click node_lib_inertia_rails_engine "https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/engine.rb"
click node_lib_inertia_rails_controller "https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/controller.rb"
click node_lib_inertia_rails_helper "https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/helper.rb"
click node_lib_inertia_rails_renderer "https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/renderer.rb"
click node_lib_inertia_rails_props_resolver "https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/props_resolver.rb"
click node_lib_inertia_rails_prop_types "https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/lazy_prop.rb"
click node_lib_inertia_rails_configuration "https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/configuration.rb"
click node_lib_inertia_rails_current "https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/current.rb"
click node_lib_inertia_rails_middleware "https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/middleware.rb"
click node_lib_inertia_rails_extensions "https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/extensions/request.rb"
click node_lib_inertia_rails_flash_extension "https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/flash_extension.rb"
click node_lib_inertia_rails_ssr "https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/ssr.rb"
click node_lib_inertia_rails_ssr_renderer "https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/ssr_renderer.rb"
click node_lib_puma_plugin_inertia_ssr "https://github.com/inertiajs/inertia-rails/blob/master/lib/puma/plugin/inertia_ssr.rb"
click node_lib_generators_install "https://github.com/inertiajs/inertia-rails/blob/master/lib/generators/inertia/install/install_generator.rb"
click node_lib_generators_scaffold "https://github.com/inertiajs/inertia-rails/blob/master/lib/generators/inertia/scaffold/scaffold_generator.rb"
click node_lib_generators_templates "https://github.com/inertiajs/inertia-rails/blob/master/lib/generators/inertia_templates/controller/controller_generator.rb"
click node_docs_vitepress "https://github.com/inertiajs/inertia-rails/blob/master/docs/.vitepress/config.mts"
click node_spec_dummy_app "https://github.com/inertiajs/inertia-rails/blob/master/spec/dummy/config/application.rb"
click node_spec_suite "https://github.com/inertiajs/inertia-rails/blob/master/spec/inertia/renderer_spec.rb"
click node_test_integration "https://github.com/inertiajs/inertia-rails/blob/master/test/integration/inertia_test.rb"
click node_bin_rake_tasks "https://github.com/inertiajs/inertia-rails/tree/master/Rakefile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_lib_inertia_rails_engine,node_lib_inertia_rails_controller,node_lib_inertia_rails_helper,node_lib_inertia_rails_renderer,node_lib_inertia_rails_configuration,node_lib_inertia_rails_current,node_lib_inertia_rails_middleware,node_lib_inertia_rails_extensions,node_lib_inertia_rails_flash_extension,node_bin_rake_tasks toneBlue
class node_lib_inertia_rails_props_resolver,node_lib_inertia_rails_prop_types toneAmber
class node_lib_inertia_rails_ssr,node_lib_inertia_rails_ssr_renderer,node_lib_puma_plugin_inertia_ssr toneMint
class node_lib_generators_install,node_lib_generators_scaffold,node_lib_generators_templates toneRose
class node_docs_vitepress toneIndigo
class node_spec_dummy_app,node_spec_suite,node_test_integration toneTeal
```

## Components

### Rails integration

Server-side Rails engine, controller surface, view entrypoints, and runtime hooks.

- [Engine](https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/engine.rb): Rails engine · Gem entrypoint that mounts the library into Rails. · `lib/inertia_rails/engine.rb`
- [Controller](https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/controller.rb): Rails mixin · Controller API for rendering Inertia responses and sharing state. · `lib/inertia_rails/controller.rb`
- [Helper](https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/helper.rb): View helper · View-side helper methods for Inertia integration. · `lib/inertia_rails/helper.rb`
- [Renderer](https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/renderer.rb): Response builder · Converts controller intent into HTML or JSON Inertia responses. · `lib/inertia_rails/renderer.rb`
- [Config](https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/configuration.rb): Runtime config · Framework configuration and app-level settings. · `lib/inertia_rails/configuration.rb`
- [Current](https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/current.rb): Request context · Per-request state and shared current values. · `lib/inertia_rails/current.rb`
- [Middleware](https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/middleware.rb): Rack middleware · Request/response integration around Rails and Inertia behavior. · `lib/inertia_rails/middleware.rb`
- [Extensions](https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/extensions/request.rb): Rails hooks · Adapters for request mapping, debugging, and error-handling integrations. · `lib/inertia_rails/extensions/request.rb`
- [Flash](https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/flash_extension.rb): Flash bridge · 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](https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/props_resolver.rb): Prop pipeline · Resolves, transforms, and serializes page props. · `lib/inertia_rails/props_resolver.rb`
- [Prop types](https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/lazy_prop.rb): Behavioral props · 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](https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/ssr.rb): SSR runtime · SSR request handling and orchestration. · `lib/inertia_rails/ssr.rb`
- [SSR renderer](https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/ssr_renderer.rb): Render bridge · Executes server-side rendering for page components. · `lib/inertia_rails/ssr_renderer.rb`
- [Puma plugin](https://github.com/inertiajs/inertia-rails/blob/master/lib/puma/plugin/inertia_ssr.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](https://github.com/inertiajs/inertia-rails/blob/master/lib/generators/inertia/install/install_generator.rb): Rails generator · Installs the gem into a host app and chooses frontend stack templates. · `lib/generators/inertia/install/install_generator.rb`
- [Scaffold generator](https://github.com/inertiajs/inertia-rails/blob/master/lib/generators/inertia/scaffold/scaffold_generator.rb): Rails generator · Generates CRUD pages and controller scaffolding for Inertia apps. · `lib/generators/inertia/scaffold/scaffold_generator.rb`
- [Templates](https://github.com/inertiajs/inertia-rails/blob/master/lib/generators/inertia_templates/controller/controller_generator.rb): Template sets · 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](https://github.com/inertiajs/inertia-rails/blob/master/docs/.vitepress/config.mts): VitePress site · Standalone documentation frontend and content pipeline. · `docs/.vitepress/config.mts`

### Testing

Dummy Rails app and automated coverage for library behavior.

- [Dummy app](https://github.com/inertiajs/inertia-rails/blob/master/spec/dummy/config/application.rb): Rails app · Full Rails host used to validate integration behavior end to end. · `spec/dummy/config/application.rb`
- [Specs](https://github.com/inertiajs/inertia-rails/blob/master/spec/inertia/renderer_spec.rb): Test suite · Focused coverage for props, rendering, middleware, SSR, generators, and adapters. · `spec/inertia/renderer_spec.rb`
- [Integration tests](https://github.com/inertiajs/inertia-rails/blob/master/test/integration/inertia_test.rb): Minitest · Additional integration coverage in the test/ tree. · `test/integration/inertia_test.rb`

### Tooling

Repo scripts, packaging, CI, and release automation.

- [Rake tasks](https://github.com/inertiajs/inertia-rails/tree/master/Rakefile): Build/release tasks · Task entrypoints for versioning, setup, and gem publishing. · `Rakefile`

## Connections

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