inertia_rails 3.21.1 → 3.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e75f704d4ac9af2da022ca9e0fb08f2954820e15095b8845809af1fc2b3470fa
-  data.tar.gz: 5ac24d6b30235de6c66f5bab59eb526e72804df26cb265c3894d214fbfd7fa98
+  metadata.gz: 4e9384ee4e756ec30efcbb0afa77c7d557d02dd4d5dc60f1dc6239ec1d0b1878
+  data.tar.gz: 98e207f798ae91e888f1de274caa506bbc289ac51ea2e20e2eb5465f818575fd
 SHA512:
-  metadata.gz: ed6bd7549422be3fffff41dfaf41502ea8d6850f23a408db31616b29ef7d1fecf3c64e74a46d6a425d80bc2c70161402b92ad25b560691ec9ef36f31403d1dba
-  data.tar.gz: 1154a428ebd8ffd146317e7aa98b996337ae445fa5f4197dac07491837b2f00d8ba13562e621b701725bebf40243a05eaf74775bf67fdef85d3ab0b008b1c1fb
+  metadata.gz: 6d9dd387eb80c39743d7d48268ef7540710a27194c52f165e4f75565fd4e76cc151db286b64b5e050fa387027b80a0eb3b37210908068a826cfedfe6003aea67
+  data.tar.gz: 3309e07158894db2e60b03c15e0f46b8d056e09821487412709b738a5ceeb2508c54d5df7421ad77ee04e30a2592e8a07a48de720192446ad5290e18c423eb47

data/CHANGELOG.md

@@ -6,6 +6,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.22.0] - 2026-07-17
+
+* Only set the `XSRF-TOKEN` cookie on HTML and XHR responses. Other responses no longer carry a `Set-Cookie` that keeps CDNs from caching them — notably ActiveStorage's images, since its controllers also inherit from `ActionController::Base` (@acetinick)
+* Add `xsrf_cookie_refresh` configuration option. Set to `:lazy` to skip rewriting the `XSRF-TOKEN` cookie on safe requests when a valid cookie is already present, keeping conditionally cached (`ETag`/`304`) responses free of `Set-Cookie` churn (@darkamenosa)
+* Fix `inertia: { errors: }` and `inertia: { clear_history: }` being discarded when `redirect_to` is given an explicit non-302 status such as `status: :see_other` (303/307/308) (@skryukov)
+* Fix cross-variant `304 Not Modified` responses under HTTP conditional caching (`fresh_when` / `stale?`) by folding the Inertia request headers into the ETag, so HTML, JSON, and partial-reload representations of the same URL no longer share a validator (@skryukov)
+* Generate controller views at the paths resolved by `render inertia: true` (@oiahoon)
+* Add `@inertiajs/core` as a direct dev dependency in the TypeScript install generator, so pnpm exposes the adapter types that `globals.d.ts` augments (@heyrobertchang)
+* Fix option handling in the `inertia` routes helper: user-supplied `defaults:` no longer replace the component (previously producing `component: null` responses), the route-to-component pair no longer leaks into `params`, and additional String-keyed pairs define routes instead of being silently dropped (@skryukov)
+* Raise a clear error when `parent_controller` does not inherit from `ActionController::Base` instead of an opaque `NoMethodError` (@skryukov)
+* Add static `props:` support to the `inertia` routes helper: `inertia 'about' => 'About', props: { title: 'About us' }` (@skryukov)
+* Deduplicate `X-Inertia` in the `Vary` response header (@skryukov)
+
+## [3.21.2] - 2026-06-09
+
+* Add `rescue: true` option to `InertiaRails.defer` to rescue and report exceptions raised while resolving a deferred prop (@skryukov)
+* Add CSP nonce to the initial page script when needed (@nicholaspufal)
+* Fix Vite install to use the configured package manager in the generator (@akicho8)
+* Fix TypeScript packages installed as dependencies instead of devDependencies (@alec-c4)
+
 ## [3.21.1] - 2026-05-19
 
 * Specify initializer run order for middleware insertion to avoid frozen middleware stack errors on Rails 8.1+ (@julik)

data/README.md

