Class: InertiaRails::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/inertia_rails/configuration.rb

Constant Summary collapse

DEFAULT_SSR_URL = 
'http://localhost:13714'
DEFAULTS = 
{
  # Whether to combine hashes with the same keys instead of replacing them.
  deep_merge_shared_data: false,

  # Overrides Rails default rendering behavior to render using Inertia by default.
  default_render: false,

  # Allows the user to hook into the default rendering behavior and change it to fit their needs
  component_path_resolver: ->(path:, action:) { "#{path}/#{action}" },

  # A function that transforms the props before they are sent to the client.
  prop_transformer: ->(props:) { props },

  # DEPRECATED: Let Rails decide which layout should be used based on the
  # controller configuration.
  layout: true,

  # Whether to encrypt the history state in the client.
  encrypt_history: false,

  # SSR options.
  ssr_enabled: false,
  # URL of the SSR server. When nil, defaults to DEFAULT_SSR_URL.
  ssr_url: nil,
  ssr_raise_on_error: false,
  on_ssr_error: nil,
  # Path(s) to check for SSR bundle existence before attempting SSR.
  # Set to nil to skip bundle detection (always attempt SSR when enabled).
  # Can be a String path or an Array of paths — SSR proceeds if any file exists.
  ssr_bundle: nil,
  # Cache SSR responses to avoid redundant renders for identical pages.
  # Accepts true, false/nil, or a Hash of Rails.cache.fetch options.
  # Lambdas are supported (instance_exec'd in controller context).
  ssr_cache: nil,
  # JavaScript runtime used to run the SSR bundle (e.g. "node", "bun", "deno").
  # When nil, auto-detects from lockfiles or falls back to "node".
  ssr_runtime: nil,

  # Used to detect version drift between server and client.
  version: nil,

  # Allows configuring the base controller for StaticController.
  parent_controller: '::ApplicationController',

  # 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,

  # Whether to use `data-inertia` attribute instead of `inertia` for meta tags.
  use_data_inertia_head_attribute: 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,

  # Whether to prevent database writes during precognition requests.
  # When enabled, any ActiveRecord write during a precognition request
  # will raise ActiveRecord::ReadOnlyError.
  precognition_prevent_writes: false,

  # 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

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(controller: nil, **attrs) ⇒ Configuration

Returns a new instance of Configuration.

Raises:

  • (ArgumentError) 


102
103
104
105
106
107
108
109
 
# File 'lib/inertia_rails/configuration.rb', line 102

def initialize(controller: nil, **attrs)
  @controller = controller
  @options = attrs.extract!(*OPTION_NAMES)

  return if attrs.empty?

  raise ArgumentError, "Unknown options for #{self.class}: #{attrs.keys}"
end

Class Method Details

.default ⇒ Object 



83
84
85
 
# File 'lib/inertia_rails/configuration.rb', line 83

def default
  new(**DEFAULTS, **env_options)
end

Instance Method Details

#bind_controller(controller) ⇒ Object 



111
112
113
 
# File 'lib/inertia_rails/configuration.rb', line 111

def bind_controller(controller)
  Configuration.new(**@options, controller: controller)
end

#cache_store ⇒ Object 



148
149
150
 
# File 'lib/inertia_rails/configuration.rb', line 148

def cache_store
  @options[:cache_store] || Rails.cache
end

#component_path_resolver(path:, action:) ⇒ Object 



135
136
137
 
# File 'lib/inertia_rails/configuration.rb', line 135

def component_path_resolver(path:, action:)
  @options[:component_path_resolver].call(path: path, action: action)
end

#freeze ⇒ Object 



115
116
117
118
 
# File 'lib/inertia_rails/configuration.rb', line 115

def freeze
  @options.freeze
  super
end

#merge(config) ⇒ Object 



125
126
127
 
# File 'lib/inertia_rails/configuration.rb', line 125

def merge(config)
  Configuration.new(**@options, **config.options)
end

#merge!(config) ⇒ Object 



120
121
122
123
 
# File 'lib/inertia_rails/configuration.rb', line 120

def merge!(config)
  @options.merge!(config.options)
  self
end

#on_ssr_error ⇒ Object

Returns the callable without evaluating it — called with (error, page) by the renderer.



144
145
146
 
# File 'lib/inertia_rails/configuration.rb', line 144

def on_ssr_error
  @options[:on_ssr_error]
end

#prop_transformer(props:) ⇒ Object 



139
140
141
 
# File 'lib/inertia_rails/configuration.rb', line 139

def prop_transformer(props:)
  @options[:prop_transformer].call(props: props)
end

#with_defaults(config) ⇒ Object

Internal: Finalizes the configuration for a specific controller.



130
131
132
133
 
# File 'lib/inertia_rails/configuration.rb', line 130

def with_defaults(config)
  @options = config.options.merge(@options)
  freeze
end