Configuration and boot

These fire when the app boots, when a controller class loads, or when rails ruact:routes or ruact:server_functions:generate runs — in a rake task the message goes to stderr as [ruact] error: <message> and the task exits 1. Values the gem fills from your app are in angle brackets.

Ruact.configure

A setting changed after boot

Ruact::ConfigurationErrorwherever the change runs

ruact: cannot mutate Ruact::Configuration#layout after initialization.
  Attempted at: <file>:<line>
  Wrap the change in Ruact.configure { |c| c.layout = ... } in config/initializers/ruact.rb and restart the process.
  Why: Ruact::Configuration is frozen after initialization (Story 7.3) so that runtime config drift cannot cause environment-dependent behavior.

Fix. Settings belong in config/initializers/ruact.rb, inside Ruact.configure. The configuration is frozen once the app has booted, so a setting cannot depend on a request, a feature flag or the time of day. Ruact.configure itself, called after boot, only warns.

config.layout

layout takes true (your app’s layout, which must call ruact_js_assets), false (ruact’s built-in shell), or a layout name such as "ruact", the one the gem ships.

Ruact::ConfigurationErrorboot

Ruact::Configuration#layout must be true, false, or a non-empty String layout name; got nil (NilClass). true renders through your app's layout (which must call ruact_js_assets); false uses ruact's built-in shell.

:auto, which earlier versions took, has its own message:

Ruact::ConfigurationErrorboot

Ruact::Configuration#layout no longer supports :auto — it inferred whether your layout was ready by inspecting it, which could not be done reliably. Set `true` to render through your app's layout (make sure it calls `<%= ruact_js_assets %>`), or `false` for ruact's built-in shell.

config.layout_stylesheets

Ruact::ConfigurationErrorboot

Ruact::Configuration#layout_stylesheets: :app and :all stand alone — Propshaft reads them only as the whole list and drops anything next to them; got [:app, "admin"]. Use [:app], or list the stylesheets by name.

Anything but an Array of stylesheet names is refused with the accepted forms spelled out: [:app], ["application"], or [] to link none of your app’s stylesheets.

Controller macros

ruact_pages and ruact_streaming options

ArgumentErrorclass load

ruact_pages takes exactly one of only: or except: (PostsController)

ArgumentErrorclass load

ruact_streaming takes only: or except:, not both (PostsController)

An action name that is not an action

A misspelled action in ruact_pages or ruact_streaming is found when the controller is consulted, and reaches the log as a [ruact] line:

[ruact] log linerequest

[ruact] PostsController declares ruact_pages for shwo, which is not an action of it (no method and no template). Check the spelling in `ruact_pages`.

Server-function names

Every server function becomes a JavaScript export of @/.ruact/server-functions, so two can never share a name.

Two functions that map to the same JavaScript name

Ruact::ConfigurationErrorboot · rake

server-function naming collision: Admin::PostsController#update and PostsController#update both map to JS identifier "<name>" — disambiguate with `ruact_function_name :<action>, as: "<other-name>"`

Fix. Give one of them its own name in its controller:

app/controllers/admin/posts_controller.rb

ruact_function_name :update, as: "adminUpdatePost"

A name that is not a valid JavaScript identifier, or is taken

Ruact::ConfigurationErrorclass load

ruact_function_name :update, as: "update-post" — "update-post" is not a valid JS identifier (must match <pattern>)

Ruact::ConfigurationErrorclass load

ruact_function_name :refresh, as: "revalidate" — "revalidate" is a reserved JS word or is already bound by the ruact runtime (`_makeServerFunction` / `_makeQuery` / `revalidate` / `useQuery`); pick another name