@@ -1,347 +1,155 @@
-![image](https://user-images.githubusercontent.com/6599653/114456558-032e2200-9bab-11eb-88bc-a19897f417ba.png)
-
-
-# Inertia.js Rails Adapter
-
-## Installation
-
-### Backend
-
-Add the `inertia_rails` gem to your Gemfile.
-
-```ruby
-gem 'inertia_rails'
-```
-
-Follow the complete [Server-side setup](https://inertia-rails.dev/guide/server-side-setup) in the official documentation.
-
-### Frontend
-
-Follow the [Client-side setup](https://inertia-rails.dev/guide/client-side-setup) guide for detailed configuration steps.
-
-### Example Projects:
-
-Reference these sample implementations:
-
-- [React/Vite](https://github.com/BrandonShar/inertia-rails-template)
-- [React/Vite + SSR](https://github.com/ElMassimo/inertia-rails-ssr-template)
-- [PingCRM with Vue and Vite](https://github.com/ledermann/pingcrm)
-
-## Usage
-
-### Responses
-
-Render Inertia responses is simple, just use the inertia renderer in your controller methods. The renderer accepts two arguments, the first is the name of the component you want to render from within your pages directory (without extension). The second argument is an options hash where you can provide `props` to your components. This options hash also allows you to pass `view_data` to your layout, but this is much less common.
-
-```ruby
-def index
-  render inertia: 'Event/Index', props: {
-    events: Event.all,
-  }
-end
-```
-
-#### Rails Component and Instance Props 
-
-Starting in version 3.0, Inertia Rails allows you to provide your component name and props via common rails conventions. 
-
-```ruby
-class EventsController < ApplicationController
-  use_inertia_instance_props
-
+<div align="center">
+  <a href="https://inertia-rails.dev">
+    <img src="https://inertia-rails.dev/logo.svg" alt="Inertia Rails" width="150">
+  </a>
+
+  <h1>Build frontend experiences with the backend you love</h1>
+
+  <p>
+    <strong>Single-page React, Vue, and Svelte apps powered by your existing Rails
+    controllers, routes, and authentication. No API required.</strong>
+  </p>
+
+  <p>
+    <a href="https://rubygems.org/gems/inertia_rails"><img src="https://img.shields.io/gem/v/inertia_rails" alt="Gem version"></a>
+    <a href="https://rubygems.org/gems/inertia_rails"><img src="https://img.shields.io/gem/dt/inertia_rails" alt="Downloads"></a>
+    <a href="https://github.com/inertiajs/inertia-rails/actions/workflows/push.yml"><img src="https://github.com/inertiajs/inertia-rails/actions/workflows/push.yml/badge.svg" alt="Build status"></a>
+    <a href="https://github.com/inertiajs/inertia-rails/blob/master/LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+    <a href="https://discord.gg/inertiajs"><img src="https://img.shields.io/badge/discord-join-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
+  </p>
+
+  <p>
+    <a href="https://inertia-rails.dev"><strong>Documentation</strong></a> ·
+    <a href="https://inertia-rails.dev/guide/server-side-setup"><strong>Get started</strong></a> ·
+    <a href="https://inertia-rails.dev/guide/demo-application"><strong>Demo</strong></a> ·
+    <a href="https://discord.gg/inertiajs"><strong>Discord</strong></a>
+  </p>
+</div>
+
+---
+
+## Your controllers. Your routes. Modern components.
+
+Inertia lets you build a fully client-side rendered single-page app without the
+complexity of a separate API. Pass data from Rails directly to React, Vue, or
+Svelte as **props** — no REST endpoints, no GraphQL, no client-side data
+fetching, no state-management headaches.
+
+```ruby
+# app/controllers/users_controller.rb
+class UsersController < ApplicationController
   def index
-    @events = Event.all
-  end
-
-end
-```
-
-is the same as 
-
-
-```ruby
-class EventsController < ApplicationController
-  def index
-    render inertia: 'events/index', props: {
-      events: Event.all
+    render inertia: {
+      users: User.active.map { |user| user.as_json(only: [:id, :name, :email]) }
     }
   end
 end
 ```
 
-#### Instance Props and Default Render Notes 
-
-In order to use instance props, you must call `use_inertia_instance_props` on the controller (or a base controller it inherits from). If any props are provided manually, instance props
-are automatically disabled for that response. Instance props are only included if they are defined after the before filter is set from `use_inertia_instance_props`.
+```jsx
+// app/frontend/pages/users/index.jsx
+import { Link } from '@inertiajs/react'
 
-Automatic component name is also opt in, you must set the [`default_render`](#default_render) config value to `true`. Otherwise, you can simply `render inertia: true` for the same behavior explicitly.
-
-If the default component path doesn't match your convention, you can define a method to resolve it however you like via the `component_path_resolver` config value. The value of this should be callable and will receive the path and action and should return a string component path.
-
-```ruby
-inertia_config(
-  component_path_resolver: ->(path:, action:) do
-    "Storefront/#{path.camelize}/#{action.camelize}"
-  end
+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
 ```
 
+That's the whole loop: the controller returns props, the component renders them.
+Links and form submits are intercepted and turned into XHR visits, so navigation
+feels instant — but you're still writing plain Rails on the server.
 
+## Get started
 
-### Layout 
-
-Inertia layouts use the rails layout convention and can be set or changed in the same way.
-
-```ruby
-class EventsController < ApplicationController
-  layout 'inertia_application'
-end
-```
-
-
-### Shared Data
-
-If you have data that you want to be provided as a prop to every component (a common use-case is information about the authenticated user) you can use the `inertia_share` controller method.
-
-```ruby
-class EventsController < ApplicationController
-  # share synchronously
-  inertia_share app_name: env['app.name']
-  
-  # share lazily, evaluated at render time
-  inertia_share do
-    if logged_in?
-      {
-        user: logged_in_user,
-      }
-    end
-  end
-  
-  # share lazily alternate syntax
-  inertia_share user_count: lambda { User.count }
-  
-end
-```
-
-#### Deep Merging Shared Data
-
-By default, Inertia will shallow merge data defined in an action with the shared data. You might want a deep merge. Imagine using shared data to represent defaults you'll override sometimes.
-
-```ruby
-class ApplicationController
-  inertia_share do
-    { basketball_data: { points: 50, rebounds: 100 } }
-  end
-end
-```
-
-Let's say we want a particular action to change only part of that data structure. The renderer accepts a `deep_merge` option:
-
-```ruby
-class CrazyScorersController < ApplicationController
-  def index
-    render inertia: 'CrazyScorersComponent',
-    props: { basketball_data: { points: 100 } },
-    deep_merge: true
-  end
-end
-
-# The renderer will send this to the frontend:
-{
-  basketball_data: {
-    points: 100,
-    rebounds: 100,
-  }
-}
-```
-
-Deep merging can be configured using the [`deep_merge_shared_data`](#deep_merge_shared_data) configuration option.
-
-If deep merging is enabled, you can still opt-out within the action:
-
-```ruby
-class CrazyScorersController < ApplicationController
-  inertia_config(deep_merge_shared_data: true)
-
-  inertia_share do
-    {
-      basketball_data: {
-        points: 50,
-        rebounds: 10,
-      }
-    }
-  end
-
-  def index
-    render inertia: 'CrazyScorersComponent',
-    props: { basketball_data: { points: 100 } },
-    deep_merge: false
-  end
-end
+**Add to an existing Rails app** — the installer sets up Vite, your chosen framework, and example pages:
 
-# `deep_merge: false` overrides the default:
-{
-  basketball_data: {
-    points: 100,
-  }
-}
+```bash
+bundle add inertia_rails
+bin/rails generate inertia:install
 ```
 
-### Optional Props
-
-On the frontend, Inertia supports the concept of "partial reloads" where only the props requested are returned by the server. Sometimes, you may want to use this flow to avoid processing a particularly slow prop on the initial load. In this case, you can use Optional props. Optional props aren't evaluated unless they're specifically requested by name in a partial reload.
+**Or start from a kit** with authentication, Vite, optional SSR, and Kamal
+deployment already wired up:
 
-```ruby
-  inertia_share some_data: InertiaRails.optional { some_very_slow_method }
-```
+- [React Starter Kit](https://github.com/inertia-rails/react-starter-kit) — React 19 · TypeScript · shadcn/ui
+- [Vue Starter Kit](https://github.com/inertia-rails/vue-starter-kit) — Vue 3 · TypeScript · shadcn-vue
+- [Svelte Starter Kit](https://github.com/inertia-rails/svelte-starter-kit) — Svelte 5 · TypeScript · shadcn-svelte
 
-### Routing
+Full walkthrough: **[Server-side setup](https://inertia-rails.dev/guide/server-side-setup)** and **[Client-side setup](https://inertia-rails.dev/guide/client-side-setup)**.
 
-If you don't need a controller to handle a static component, you can route directly to a component with the inertia route helper
+## Built for real Rails apps
 
-```ruby
-inertia 'about' => 'AboutComponent'
-```
+| | |
+|---|---|
+| **[Forms that work](https://inertia-rails.dev/guide/forms)** | Validation errors flow from Rails to your components automatically — no manual wiring. |
+| **[Server-side rendering](https://inertia-rails.dev/guide/server-side-rendering)** | Full SSR for SEO and fast first paint. Your React/Vue/Svelte, rendered on Rails. |
+| **[Test like Rails](https://inertia-rails.dev/guide/testing)** | RSpec and Minitest matchers that feel native. Assert on props, components, and more. |
+| **[Partial reloads](https://inertia-rails.dev/guide/partial-reloads)** | Refresh only the data you need. Keep interactions snappy without full page loads. |
+| **[Shared data](https://inertia-rails.dev/guide/shared-data)** | Current user, flash, permissions — available on every page automatically. |
+| **[Deferred props](https://inertia-rails.dev/guide/deferred-props)** | Load the page fast, fetch expensive data after, with built-in loading states. |
+| **[Rails generators](https://inertia-rails.dev/guide/server-side-setup)** | Scaffold entire CRUD interfaces — controllers with matching components. |
+| **[History encryption](https://inertia-rails.dev/guide/history-encryption)** | Keep sensitive data private, even in browser history. Toggle per page. |
 
-### SSR _(experimental)_
+## Why Inertia?
 
-Enable SSR via the configuration options for [`ssr_enabled`](#ssr_enabled-experimental) and [`ssr_url`](#ssr_url-experimental).
+Inertia sits between traditional server-rendered apps and full SPAs.
 
-When using SSR, don't forget to add `<%= inertia_ssr_head %>` to the `<head>` of your layout (i.e. `application.html.erb`).
+**vs. Hotwire** — Same monolith, different view layer. Both keep you in Rails;
+Inertia gives you the full React/Vue/Svelte component model and the npm
+ecosystem instead of HTML-over-the-wire. Choose Hotwire for minimal JS and
+server-rendered HTML; choose Inertia for a modern component architecture.
 
-## Configuration ⚙️
+**vs. API + SPA** — Same frontend, no API hassle. Both give you React/Vue/Svelte,
+but Inertia removes the API layer entirely: one router (Rails), Rails sessions
+instead of a JWT/OAuth dance, and props from your controller instead of fetching
+in `useEffect`. Choose an API for public/mobile clients; choose Inertia for
+focused web products. (You can always add an API alongside Inertia later.)
 
-Inertia Rails can be configured globally or in a specific controller (and subclasses).
+See the full [comparison and FAQ](https://inertia-rails.dev/#why-inertia) →
 
-### Global Configuration
+## Documentation
 
-If using global configuration, we recommend you place the code inside an initializer:
+Everything lives at **[inertia-rails.dev](https://inertia-rails.dev)**:
 
-```ruby
-# config/initializers/inertia.rb
+- [How it works](https://inertia-rails.dev/guide/how-it-works)
+- [Pages & layouts](https://inertia-rails.dev/guide/pages)
+- [Forms & validation](https://inertia-rails.dev/guide/forms)
+- [Shared data](https://inertia-rails.dev/guide/shared-data) · [Partial reloads](https://inertia-rails.dev/guide/partial-reloads) · [Deferred props](https://inertia-rails.dev/guide/deferred-props)
+- [Server-side rendering](https://inertia-rails.dev/guide/server-side-rendering)
+- [Testing](https://inertia-rails.dev/guide/testing)
+- [Configuration reference](https://inertia-rails.dev/guide/configuration)
 
-InertiaRails.configure do |config|
-  # Example: force a full-reload if the deployed assets change.
-  config.version = ViteRuby.digest
-end
-```
+## Community
 
-The default configuration can be found [here](https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/configuration.rb#L5-L22).
+- [Awesome Inertia Rails](https://inertia-rails.dev/awesome) — gems, tutorials, and real-world apps
+- [Discord](https://discord.gg/inertiajs) — ask questions, get answers fast
+- [GitHub Discussions & Issues](https://github.com/inertiajs/inertia-rails/issues) — browse the source, report bugs
 
-### Local Configuration
+## Contributing
 
-Use `inertia_config` in your controllers to override global settings:
+Bug reports and pull requests are welcome. To run the test suite:
 
-```ruby
-class EventsController < ApplicationController
-  inertia_config(
-    version: "events-#{InertiaRails.configuration.version}",
-    ssr_enabled: -> { action_name == "index" },
-  )
-end
+```bash
+bundle install
+bundle exec rspec
 ```
 
-### Configuration Options
-
-#### `version` _(recommended)_
-
-  This allows Inertia to detect if the app running in the client is oudated,
-  forcing a full page visit instead of an XHR visit on the next request.
-
-  See [assets versioning](https://inertiajs.com/asset-versioning).
-
-  __Default__: `nil`
-
-#### `deep_merge_shared_data`
-
-  When enabled, props will be deep merged with shared data, combining hashes
-  with the same keys instead of replacing them.
-
-  __Default__: `false`
+See the [Code of Conduct](CODE_OF_CONDUCT.md). Everyone interacting with the
+project is expected to follow it.
 
-#### `default_render`
-
-  Overrides Rails default rendering behavior to render using Inertia by default.
-
-  __Default__: `false`
-
-#### `encrypt_history`
-
-  When enabled, you instruct Inertia to encrypt your app's history, it uses
-  the browser's built-in [`crypto` api](https://developer.mozilla.org/en-US/docs/Web/API/Crypto)
-  to encrypt the current page's data before pushing it to the history state.
-
-  __Default__: `false`
-
-#### `ssr_enabled` _(experimental)_
-
-  Whether to use a JavaScript server to pre-render your JavaScript pages,
-  allowing your visitors to receive fully rendered HTML when they first visit
-  your application.
-
-  Requires a JS server to be available at `ssr_url`. [_Example_](https://github.com/ElMassimo/inertia-rails-ssr-template)
-
-  __Default__: `false`
-
-#### `ssr_url` _(experimental)_
-
-  The URL of the JS server that will pre-render the app using the specified
-  component and props.
-
-  __Default__: `"http://localhost:13714"`
-
-## Testing
-
-If you're using Rspec, Inertia Rails comes with some nice test helpers to make things simple. 
-
-To use these helpers, just add the following require statement to your `spec/rails_helper.rb`
-
-```ruby
-require 'inertia_rails/rspec'
-```
-
-And in any test you want to use the inertia helpers, add the inertia flag to the describe block
-
-```ruby
-RSpec.describe EventController, type: :request do
-  describe '#index', inertia: true do
-    # ...
-  end
-end
-```
-
-### Assertions
-
-```ruby
-RSpec.describe EventController, type: :request do
-  describe '#index', inertia: true do
-    
-    # check the component
-    expect_inertia.to render_component 'Event/Index'
-    
-    # access the component name
-    expect(inertia.component).to eq 'TestComponent'
-    
-    # props (including shared props)
-    expect_inertia.to have_exact_props({name: 'Brandon', sport: 'hockey'})
-    expect_inertia.to include_props({sport: 'hockey'})
-    
-    # access props
-    expect(inertia.props[:name]).to eq 'Brandon'
-    
-    # view data
-    expect_inertia.to have_exact_view_data({name: 'Brian', sport: 'basketball'})
-    expect_inertia.to include_view_data({sport: 'basketball'})
-    
-    # access view data 
-    expect(inertia.view_data[:name]).to eq 'Brian'
-    
-  end
-end
-
-```
+## Credits
 
-*Maintained and sponsored by the team at [bellaWatt](https://bellawatt.com/)*
+Inertia Rails is part of the official [Inertia.js](https://inertiajs.com)
+organization. It was originally created by the team at
+[bellaWatt](https://bellawatt.com) and is maintained by the Inertia.js community.
 
-[![bellaWatt Logo](https://user-images.githubusercontent.com/6599653/114456832-5607d980-9bab-11eb-99c8-ab39867c384e.png)](https://bellawatt.com/)
+Released under the [MIT License](LICENSE.txt).

data/app/controllers/inertia_rails/static_controller.rb

@@ -3,8 +3,16 @@
 module InertiaRails
   class StaticController < InertiaRails.configuration.parent_controller.constantize
     def static
+      # Checked at dispatch, not load: eager loading defines this class even
+      # in apps that never draw an `inertia` route, and those must still boot.
+      unless is_a?(::ActionController::Base)
+        raise ArgumentError,
+              '`config.parent_controller` must inherit from ActionController::Base to serve `inertia` routes, ' \
+              "got #{InertiaRails.configuration.parent_controller.inspect}"
+      end
+
       respond_to do |format|
-        format.html { render inertia: params[:component] }
+        format.html { render inertia: params[:component], props: request.path_parameters[:props]&.deep_dup || {} }
       end
     end
   end

data/lib/generators/inertia/install/frameworks.yml

@@ -31,7 +31,8 @@ vue:
     - "@vitejs/plugin-vue"
     - "vite@latest"
   packages_ts:
-    - "typescript"
+    # vue-tsc requires typescript/lib/tsc, removed in TypeScript 7
+    - "typescript@^6"
     - "vue-tsc"
   vite_plugin_import: "import vue from '@vitejs/plugin-vue'"
   vite_plugin_call: "vue()"
@@ -55,7 +56,8 @@ svelte:
   packages_ts:
     - "@tsconfig/svelte@5"
     - "svelte-check"
-    - "typescript"
+    # svelte-check uses the TypeScript API, gone from TypeScript 7's package entry
+    - "typescript@^6"
     - "tslib"
   vite_plugin_import: "import { svelte } from '@sveltejs/vite-plugin-svelte'"
   vite_plugin_call: "svelte()"

data/lib/generators/inertia/install/install_generator.rb

@@ -142,7 +142,13 @@ module Inertia
       def install_typescript
         say 'Adding TypeScript support'
 
-        add_dependencies(*FRAMEWORKS[framework]['packages_ts'])
+        # globals.d.ts augments @inertiajs/core and scaffolds import its types;
+        # pnpm won't expose the adapters' transitive dep, so declare it directly.
+        add_dependencies(
+          "@inertiajs/core@#{options[:inertia_version]}",
+          *FRAMEWORKS[framework]['packages_ts'],
+          dev: true
+        )
 
         say 'Copying tsconfig and types'
 
@@ -223,7 +229,8 @@ module Inertia
               say_error 'Failed to install Vite Rails gem', :red
               exit(false)
             end
-            if (capture = run('bundle exec vite install', capture: !verbose?))
+            vite_ruby_install_options = package_manager.present? ? "--package-manager=#{package_manager.name}" : ''
+            if (capture = run("bundle exec vite install #{vite_ruby_install_options}", capture: !verbose?))
               rename_application_js_to_ts if typescript?
               run('bundle binstub vite_ruby', capture: !verbose?) unless File.exist?(file_path('bin/vite'))
               say 'Vite Rails successfully installed', :green
@@ -282,8 +289,8 @@ module Inertia
         @package_manager ||= JSPackageManager.new(self)
       end
 
-      def add_dependencies(*packages)
-        package_manager.add_dependencies(*packages)
+      def add_dependencies(*packages, dev: false)
+        package_manager.add_dependencies(*packages, dev: dev)
       end
 
       def vite_config_path

data/lib/generators/inertia/install/js_package_manager.rb

@@ -15,10 +15,11 @@ module Inertia
         name.present?
       end
 
-      def add_dependencies(*dependencies)
+      def add_dependencies(*dependencies, dev: false)
+        dev_flag = dev ? ' -D' : ''
         options = @generator.options[:verbose] ? '' : ' --silent'
         @generator.in_root do
-          @generator.run "#{name} add #{dependencies.join(' ')}#{options}"
+          @generator.run "#{name} add#{dev_flag} #{dependencies.join(' ')}#{options}"
         end
       end
 

data/lib/inertia_rails/configuration.rb

@@ -3,6 +3,7 @@
 module InertiaRails
   class Configuration
     DEFAULT_SSR_URL = 'http://localhost:13714'
+    XSRF_COOKIE_REFRESH_OPTIONS = %i[always lazy].freeze
 
     DEFAULTS = {
       # Whether to combine hashes with the same keys instead of replacing them.
@@ -51,6 +52,9 @@ module InertiaRails
       # Whether to include empty `errors` hash to the props when no errors are present.
       always_include_errors_hash: nil,
 
+      # When to refresh the XSRF token cookie on protected requests.
+      xsrf_cookie_refresh: :always,
+
       # Whether to use `<script>` element for initial page rendering instead of the `data-page` attribute.
       use_script_element_for_initial_page: false,
 
@@ -149,6 +153,17 @@ module InertiaRails
       @options[:cache_store] || Rails.cache
     end
 
+    # Normalized and validated at read time — ENV values arrive as strings, and callables are only evaluated here.
+    def xsrf_cookie_refresh
+      value = evaluate_option(options[:xsrf_cookie_refresh])
+      value = value.to_sym if value.respond_to?(:to_sym)
+      return value if XSRF_COOKIE_REFRESH_OPTIONS.include?(value)
+
+      raise ArgumentError,
+            "Invalid xsrf_cookie_refresh: #{value.inspect}. " \
+            "Expected one of: #{XSRF_COOKIE_REFRESH_OPTIONS.map(&:inspect).join(', ')}"
+    end
+
     OPTION_NAMES.each do |option|
       unless method_defined?(option)
         define_method(option) do

data/lib/inertia_rails/controller.rb

@@ -11,8 +11,18 @@ module InertiaRails
         InertiaRails::Current.request = request
       end
 
+      # The same URL answers as HTML, Inertia JSON, or a partial reload; fold the
+      # representation into the conditional-GET validator so they don't share an ETag.
+      etag { inertia_conditional_get_variant }
+
       after_action do
-        cookies['XSRF-TOKEN'] = form_authenticity_token if protect_against_forgery?
+        next unless protect_against_forgery?
+        # Included into ActionController::Base, so this runs for non-Inertia
+        # responses too — ActiveStorage images, where it only breaks CDN caching.
+        next unless request.format.html? || request.xhr?
+        next if XsrfCookieRefreshPolicy.skip?(self)
+
+        cookies['XSRF-TOKEN'] = form_authenticity_token
       end
 
       rescue_from InertiaRails::PrecognitionResponse do |e|
@@ -112,6 +122,13 @@ module InertiaRails
       view_assigns.except(*@_inertia_skip_props)
     end
 
+    # nil for plain requests — compacted out of the ETag, so non-Inertia ETags are unchanged.
+    def inertia_conditional_get_variant
+      return unless request.inertia?
+
+      request.env.filter_map { |key, value| "#{key}=#{value}" if key.start_with?('HTTP_X_INERTIA') }.sort
+    end
+
     # Rails < 8: _normalize_options overwrites :layout with a resolved default,
     # making an explicit `layout: false` indistinguishable from "not provided".
     # Stash the original value so the renderer can tell the two apart.

data/lib/inertia_rails/defer_prop.rb

@@ -14,10 +14,15 @@ module InertiaRails
       super(&block)
 
       @group = props[:group] || DEFAULT_GROUP
+      @rescue = props.fetch(:rescue, false)
     end
 
     def deferred?
       true
     end
+
+    def rescue?
+      @rescue
+    end
   end
 end

data/lib/inertia_rails/extensions/mapper.rb

@@ -3,17 +3,29 @@
 module InertiaRails
   module InertiaMapper
     def inertia(*args, **options)
-      path = args.any? ? args.first : options
-      route, component = extract_route_and_component(path)
-      get(route, to: StaticController.action(:static), defaults: { component: component }, **options)
+      defaults = options.delete(:defaults) || {}
+      defaults = defaults.merge(props: options.delete(:props)) if options.key?(:props)
+
+      extract_routes(args, options).each do |route, component|
+        get(route, to: StaticController.action(:static), defaults: defaults.merge(component: component), **options)
+      end
     end
 
     private
 
-    def extract_route_and_component(path)
-      if path.is_a?(Hash)
-        path.first
-      elsif resource_scope?
+    # The first hash pair is the route; any further String-keyed pairs are
+    # additional routes. Symbol-keyed leftovers are route options (`on:`, `as:`).
+    def extract_routes(args, options)
+      return [route_with_default_component(args.first)] if args.any?
+
+      route = options.keys.first
+      routes = [[route, options.delete(route)]]
+      options.keys.grep(String).each { |extra| routes << [extra, options.delete(extra)] }
+      routes
+    end
+
+    def route_with_default_component(path)
+      if resource_scope?
         [path,
          InertiaRails.configuration.component_path_resolver(
            path: [@scope[:module], @scope[:controller]].compact.join('/'), action: path

data/lib/inertia_rails/generators/controller_template_base.rb

@@ -8,8 +8,8 @@ module InertiaRails
     class ControllerTemplateBase < Rails::Generators::NamedBase
       include Helper
 
-      class_option :frontend_framework, required: true, desc: 'Frontend framework to generate the views for.',
-                                        default: Helper.guess_the_default_framework
+      class_option :frontend_framework,
+                   desc: 'Frontend framework to generate the views for (defaults to the one detected in package.json).'
 
       class_option :typescript, type: :boolean, desc: 'Whether to use TypeScript',
                                 default: Helper.uses_typescript?
@@ -23,13 +23,17 @@ module InertiaRails
       def copy_view_files
         actions.each do |action|
           @action = action
-          @path = File.join(base_path, "#{action.camelize}.#{extension}")
-          template "#{options.frontend_framework}/#{template_filename}.#{extension}", @path
+          @path = File.join(base_path, "#{action}.#{extension}")
+          template "#{frontend_framework}/#{template_filename}.#{extension}", @path
         end
       end
 
       private
 
+      def frontend_framework
+        options[:frontend_framework] || Helper.guess_the_default_framework
+      end
+
       def base_path
         File.join(pages_path, inertia_base_path)
       end
@@ -47,12 +51,12 @@ module InertiaRails
       end
 
       def extension
-        case options.frontend_framework
+        case frontend_framework
         when 'react' then typescript? ? 'tsx' : 'jsx'
         when 'vue' then 'vue'
         when 'svelte' then 'svelte'
         else
-          raise ArgumentError, "Unknown frontend framework: #{options.frontend_framework}"
+          raise ArgumentError, "Unknown frontend framework: #{frontend_framework}"
         end
       end
 

data/lib/inertia_rails/generators/helper.rb

@@ -27,6 +27,8 @@ module InertiaRails
         end
 
         def guess_inertia_template(package_json_path = DEFAULT_PACKAGE_PATH)
+          return 'inertia_templates' unless package_json_path.exist?
+
           if package_json_path.read.include?('"tailwindcss"')
             'inertia_tw_templates'
           else
@@ -35,8 +37,9 @@ module InertiaRails
         end
       end
 
+      # Matches controller_path, which the default component path resolver expects.
       def inertia_base_path
-        (class_path + [file_name.pluralize]).join('/')
+        (class_path + [file_name]).join('/')
       end
 
       def inertia_component_name

data/lib/inertia_rails/generators/scaffold_template_base.rb

@@ -14,21 +14,26 @@ module InertiaRails
 
       def copy_view_files
         available_views.each do |view|
-          template "#{options.frontend_framework}/#{view}.#{template_extension}",
+          template "#{frontend_framework}/#{view}.#{template_extension}",
                    File.join(base_path, "#{view}.#{extension}")
         end
 
-        template "#{options.frontend_framework}/#{partial_name}.#{template_extension}",
+        template "#{frontend_framework}/#{partial_name}.#{template_extension}",
                  File.join(base_path, "#{singular_name}.#{extension}")
 
-        template "#{options.frontend_framework}/types.ts", File.join(base_path, 'types.ts') if typescript?
+        template "#{frontend_framework}/types.ts", File.join(base_path, 'types.ts') if typescript?
       end
 
       private
 
+      # Scaffold controllers are pluralized, so the views live under the pluralized path.
+      def inertia_base_path
+        (controller_class_path + [controller_file_name]).join('/')
+      end
+
       def template_extension
         return extension unless typescript?
-        return 'tsx' if options.frontend_framework == 'react'
+        return 'tsx' if frontend_framework == 'react'
 
         "ts.#{extension}"
       end

data/lib/inertia_rails/helper.rb

@@ -36,8 +36,14 @@ module InertiaRails
       id ||= config.root_dom_id
 
       if config.use_script_element_for_initial_page
+        script_options = { 'data-page': id, type: 'application/json' }
+        if respond_to?(:content_security_policy_nonce, true)
+          nonce = content_security_policy_nonce
+          script_options[:nonce] = nonce if nonce.present?
+        end
+
         safe_join([
-                    tag.script(page.to_json.html_safe, 'data-page': id, type: 'application/json'),
+                    tag.script(page.to_json.html_safe, **script_options),
                     tag.div(id: id)
                   ], "\n")
       else

data/lib/inertia_rails/middleware.rb

@@ -51,7 +51,15 @@ module InertiaRails
         inertia_request? && version_stale?
       end
 
+      # Matches Rack::Response::Helpers#redirect? — Inertia session options
+      # must survive every redirect until a render consumes them.
       def redirect_status?(status)
+        [301, 302, 303, 307, 308].include? status
+      end
+
+      # Only 301/302 are rewritten to 303: a 303 already forces a GET on
+      # follow, and 307/308 preserve the request method by design.
+      def convertible_redirect_status?(status)
         [301, 302].include? status
       end
 
@@ -60,7 +68,7 @@ module InertiaRails
       end
 
       def inertia_non_post_redirect?(status)
-        inertia_request? && redirect_status?(status) && non_get_redirectable_method?
+        inertia_request? && convertible_redirect_status?(status) && non_get_redirectable_method?
       end
 
       def stale_inertia_get?

data/lib/inertia_rails/props_resolver.rb

@@ -24,6 +24,7 @@ module InertiaRails
       @_match_on = []
       @_once = {}
       @_scroll = {}
+      @_rescued = []
 
       props = expand_dot_notation(@props)
       resolved = deep_transform_props(props)
@@ -71,6 +72,7 @@ module InertiaRails
       metadata[:deepMergeProps] = @_deep_merge unless @_deep_merge.empty?
       metadata[:matchPropsOn] = @_match_on unless @_match_on.empty?
       metadata[:onceProps] = @_once unless @_once.empty?
+      metadata[:rescuedProps] = @_rescued unless @_rescued.empty?
 
       metadata
     end
@@ -99,29 +101,39 @@ module InertiaRails
         collect_metadata(prop, path)
         next unless keep_prop?(prop, path, parent_was_resolved: parent_was_resolved)
 
-        value = @evaluator.call(prop)
+        rescue_enabled = prop.try(:rescue?)
 
-        # A closure may return a prop type — unwrap one level
-        if value.is_a?(BaseProp) && !prop.is_a?(BaseProp)
-          collect_metadata(value, path)
-          next unless keep_prop?(value, path, parent_was_resolved: parent_was_resolved)
+        begin
+          value = @evaluator.call(prop)
 
-          value = @evaluator.call(value)
-        end
+          # A closure may return a prop type — unwrap one level
+          if value.is_a?(BaseProp) && !prop.is_a?(BaseProp)
+            collect_metadata(value, path)
+            next unless keep_prop?(value, path, parent_was_resolved: parent_was_resolved)
 
-        # A closure may return a Hash or Array containing prop types — recurse into it
-        if prop.is_a?(Proc)
-          if value.is_a?(Hash) && value.any?
-            nested = deep_transform_props(value, path, parent_was_resolved: true)
-            transformed_props[key] = nested unless nested.empty?
-            next
-          elsif value.is_a?(Array)
-            transformed_props[key] = transform_array(value, path, parent_was_resolved: true)
-            next
+            value = @evaluator.call(value)
           end
-        end
 
-        transformed_props[key] = value
+          # A closure may return a Hash or Array containing prop types — recurse into it
+          if prop.is_a?(Proc)
+            if value.is_a?(Hash) && value.any?
+              nested = deep_transform_props(value, path, parent_was_resolved: true)
+              transformed_props[key] = nested unless nested.empty?
+              next
+            elsif value.is_a?(Array)
+              transformed_props[key] = transform_array(value, path, parent_was_resolved: true)
+              next
+            end
+          end
+
+          transformed_props[key] = rescue_enabled ? value.as_json : value
+        rescue StandardError => e
+          raise unless rescue_enabled
+
+          report_rescued_error(e)
+          @_rescued << path
+          next
+        end
       end
     end
 
@@ -147,6 +159,16 @@ module InertiaRails
       end
     end
 
+    def report_rescued_error(error)
+      # `Rails.error` (the Error Reporter) was introduced in Rails 7.0. Fall back
+      # to the logger on older versions so rescued errors are never silently lost.
+      if Rails.respond_to?(:error)
+        Rails.error.report(error, handled: true)
+      else
+        Rails.logger&.error("[inertia-rails] Rescued deferred prop error: #{error.class}: #{error.message}")
+      end
+    end
+
     def collect_metadata(prop, path)
       return unless prop.is_a?(BaseProp)
 

data/lib/inertia_rails/renderer.rb

@@ -44,11 +44,9 @@ module InertiaRails
     end
 
     def render
-      @response.headers['Vary'] = if @response.headers['Vary'].blank?
-                                    'X-Inertia'
-                                  else
-                                    "#{@response.headers['Vary']}, X-Inertia"
-                                  end
+      vary = @response.headers['Vary'].to_s.split(',').map(&:strip).reject(&:empty?)
+      vary << 'X-Inertia' if vary.none? { |value| value.casecmp?('X-Inertia') }
+      @response.headers['Vary'] = vary.join(', ')
       if @request.inertia?
         @response.set_header('X-Inertia', 'true')
         @render_method.call json: page.to_json, status: @response.status, content_type: Mime[:json]

data/lib/inertia_rails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module InertiaRails
-  VERSION = '3.21.1'
+  VERSION = '3.22.0'
 end

data/lib/inertia_rails/xsrf_cookie_refresh_policy.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module InertiaRails
+  # Decides whether the XSRF-TOKEN cookie rewrite can be skipped under the `:lazy` refresh policy.
+  class XsrfCookieRefreshPolicy
+    def self.skip?(controller)
+      new(controller).skip?
+    end
+
+    def initialize(controller)
+      @controller = controller
+      @request = controller.request
+    end
+
+    def skip?
+      return false unless configuration.xsrf_cookie_refresh == :lazy
+      return false unless @request.get? || @request.head?
+
+      cookie = @request.cookies['XSRF-TOKEN']
+      return false if cookie.blank?
+
+      return true unless can_validate_without_loading_session?
+
+      valid_for_session?(cookie)
+    end
+
+    private
+
+    def configuration
+      @controller.send(:inertia_configuration)
+    end
+
+    def can_validate_without_loading_session?
+      csrf_token_loaded_in_env? ||
+        (@request.session.respond_to?(:loaded?) && @request.session.loaded?)
+    end
+
+    def valid_for_session?(cookie)
+      csrf_token_was_loaded = csrf_token_loaded_in_env?
+      @controller.send(:valid_authenticity_token?, @request.session, cookie)
+    ensure
+      # `valid_authenticity_token?` memoizes the real token into
+      # `request.env[CSRF_TOKEN]` (Rails 7.1+), and the session middleware later
+      # persists whatever sits there via `commit_csrf_token`. Drop the key when
+      # validation itself created it, so a validation-only read can't dirty the
+      # session and emit a session Set-Cookie. No-op on Rails < 7.1, where
+      # there is no env key to clean up.
+      @request.env.delete(csrf_token_env_key) if csrf_token_env_key && !csrf_token_was_loaded
+    end
+
+    def csrf_token_loaded_in_env?
+      csrf_token_env_key && @request.env.key?(csrf_token_env_key)
+    end
+
+    def csrf_token_env_key
+      return @csrf_token_env_key if defined?(@csrf_token_env_key)
+
+      @csrf_token_env_key =
+        if ActionController::RequestForgeryProtection.const_defined?(:CSRF_TOKEN, false)
+          ActionController::RequestForgeryProtection.const_get(:CSRF_TOKEN)
+        end
+    end
+  end
+end

data/lib/inertia_rails.rb

@@ -43,6 +43,7 @@ require_relative 'inertia_rails/renderer'
 require_relative 'inertia_rails/flash_extension'
 require_relative 'inertia_rails/helper'
 require_relative 'inertia_rails/precognition'
+require_relative 'inertia_rails/xsrf_cookie_refresh_policy'
 require_relative 'inertia_rails/controller'
 require_relative 'inertia_rails/middleware'
 require_relative 'inertia_rails/engine'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inertia_rails
 version: !ruby/object:Gem::Version
-  version: 3.21.1
+  version: 3.22.0
 platform: ruby
 authors:
 - Brian Knoles
@@ -225,6 +225,7 @@ files:
 - lib/inertia_rails/ssr_renderer.rb
 - lib/inertia_rails/testing.rb
 - lib/inertia_rails/version.rb
+- lib/inertia_rails/xsrf_cookie_refresh_policy.rb
 - lib/puma/plugin/inertia_ssr.rb
 - lib/tasks/inertia_rails.rake
 homepage: https://github.com/inertiajs/inertia-rails