inertia_rails 3.20.0 → 3.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e56b13d7d02abe1f35709de08b6873cc0d407215a97891502bb4ee7439e0d005
-  data.tar.gz: a627501dd94ab5d9ad747c2decce31ab47fe4870e677d2197395680cb4dfaa3e
+  metadata.gz: 8e115fc23929dd31823522f220656a19369a8f5532215bf2c36a2f01e038ca20
+  data.tar.gz: 81bf7c11c9fb32be96de1d70e212894057bbb16c49ce87c76ea17071fe9635e5
 SHA512:
-  metadata.gz: 5f9b35e5039a9516daaa7ff6d9c1b702011d3ddd2161fb40922143fde7951522ca3e8268691d2b3490baae217febb046b04d07d677facf39b81dad9f1f5bd076
-  data.tar.gz: 3523dadfe1c2877767cf534b4a6c95ef979250bbf3c78a86af31e6220247cb860d020402b359a32c8b5295b1d246aa30d8a5a590dd8fae44de89623b24521880
+  metadata.gz: 80d695972717a9ad929c580bffb339102b19cb0890b1f235d3b2076b0b8094d7d8f5ce67de1d9b18ebe440dc03982be37371d522d7168fb8be447fa3e7b15fe0
+  data.tar.gz: dac3f813eecdc130f9b2081f084122c9783cb3d74793847c8f2ca1f9c95d080159594ccf1e015f05c4b1848faccd53fa069c4f97694614fb5ea96ac7b54765b2

data/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [3.21.0] - 2026-04-14
+
+* Skip excluded hash props on partial reloads (@erickreutz)
+* Fix Vite plugin insertion order in install generator (@onk)
+* Fix typo in `inertia()` plugin configuration example in docs (@onk)
+* Better SSR Puma plugin lookup defaults (@skryukov)
+* Add prop-level caching and caching documentation (@skryukov)
+* Skip session cleanup in middleware when session was never loaded (@khamusa)
+* Support `layout` option in `render inertia:` calls (@skryukov)
+
 ## [3.20.0] - 2026-04-04
 
 * Fix partial reload filtering with arrays

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

@@ -87,18 +87,21 @@ module Inertia
         say 'Installing Inertia npm packages'
         add_dependencies(inertia_package, *FRAMEWORKS[framework]['packages'])
 
-        unless File.read(vite_config_path).include?(FRAMEWORKS[framework]['vite_plugin_import'])
-          say "Adding Vite plugin for #{framework}"
-          insert_into_file vite_config_path, "\n    #{FRAMEWORKS[framework]['vite_plugin_call']},", after: 'plugins: ['
-          prepend_file vite_config_path, "#{FRAMEWORKS[framework]['vite_plugin_import']}\n"
-        end
-
         unless File.read(vite_config_path).include?('@inertiajs/vite')
           say 'Adding Inertia Vite plugin'
-          insert_into_file vite_config_path, "\n    inertia(),", after: 'plugins: ['
+          # Append to the end of the plugins array.
+          gsub_file vite_config_path, /(plugins: \[.*?)(\n\s*\])/m, "\\1\n    inertia(),\\2"
           prepend_file vite_config_path, "import inertia from '@inertiajs/vite'\n"
         end
 
+        unless File.read(vite_config_path).include?(FRAMEWORKS[framework]['vite_plugin_import'])
+          say "Adding Vite plugin for #{framework}"
+          # Append to the end of the plugins array.
+          gsub_file vite_config_path, /(plugins: \[.*?)(\n\s*\])/m,
+                    "\\1\n    #{FRAMEWORKS[framework]['vite_plugin_call']},\\2"
+          prepend_file vite_config_path, "#{FRAMEWORKS[framework]['vite_plugin_import']}\n"
+        end
+
         say "Copying #{inertia_entrypoint} entrypoint"
         copy_file "#{framework}/#{inertia_entrypoint}", js_file_path("entrypoints/#{inertia_entrypoint}")
 

data/lib/inertia_rails/cached_prop.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module InertiaRails
+  class CachedProp < BaseProp
+    include PropCacheable
+
+    def initialize(key, **options, &block)
+      super(cache: options.merge!(key: key), &block)
+    end
+  end
+end

data/lib/inertia_rails/configuration.rb

@@ -71,6 +71,10 @@ module InertiaRails
 
       # Whether to include shared prop keys in the page response metadata.
       expose_shared_prop_keys: true,
+
+      # Cache store for prop-level caching and SSR response caching.
+      # Defaults to Rails.cache when nil.
+      cache_store: nil,
     }.freeze
 
     OPTION_NAMES = DEFAULTS.keys.freeze
@@ -141,6 +145,10 @@ module InertiaRails
       @options[:on_ssr_error]
     end
 
