inertia_rails 3.21.2 → 3.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 190a5d8589ff4eed036766ab20f769f4bb330e09e3097a6682a30c9a8121ceef
-  data.tar.gz: 54f4aac04e72db5de364d525851a68de80590aed5ae1220055871d10cbb3ef05
+  metadata.gz: 4e9384ee4e756ec30efcbb0afa77c7d557d02dd4d5dc60f1dc6239ec1d0b1878
+  data.tar.gz: 98e207f798ae91e888f1de274caa506bbc289ac51ea2e20e2eb5465f818575fd
 SHA512:
-  metadata.gz: 9c1f35a30b2357eb934fdf33d4f6d51067d0771de5d1081093be4e9858bc9022bde74b799b40d18a3b59e09ca9d8811b4c8fbb91d0062b4a9280b40ab9bca7c5
-  data.tar.gz: a47aec16b0e2502305cfa41c48941586036bd322cc74c84f3f6cfb783aeb7b97835bc810f6e35ef1b70c40554a945e05979123cf710819eec50aa6ea2978c8ea
+  metadata.gz: 6d9dd387eb80c39743d7d48268ef7540710a27194c52f165e4f75565fd4e76cc151db286b64b5e050fa387027b80a0eb3b37210908068a826cfedfe6003aea67
+  data.tar.gz: 3309e07158894db2e60b03c15e0f46b8d056e09821487412709b738a5ceeb2508c54d5df7421ad77ee04e30a2592e8a07a48de720192446ad5290e18c423eb47

data/CHANGELOG.md

@@ -6,6 +6,19 @@ 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)

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'], dev: true)
+        # 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'
 

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/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/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/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.2'
+  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.2
+  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