inertia_rails 3.14.0 → 3.16.0

data/lib/generators/inertia_tw_templates/scaffold/templates/svelte/index.ts.svelte.tt

@@ -1,11 +1,10 @@
 <script lang="ts">
-  import { Link } from '@inertiajs/svelte'
+  import { Link, page } from '@inertiajs/svelte'
   import <%= inertia_component_name %> from './<%= singular_name %>.svelte'
   import type { <%= inertia_model_type %> } from './types'
 
-  let { <%= plural_table_name %>, flash } = $props<{
+  let { <%= plural_table_name %> } = $props<{
     <%= plural_table_name %>: <%= inertia_model_type %>[]
-    flash: { notice?: string }
   }>()
 </script>
 
@@ -14,9 +13,9 @@
 </svelte:head>
 
 <div class="mx-auto md:w-2/3 w-full px-8 pt-8">
-  {#if flash.notice}
+  {#if $page.flash.notice}
     <p class="py-2 px-3 bg-green-50 mb-5 text-green-500 font-medium rounded-lg inline-block">
-      {flash.notice}
+      {$page.flash.notice}
     </p>
   {/if}
 

data/lib/generators/inertia_tw_templates/scaffold/templates/svelte/show.svelte.tt

@@ -1,8 +1,8 @@
 <script>
-  import { Link } from '@inertiajs/svelte'
+  import { Link, page } from '@inertiajs/svelte'
   import <%= inertia_component_name %> from './<%= singular_name %>.svelte'
 
-  let { <%= singular_table_name %>, flash } = $props()
+  let { <%= singular_table_name %> } = $props()
 </script>
 
 <svelte:head>
@@ -11,9 +11,9 @@
 
 <div class="mx-auto md:w-2/3 w-full px-8 pt-8">
   <div class="mx-auto">
-    {#if flash.notice}
+    {#if $page.flash.notice}
       <p class="py-2 px-3 bg-green-50 mb-5 text-green-500 font-medium rounded-lg inline-block">
-        {flash.notice}
+        {$page.flash.notice}
       </p>
     {/if}
 

data/lib/generators/inertia_tw_templates/scaffold/templates/svelte/show.ts.svelte.tt

@@ -1,11 +1,10 @@
 <script lang="ts">
-  import { Link } from '@inertiajs/svelte'
+  import { Link, page } from '@inertiajs/svelte'
   import <%= inertia_component_name %> from './<%= singular_name %>.svelte'
   import type { <%= inertia_model_type %> } from './types'
 
-  let { <%= singular_table_name %>, flash } = $props<{
+  let { <%= singular_table_name %> } = $props<{
     <%= singular_table_name %>: <%= inertia_model_type %>
-    flash: { notice?: string }
   }>()
 </script>
 
@@ -15,9 +14,9 @@
 
 <div class="mx-auto md:w-2/3 w-full px-8 pt-8">
   <div class="mx-auto">
-    {#if flash.notice}
+    {#if $page.flash.notice}
       <p class="py-2 px-3 bg-green-50 mb-5 text-green-500 font-medium rounded-lg inline-block">
-        {flash.notice}
+        {$page.flash.notice}
       </p>
     {/if}
 

data/lib/generators/inertia_tw_templates/scaffold/templates/vue/index.ts.vue.tt

@@ -36,12 +36,12 @@
 </template>
 
 <script setup lang="ts">
-import { Head, Link } from '@inertiajs/vue3'
+import { Head, Link, usePage } from '@inertiajs/vue3'
 import <%= inertia_component_name %> from './<%= singular_name %>.vue'
 import { <%= inertia_model_type %> } from './types'
 
-const { <%= plural_table_name %>, flash } = defineProps<{
+defineProps<{
   <%= plural_table_name %>: <%= inertia_model_type %>[]
-  flash: { notice?: string }
 }>()
+const { flash } = usePage()
 </script>

data/lib/generators/inertia_tw_templates/scaffold/templates/vue/index.vue.tt

@@ -36,8 +36,9 @@
 </template>
 
 <script setup>
-import { Head, Link } from '@inertiajs/vue3'
+import { Head, Link, usePage } from '@inertiajs/vue3'
 import <%= inertia_component_name %> from './<%= singular_name %>.vue'
 
-const { <%= plural_table_name %>, flash } = defineProps(['<%= plural_table_name %>', 'flash'])
+defineProps(['<%= plural_table_name %>'])
+const { flash } = usePage()
 </script>

data/lib/generators/inertia_tw_templates/scaffold/templates/vue/show.ts.vue.tt

@@ -42,12 +42,12 @@
 </template>
 
 <script setup lang="ts">
-import { Head, Link } from '@inertiajs/vue3'
+import { Head, Link, usePage } from '@inertiajs/vue3'
 import <%= inertia_component_name %> from './<%= singular_name %>.vue'
 import { <%= inertia_model_type %> } from './types'
 
-const { <%= singular_table_name %>, flash } = defineProps<{
+defineProps<{
   <%= singular_table_name %>: <%= inertia_model_type %>
-  flash: { notice?: string }
 }>()
+const { flash } = usePage()
 </script>

data/lib/generators/inertia_tw_templates/scaffold/templates/vue/show.vue.tt

@@ -42,8 +42,9 @@
 </template>
 
 <script setup>
-import { Head, Link } from '@inertiajs/vue3'
+import { Head, Link, usePage } from '@inertiajs/vue3'
 import <%= inertia_component_name %> from './<%= singular_name %>.vue'
 
-const { <%= singular_table_name %>, flash } = defineProps(['<%= singular_table_name %>', 'flash'])
+defineProps(['<%= singular_table_name %>'])
+const { flash } = usePage()
 </script>

data/lib/inertia_rails/base_prop.rb

@@ -3,7 +3,7 @@
 module InertiaRails
   # Base class for all props.
   class BaseProp
-    def initialize(&block)
+    def initialize(**, &block)
       @block = block
     end
 

data/lib/inertia_rails/configuration.rb

@@ -34,6 +34,16 @@ module InertiaRails
 
       # Whether to include empty `errors` hash to the props when no errors are present.
       always_include_errors_hash: nil,
+
+      # Whether to use `<script>` element for initial page rendering instead of the `data-page` attribute.
+      use_script_element_for_initial_page: false,
+
+      # DOM id to use for the root Inertia.js element.
+      root_dom_id: 'app',
+
+      # Flash keys from Rails flash to expose to frontend.
+      # Set to nil to disable Rails flash integration (use only flash.inertia).
+      flash_keys: %i[notice alert].freeze,
     }.freeze
 
     OPTION_NAMES = DEFAULTS.keys.freeze

data/lib/inertia_rails/controller.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'inertia_rails'
+require_relative 'flash_extension'
 require_relative 'helper'
 require_relative 'action_filter'
 require_relative 'meta_tag_builder'
@@ -180,6 +181,17 @@ module InertiaRails
       head :conflict
     end
 
+    def inertia_collect_flash_data
+      flash_data = flash.to_hash
+
+      allowed_keys = inertia_configuration.flash_keys
+      result = allowed_keys ? flash_data.slice(*allowed_keys.map(&:to_s)) : {}
+
+      result.merge!(flash_data['inertia'].transform_keys(&:to_s)) if flash_data['inertia'].is_a?(Hash)
+
+      result.symbolize_keys
+    end
+
     def capture_inertia_session_options(options)
       return unless (inertia = options[:inertia])
 
@@ -192,7 +204,6 @@ module InertiaRails
           )
           session[:inertia_errors] = inertia_errors
         end
-
       end
 
       session[:inertia_clear_history] = inertia[:clear_history] if inertia[:clear_history]

data/lib/inertia_rails/defer_prop.rb

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

data/lib/inertia_rails/engine.rb

@@ -2,6 +2,7 @@
 
 require_relative 'middleware'
 require_relative 'controller'
+require_relative 'flash_extension'
 
 module InertiaRails
   class Engine < ::Rails::Engine
@@ -14,5 +15,10 @@ module InertiaRails
         include ::InertiaRails::Controller
       end
     end
+
+    initializer 'inertia_rails.flash_extension' do
+      ActionDispatch::Flash::FlashHash.prepend ::InertiaRails::FlashExtension
+      ActionDispatch::Flash::FlashNow.prepend ::InertiaRails::FlashExtension
+    end
   end
 end

data/lib/inertia_rails/flash_extension.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module InertiaRails
+  # Provides a scoped interface for Inertia flash data within Rails' flash.
+  # Uses native hash storage: flash[:inertia] = { key: value }
+  # Tracks .now keys separately in @inertia_now_keys for session filtering.
+  module FlashExtension
+    INERTIA_KEY = 'inertia'
+
+    def inertia
+      @inertia ||= InertiaFlashScope.new(self)
+    end
+
+    # Keys set via flash.now.inertia that should not persist to session
+    def inertia_now_keys
+      @inertia_now_keys ||= Set.new
+    end
+
+    # Clear .now tracking when user explicitly keeps :inertia or all flash
+    def keep(key = nil)
+      @inertia_now_keys&.clear if key.nil? || key.to_s == INERTIA_KEY
+      super
+    end
+
+    # Override to filter .now keys from nested inertia hash before session persistence
+    def to_session_value
+      inertia_hash = self[INERTIA_KEY]
+      if inertia_hash.is_a?(Hash) && @inertia_now_keys&.any?
+        @inertia_now_keys.each { |k| inertia_hash.delete(k.to_s) }
+        delete(INERTIA_KEY) if inertia_hash.empty?
+      end
+
+      super
+    end
+
+    class InertiaFlashScope
+      def initialize(flash_or_now)
+        if flash_or_now.respond_to?(:flash)
+          @flash = flash_or_now.flash
+          @now = true
+        else
+          @flash = flash_or_now
+          @now = false
+        end
+      end
+
+      def []=(key, value)
+        @flash[INERTIA_KEY] ||= {}
+        @flash[INERTIA_KEY][key.to_s] = value
+        @flash.inertia_now_keys.add(key.to_s) if @now
+      end
+
+      def [](key)
+        @flash[INERTIA_KEY]&.[](key.to_s)
+      end
+
+      def to_hash
+        @flash[INERTIA_KEY]&.dup || {}
+      end
+      alias to_h to_hash
+    end
+  end
+end

data/lib/inertia_rails/generators/helper.rb

@@ -87,14 +87,6 @@ module InertiaRails
         route_url
       end
 
-      def inertia_js_version
-        @inertia_js_version ||= Gem::Version.new(
-          JSON.parse(`npm ls @inertiajs/core --json`).then do |json|
-            json['dependencies'].values.first['version']
-          end
-        )
-      end
-
       def ts_type(attribute)
         case attribute.type
         when :float, :decimal, :integer

data/lib/inertia_rails/helper.rb

@@ -32,5 +32,19 @@ module InertiaRails
 
       safe_join(meta_tags, "\n")
     end
+
+    def inertia_root(id: nil, page: inertia_page)
+      config = controller.send(:inertia_configuration)
+      id ||= config.root_dom_id
+
+      if config.use_script_element_for_initial_page
+        safe_join([
+                    tag.script(page.to_json.html_safe, 'data-page': id, type: 'application/json'),
+                    tag.div(id: id)
+                  ], "\n")
+      else
+        tag.div(id: id, 'data-page': page.to_json)
+      end
+    end
   end
 end

data/lib/inertia_rails/inertia_rails.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'inertia_rails/prop_onceable'
 require 'inertia_rails/prop_mergeable'
 require 'inertia_rails/base_prop'
 require 'inertia_rails/ignore_on_first_load_prop'
@@ -8,6 +9,7 @@ require 'inertia_rails/lazy_prop'
 require 'inertia_rails/optional_prop'
 require 'inertia_rails/defer_prop'
 require 'inertia_rails/merge_prop'
+require 'inertia_rails/once_prop'
 require 'inertia_rails/scroll_prop'
 require 'inertia_rails/configuration'
 require 'inertia_rails/meta_tag'
@@ -28,14 +30,18 @@ module InertiaRails
       LazyProp.new(value, &block)
     end
 
-    def optional(&block)
-      OptionalProp.new(&block)
+    def optional(...)
+      OptionalProp.new(...)
     end
 
     def always(&block)
       AlwaysProp.new(&block)
     end
 
+    def once(...)
+      OnceProp.new(...)
+    end
+
     def merge(...)
       MergeProp.new(...)
     end
@@ -44,8 +50,8 @@ module InertiaRails
       MergeProp.new(deep_merge: true, match_on: match_on, &block)
     end
 
-    def defer(group: nil, merge: nil, deep_merge: nil, match_on: nil, &block)
-      DeferProp.new(group: group, merge: merge, deep_merge: deep_merge, match_on: match_on, &block)
+    def defer(...)
+      DeferProp.new(...)
     end
 
     def scroll(metadata = nil, **options, &block)

data/lib/inertia_rails/merge_prop.rb

@@ -2,6 +2,7 @@
 
 module InertiaRails
   class MergeProp < BaseProp
+    prepend PropOnceable
     prepend PropMergeable
 
     def initialize(**_props, &block)

data/lib/inertia_rails/middleware.rb

@@ -21,7 +21,7 @@ module InertiaRails
         status, headers, body = @app.call(@env)
         request = ActionDispatch::Request.new(@env)
 
-        # Inertia errors are added to the session via redirect_to
+        # Inertia session data is added via redirect_to
         unless keep_inertia_session_options?(status)
           request.session.delete(:inertia_errors)
           request.session.delete(:inertia_clear_history)

data/lib/inertia_rails/once_prop.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module InertiaRails
+  class OnceProp < BaseProp
+    prepend PropOnceable
+
+    def initialize(**, &block)
+      @once = true
+      super(&block)
+    end
+  end
+end

data/lib/inertia_rails/optional_prop.rb

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

data/lib/inertia_rails/prop_onceable.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module InertiaRails
+  module PropOnceable
+    attr_reader :once_key, :once_expires_in
+
+    def initialize(**props, &block)
+      @once = props.fetch(:once, false)
+      @once_key = props[:key]
+      @once_expires_in = props[:expires_in]
+      @fresh = props.fetch(:fresh, false)
+
+      super
+    end
+
+    def once?
+      @once
+    end
+
+    def fresh?
+      @fresh
+    end
+
+    def expires_at
+      return nil unless @once_expires_in
+
+      timestamp = case @once_expires_in
+                  when ActiveSupport::Duration
+                    (Time.current + @once_expires_in).to_f
+                  when Numeric
+                    Time.current.to_f + @once_expires_in
+                  else
+                    raise ArgumentError, "Invalid `expires_in` value: #{@once_expires_in.inspect}"
+                  end
+
+      (timestamp * 1000).to_i
+    end
+  end
+end

data/lib/inertia_rails/renderer.rb

@@ -48,7 +48,7 @@ module InertiaRails
                                   else
                                     "#{@response.headers['Vary']}, X-Inertia"
                                   end
-      if @request.headers['X-Inertia']
+      if @request.inertia?
         @response.set_header('X-Inertia', 'true')
         @render_method.call json: page.to_json, status: @response.status, content_type: Mime[:json]
       else
@@ -97,15 +97,17 @@ module InertiaRails
     def computed_props
       # rubocop:disable Style/MultilineBlockChain
       @props
-        .tap do |merged_props| # Always keep errors in the props
-          if merged_props.key?(:errors) && !merged_props[:errors].is_a?(BaseProp)
-            errors = merged_props[:errors]
-            merged_props[:errors] = InertiaRails.always { errors }
-          end
+        .tap do |merged_props|
+        # Always keep errors in the props
+        if merged_props.key?(:errors) && !merged_props[:errors].is_a?(BaseProp)
+          errors = merged_props[:errors]
+          merged_props[:errors] = InertiaRails.always { errors }
         end
+      end
         .then { |props| deep_transform_props(props) } # Internal hydration/filtering
         .then { |props| @configuration.prop_transformer(props: props) } # Apply user-defined prop transformer
-        .tap do |props| # Add meta tags last (never transformed)
+        .tap do |props|
+        # Add meta tags last (never transformed)
         props[:_inertia_meta] = meta_tags if meta_tags.present?
       end
       # rubocop:enable Style/MultilineBlockChain
@@ -123,11 +125,17 @@ module InertiaRails
         clearHistory: @clear_history,
       }
 
+      flash_data = @controller.__send__(:inertia_collect_flash_data)
+      @page[:flash] = flash_data if flash_data.present?
+
       deferred_props = deferred_props_keys
       @page[:deferredProps] = deferred_props if deferred_props.present?
       @page[:scrollProps] = scroll_props if scroll_props.present?
       @page.merge!(resolve_merge_props)
 
+      once_props = resolve_once_props
+      @page[:onceProps] = once_props if once_props.present?
+
       @page
     end
 
@@ -173,6 +181,17 @@ module InertiaRails
       }.delete_if { |_, v| v.blank? }
     end
 
+    def resolve_once_props
+      @props.each_with_object({}) do |(key, prop), result|
+        next unless prop.try(:once?)
+        next if excluded_by_partial_request?([key.to_s])
+
+        once_key = (prop.once_key || key).to_s
+
+        result[once_key] = { prop: key.to_s, expiresAt: prop.expires_at }.compact
+      end
+    end
+
     def resolve_match_on_props
       all_merge_props.filter_map do |key, prop|
         prop.match_on.map! { |ms| "#{key}.#{ms}" } if prop.match_on.present?
@@ -251,6 +270,10 @@ module InertiaRails
       @partial_except_keys ||= (@request.headers['X-Inertia-Partial-Except'] || '').split(',').compact_blank!
     end
 
+    def except_once_keys
+      @except_once_keys ||= (@request.headers['X-Inertia-Except-Once-Props'] || '').split(',').compact_blank!
+    end
+
     def rendering_partial_component?
       @request.headers['X-Inertia-Partial-Component'] == @component
     end
@@ -265,12 +288,8 @@ module InertiaRails
 
     def keep_prop?(prop, path)
       return true if prop.is_a?(AlwaysProp)
-
-      if rendering_partial_component? && (partial_keys.present? || partial_except_keys.present?)
-        path_with_prefixes = path_prefixes(path)
-        return false if excluded_by_only_partial_keys?(path_with_prefixes)
-        return false if excluded_by_except_partial_keys?(path_with_prefixes)
-      end
+      return false if excluded_by_once_cache?(prop, path)
+      return false if excluded_by_partial_request?(path)
 
       # Precedence: Evaluate IgnoreOnFirstLoadProp only after partial keys have been checked
       return false if prop.is_a?(IgnoreOnFirstLoadProp) && !rendering_partial_component?
@@ -278,6 +297,29 @@ module InertiaRails
       true
     end
 
+    def excluded_by_once_cache?(prop, path)
+      return false unless prop.try(:once?)
+      return false if prop.try(:fresh?)
+      return false if explicitly_requested?(path)
+
+      once_key = (prop.once_key || path.join('.')).to_s
+      except_once_keys.include?(once_key)
+    end
+
+    def explicitly_requested?(path)
+      return false unless rendering_partial_component? && partial_keys.present?
+
+      path_with_prefixes = path_prefixes(path)
+      (path_with_prefixes & partial_keys).any?
+    end
+
+    def excluded_by_partial_request?(path)
+      return false unless rendering_partial_component? && (partial_keys.present? || partial_except_keys.present?)
+
+      path_with_prefixes = path_prefixes(path)
+      excluded_by_only_partial_keys?(path_with_prefixes) || excluded_by_except_partial_keys?(path_with_prefixes)
+    end
+
     def path_prefixes(parts)
       (0...parts.length).map do |i|
         parts[0..i].join('.')

data/lib/inertia_rails/version.rb

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

data/lib/patches/debug_exceptions.rb

@@ -5,18 +5,22 @@
 # The original source needs to be patched, so that Inertia requests are
 # NOT responded with plain text, but with HTML.
 #
-# Original source (unchanged since Rails 5.1):
-# https://github.com/rails/rails/blob/5-1-stable/actionpack/lib/action_dispatch/middleware/debug_exceptions.rb
+# Original source:
 # https://github.com/rails/rails/blob/8-0-stable/actionpack/lib/action_dispatch/middleware/debug_exceptions.rb
+# https://github.com/rails/rails/blob/main/actionpack/lib/action_dispatch/middleware/debug_exceptions.rb
 #
 
 module InertiaRails
   module InertiaDebugExceptions
-    def render_for_browser_request(request, wrapper)
+    # Rails 8.2+ passes content_type as third argument
+    def render_for_browser_request(request, wrapper, content_type = nil)
       template = create_template(request, wrapper)
       file = "rescues/#{wrapper.rescue_template}"
 
-      if request.xhr? && !request.headers['X-Inertia'] # <<<< this line is changed only
+      if content_type == Mime[:md]
+        body = template.render(template: file, layout: false, formats: [:text])
+        format = 'text/markdown'
+      elsif request.xhr? && !request.headers['X-Inertia']
         body = template.render(template: file, layout: false, formats: [:text])
         format = 'text/plain'
       else

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inertia_rails
 version: !ruby/object:Gem::Version
-  version: 3.14.0
+  version: 3.16.0
 platform: ruby
 authors:
 - Brian Knoles
@@ -9,7 +9,7 @@ authors:
 - Eugene Granovsky
 bindir: bin
 cert_chain: []
-date: 2025-11-27 00:00:00.000000000 Z
+date: 2025-12-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -189,6 +189,7 @@ files:
 - lib/inertia_rails/controller.rb
 - lib/inertia_rails/defer_prop.rb
 - lib/inertia_rails/engine.rb
+- lib/inertia_rails/flash_extension.rb
 - lib/inertia_rails/generators/controller_template_base.rb
 - lib/inertia_rails/generators/helper.rb
 - lib/inertia_rails/generators/scaffold_template_base.rb
@@ -200,8 +201,10 @@ files:
 - lib/inertia_rails/meta_tag.rb
 - lib/inertia_rails/meta_tag_builder.rb
 - lib/inertia_rails/middleware.rb
+- lib/inertia_rails/once_prop.rb
 - lib/inertia_rails/optional_prop.rb
 - lib/inertia_rails/prop_mergeable.rb
+- lib/inertia_rails/prop_onceable.rb
 - lib/inertia_rails/renderer.rb
 - lib/inertia_rails/rspec.rb
 - lib/inertia_rails/scroll_metadata.rb