docs: update readme to cover the new configuration options

inertiajs · Jun 26, 2024 · 7f84110 · 7f84110
1 parent 46626e4
commit 7f84110
Show file tree

Hide file tree

Showing 2 changed files with 83 additions and 32 deletions.
diff --git a/README.md b/README.md
@@ -67,8 +67,7 @@ Automatic component name is also opt in, you must set the `default_render` confi
 
 ### Layout 
 
-Inertia layouts use the rails layout convention and can be set or changed in the same way. The original `layout` config option is still functional, but will likely be deprecated in the future in favor
-of using rails layouts.
+Inertia layouts use the rails layout convention and can be set or changed in the same way.
 
 ```ruby
 class EventsController < ApplicationController
@@ -133,20 +132,14 @@ end
 }
 ```
 
-Deep merging can be set as the project wide default via the InertiaRails configuration:
+Deep merging can be configured using the `deep_merge_shared_data` configuration option.
 
-```ruby
-# config/initializers/some_initializer.rb
-InertiaRails.configure do |config|
-  config.deep_merge_shared_data = true
-end
-
-```
-
-If deep merging is enabled by default, it's possible to opt out within the action:
+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: {
@@ -163,7 +156,7 @@ class CrazyScorersController < ApplicationController
   end
 end
 
-# Even if deep merging is set by default, since the renderer has `deep_merge: false`, it will send a shallow merge to the frontend:
+# `deep_merge: false` overrides the default:
 {
   basketball_data: {
     points: 100,
@@ -187,34 +180,85 @@ If you don't need a controller to handle a static component, you can route direc
 inertia 'about' => 'AboutComponent'
 ```
 
-### SSR
+### SSR _(experimental)_
+
+Enable SSR via the configuration options for `ssr_enabled` and `ssr_url`.
 
-Enable SSR via the config settings for `ssr_enabled` and `ssr_url`.
+When using SSR, don't forget to add `<%= inertia_ssr_head %>` to the `<head>` of your layout (i.e. `application.html.erb`).
 
-When using SSR, don't forget to add `<%= inertia_ssr_head %>` to the `<head>` of your `application.html.erb`.
+## Configuration ⚙️
 
-## Configuration
+Inertia Rails can be configured globally or in a specific controller (and subclasses).
 
-Inertia Rails has a few different configuration options that can be set anywhere, but the most common location is from within an initializer.
+### Global Configuration
+
+If using global configuration, we recommend you place the code inside an initializer:
 
-The default config is shown below
 ```ruby
+# config/initializers/inertia.rb
+
 InertiaRails.configure do |config|
-
-  # set the current version for automatic asset refreshing. A string value should be used if any.
-  config.version = nil
-  # enable default inertia rendering (warning! this will override rails default rendering behavior)
-  config.default_render = true
-
-  # ssr specific options
-  config.ssr_enabled = false
-  config.ssr_url = 'http://localhost:13714'
+  # Example: force a full-reload if the deployed assets change.
+  config.version = ViteRuby.digest
+end
+```
 
-  config.deep_merge_shared_data = false
-
+The default configuration can be found [here](https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/configuration.rb#L5-L22).
+
+### Local Configuration
+
+Use `inertia_config` in your controllers to override global settings:
+
+```ruby
+class EventsController < ApplicationController
+  inertia_config(
+    version: "events-#{InertiaRails.configuration.version}",
+    ssr_enabled: -> { action_name == "index" },
+  )
 end
 ```
 
+### 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`
+
+#### `default_render`
+
+  Overrides Rails default rendering behavior to render using Inertia by default.
+
+  __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. 

diff --git a/lib/inertia_rails/configuration.rb b/lib/inertia_rails/configuration.rb
@@ -3,14 +3,21 @@
 module InertiaRails
   class Configuration
     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,
 
-      # Let Rails decide which layout should be used based on the controller configuration.
+      # DEPRECATED: Let Rails decide which layout should be used based on the
+      # controller configuration.
       layout: true,
 
-      deep_merge_shared_data: false,
+      # SSR options.
       ssr_enabled: false,
       ssr_url: 'http://localhost:13714',
+
+      # Used to detect version drift between server and client.
       version: nil,
     }.freeze