+    def cache_store
+      @options[:cache_store] || Rails.cache
+    end
+
     OPTION_NAMES.each do |option|
       unless method_defined?(option)
         define_method(option) do

data/lib/inertia_rails/controller.rb

@@ -112,6 +112,14 @@ module InertiaRails
       view_assigns.except(*@_inertia_skip_props)
     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.
+    def _normalize_options(options)
+      options[:_inertia_layout] = options[:layout] if options.key?(:inertia) && options.key?(:layout)
+      super
+    end
+
     def inertia_configuration
       self.class._inertia_configuration.bind_controller(self)
     end

data/lib/inertia_rails/defer_prop.rb

@@ -4,6 +4,7 @@ module InertiaRails
   class DeferProp < IgnoreOnFirstLoadProp
     prepend PropOnceable
     prepend PropMergeable
+    prepend PropCacheable
 
     DEFAULT_GROUP = 'default'
 

data/lib/inertia_rails/engine.rb

@@ -15,6 +15,14 @@ module InertiaRails
     initializer 'inertia_rails.renderer' do
       ActiveSupport.on_load(:action_controller) do
         ActionController::Renderers.add :inertia do |component, options|
+          # See Controller#_normalize_options — restore the user's original
+          # :layout or discard the Rails-injected default.
+          if options.key?(:_inertia_layout)
+            options[:layout] = options.delete(:_inertia_layout)
+          else
+            options.delete(:layout)
+          end
+
           InertiaRails::Renderer.new(
             component,
             self,

data/lib/inertia_rails/middleware.rb

@@ -26,7 +26,11 @@ module InertiaRails
         request = ActionDispatch::Request.new(@env)
 
         # Inertia session data is added via redirect_to
-        unless keep_inertia_session_options?(status)
+        # Guard with session.loaded? to avoid forcing session I/O (and unnecessary
+        # database writes) on requests that never accessed the session, e.g. sessionless
+        # controllers. If the session was never loaded the Inertia keys cannot have been
+        # set, so the cleanup would be a no-op anyway.
+        unless keep_inertia_session_options?(status) || !request.session.loaded?
           request.session.delete(:inertia_errors)
           request.session.delete(:inertia_clear_history)
           request.session.delete(:inertia_preserve_fragment)

data/lib/inertia_rails/optional_prop.rb

@@ -3,5 +3,6 @@
 module InertiaRails
   class OptionalProp < IgnoreOnFirstLoadProp
     prepend PropOnceable
+    prepend PropCacheable
   end
 end

data/lib/inertia_rails/prop_cacheable.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module InertiaRails
+  module PropCacheable
+    def initialize(**props, &block)
+      cache_arg = props.delete(:cache)
+
+      if cache_arg.is_a?(Hash)
+        raise ArgumentError, 'cache: hash requires a :key' unless cache_arg.key?(:key)
+
+        @cache_key = derive_cache_key(cache_arg.delete(:key))
+        @cache_options = cache_arg.freeze
+      elsif cache_arg
+        @cache_key = derive_cache_key(cache_arg)
+        @cache_options = nil
+      end
+
+      super
+    end
+
+    def cached?
+      !@cache_key.nil?
+    end
+
+    def call(controller, **context)
+      return super unless cached?
+
+      json = InertiaRails.cache_store.fetch(@cache_key, **(@cache_options || {})) { super.to_json }
+      RawJson.new(json)
+    end
+
+    private
+
+    def derive_cache_key(raw_key)
+      expanded = ActiveSupport::Cache.expand_cache_key(raw_key)
+      "inertia_rails/#{expanded}"
+    end
+  end
+end

data/lib/inertia_rails/props_resolver.rb

@@ -82,6 +82,8 @@ module InertiaRails
         prop = prop.to_inertia if prop.respond_to?(:to_inertia)
 
         if prop.is_a?(Hash) && prop.any?
+          next if !parent_was_resolved && excluded_by_partial_request?(path)
+
           nested = deep_transform_props(prop, path, parent_was_resolved: parent_was_resolved)
           transformed_props[key] = nested unless nested.empty?
           next

data/lib/inertia_rails/raw_json.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module InertiaRails
+  # Wraps a pre-serialized JSON string so it embeds directly
+  # into a larger JSON structure without re-serialization.
+  #
+  # - JSON.generate calls #to_json, embedding the raw string.
+  # - ActiveSupport::JSON.encode calls #as_json first, which
+  #   returns parsed Ruby data that the encoder re-serializes.
+  class RawJson
+    def initialize(json_string)
+      @json_string = json_string
+    end
+
+    def to_json(*)
+      @json_string
+    end
+
+    def as_json(*)
+      JSON.parse(@json_string)
+    end
+  end
+end

data/lib/inertia_rails/renderer.rb

@@ -27,6 +27,7 @@ module InertiaRails
       @encrypt_history = options.fetch(:encrypt_history, @configuration.encrypt_history)
       @clear_history = options.fetch(:clear_history, controller.session[:inertia_clear_history] || false)
       @preserve_fragment = options.fetch(:preserve_fragment, controller.session[:inertia_preserve_fragment] || false)
+      @layout_override = options.fetch(:layout) { @configuration.layout }
       @ssr_cache = options[:ssr_cache]
 
       deep_merge = options.fetch(:deep_merge, @configuration.deep_merge_shared_data)
@@ -70,7 +71,7 @@ module InertiaRails
     end
 
     def layout
-      layout = @configuration.layout
+      layout = @layout_override
       layout.nil? || layout
     end
 

data/lib/inertia_rails/ssr_renderer.rb

@@ -12,7 +12,7 @@ module InertiaRails
       return unless bundle_exists?
 
       if (cache_options = cache_options_hash)
-        Rails.cache.fetch(cache_key, **cache_options) { request }
+        InertiaRails.cache_store.fetch(cache_key, **cache_options) { request }
       else
         request
       end

data/lib/inertia_rails/version.rb

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

data/lib/inertia_rails.rb

@@ -12,6 +12,8 @@ require_relative 'inertia_rails/current'
 require_relative 'inertia_rails/errors'
 
 # props
+require_relative 'inertia_rails/raw_json'
+require_relative 'inertia_rails/prop_cacheable'
 require_relative 'inertia_rails/prop_onceable'
 require_relative 'inertia_rails/prop_mergeable'
 require_relative 'inertia_rails/base_prop'
@@ -19,6 +21,7 @@ require_relative 'inertia_rails/ignore_on_first_load_prop'
 require_relative 'inertia_rails/always_prop'
 require_relative 'inertia_rails/lazy_prop'
 require_relative 'inertia_rails/optional_prop'
+require_relative 'inertia_rails/cached_prop'
 require_relative 'inertia_rails/defer_prop'
 require_relative 'inertia_rails/merge_prop'
 require_relative 'inertia_rails/once_prop'
@@ -54,6 +57,10 @@ module InertiaRails
       @configuration ||= Configuration.default
     end
 
+    def cache_store
+      configuration.cache_store
+    end
+
     def deprecator # :nodoc:
       @deprecator ||= ActiveSupport::Deprecation.new
     end
@@ -82,6 +89,10 @@ module InertiaRails
       MergeProp.new(deep_merge: true, match_on: match_on, &block)
     end
 
+    def cache(...)
+      CachedProp.new(...)
+    end
+
     def defer(...)
       DeferProp.new(...)
     end

data/lib/puma/plugin/inertia_ssr.rb

@@ -138,14 +138,17 @@ Puma::Plugin.create do
 
     return Array(config.ssr_bundle).find { |path| File.exist?(path) } if config.ssr_bundle
 
-    if defined?(ViteRuby)
-      ssr_dir = ViteRuby.config.ssr_output_dir
-      candidates = Dir.glob(File.join(ssr_dir, 'inertia.*')) if ssr_dir
-      return candidates.first if candidates&.any?
+    patterns = %w[ssr/*.js public/assets-ssr/*.js]
+    if defined?(ViteRuby) && (ssr_dir = ViteRuby.config.ssr_output_dir)
+      patterns.prepend(File.join(ssr_dir, '*.js'))
     end
 
-    path = 'public/assets-ssr/inertia.js'
-    path if File.exist?(path)
+    patterns.each do |pattern|
+      candidates = Dir.glob(pattern)
+      return candidates.first if candidates.any?
+    end
+
+    nil
   end
 
   def resolve_base_url

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inertia_rails
 version: !ruby/object:Gem::Version
-  version: 3.20.0
+  version: 3.21.0
 platform: ruby
 authors:
 - Brian Knoles
@@ -184,6 +184,7 @@ files:
 - lib/inertia_rails.rb
 - lib/inertia_rails/always_prop.rb
 - lib/inertia_rails/base_prop.rb
+- lib/inertia_rails/cached_prop.rb
 - lib/inertia_rails/configuration.rb
 - lib/inertia_rails/controller.rb
 - lib/inertia_rails/current.rb
@@ -209,10 +210,12 @@ files:
 - lib/inertia_rails/once_prop.rb
 - lib/inertia_rails/optional_prop.rb
 - lib/inertia_rails/precognition.rb
+- lib/inertia_rails/prop_cacheable.rb
 - lib/inertia_rails/prop_evaluator.rb
 - lib/inertia_rails/prop_mergeable.rb
 - lib/inertia_rails/prop_onceable.rb
 - lib/inertia_rails/props_resolver.rb
+- lib/inertia_rails/raw_json.rb
 - lib/inertia_rails/renderer.rb
 - lib/inertia_rails/rspec.rb
 - lib/inertia_rails/rspec/deprecated.rb