docs/guides/configuration.md
Here is the full set of config options. This file is `/config/initializers/react_on_rails.rb`
First, you should have a `/config/shakapacker.yml` setup.
Here is the setup when using the recommended `/client` directory for your `node_modules` and source files:
```yaml
# Note: Base output directory of /public is assumed for static files
default: &default
compile: false
# Used in your webpack configuration. Must be created in the
# public_output_path folder
manifest: manifest.json
cache_manifest: false
# Source path is used to check if webpack compilation needs to be run for `compile: true`
source_path: client/app
development:
<<: *default
# Generated files for development, in /public/webpack/dev
public_output_path: webpack/dev
test:
<<: *default
# Ensure that shakapacker invokes webpack to build files for tests if not using the
# ReactOnRails rspec helper.
compile: true
# Generated files for tests, in /public/webpack/test
public_output_path: webpack/test
production:
<<: *default
# Generated files for production, in /public/webpack/production
public_output_path: webpack/production
cache_manifest: true
```
Here's a representative `/config/initializers/react_on_rails.rb` setup when using this `/client` directory
for all client files, including your sources and node_modules.
```ruby
# frozen_string_literal: true
# NOTE: you typically will leave the commented out configurations set to their defaults.
# Thus, you only need to pay careful attention to the non-commented settings in this file.
ReactOnRails.configure do |config|
# You can optionally add values to your rails_context. This object is passed
# every time a component renders.
# See below for an example definition of RenderingExtension
config.rendering_extension = RenderingExtension
# `trace`: General debugging flag.
# The default is true for development, off otherwise.
# With true, you get detailed logs of rendering and stack traces if you call setTimout,
# setInterval, clearTimout when server rendering.
config.trace = Rails.env.development? # default
# Configure if default DOM IDs have a random value or are fixed.
# false ==> Sets the dom id to "#{react_component_name}-react-component"
# true ==> Adds "-#{SecureRandom.uuid}" to that ID
# If you might use multiple instances of the same React component on a Rails page, then
# it is convenient to set this to true or else you have to either manually set the ids to
# avoid collisions. Most newer apps will have only one instance of a component on a page,
# so this should be false in most cases.
# This value can be overridden for a given call to react_component
config.random_dom_id = true # default
# defaults to "" (top level)
config.node_modules_location = "client" # If using Shakapacker you should use "".
# If you're using the standard Shakapacker configuration of webpack, then Shakapacker
# will automatically modify or create an assets:precompile task to build your assets. If so,
# set this value to nil. Alternatively, you can specify `config.build_production_command`
# to have react_on_rails invoke a command for you during assets:precompile.
# The command is either a script or a module containing a class method `call`
# In this example, the module BuildProductionCommand would have a class method `call`.
config.build_production_command = "RAILS_ENV=production bin/shakapacker"
# NOTE:
# When specifying `build_production_command`, you need to disable `rails/shakapacker`
# configuration by setting `shakapacker_precompile: false` in your `config/shakapacker.yml` file.
# See bottom for an example of the BuildProductionCommand module.
# config.build_production_command = BuildProductionCommand
# If you wish to utilize ReactOnRailsPro production bundle caching logic, then use
# config.build_production_command = ReactOnRailsPro::AssetsPrecompile
# and be sure to check ReactOnRailsPro's configuration documentation!
################################################################################
################################################################################
# SERVER RENDERING OPTIONS
################################################################################
# This is the file used for server rendering of React when using `(prerender: true)`
# If you are not using server rendering, you should set this to `nil`.
# Note, there is only one server bundle, unlike JavaScript where you want to minimize the size
# of the JS sent to the client. For the server rendering, React on Rails creates a pool of
# JavaScript execution instances which should handle any component requested.
#
# While you may configure this to be the same as your client bundle file, this file is typically
# different. Note, be sure to include the exact file name with the ".js" if you are not hashing this file.
# If you are hashing this file (supposing you are using the same file for client rendering), then
# you should include a name that matches your bundle name in your webpack config.
config.server_bundle_js_file = "server-bundle.js"
# `prerender` means server-side rendering
# default is false. This is an option for view helpers `render_component` and `render_component_hash`.
# Set to true to change the default value to true.
config.prerender = false
# THE BELOW OPTIONS FOR SERVER-SIDE RENDERING RARELY NEED CHANGING
#
# This value only affects server-side rendering when using the webpack-dev-server
# If you are hashing the server bundle and you want to use the same bundle for client and server,
# you'd set this to `true` so that React on Rails reads the server bundle from the webpack-dev-server.
# Normally, you have different bundles for client and server, thus, the default is false.
# Furthermore, if you are not hashing the server bundle (not in the manifest.json), then React on Rails
# will only look for the server bundle to be created in the typical file location, typically by
# a `shakapacker --watch` process.
# If true, ensure that in config/shakapacker.yml that you have both dev_server.hmr and
# dev_server.inline set to false.
config.same_bundle_for_client_and_server = false
# If set to true, this forces Rails to reload the server bundle if it is modified
# Default value is Rails.env.development?
# You probably will never change this.
config.development_mode = Rails.env.development?
# For server rendering so that the server-side console replays in the browser console.
# This can be set to false so that server side messages are not displayed in the browser.
# Default is true. Be cautious about turning this off, as it can make debugging difficult.
# Default value is true
config.replay_console = true
# Default is true. Logs server rendering messages to Rails.logger.info. If false, you'll only
# see the server rendering messages in the browser console.
config.logging_on_server = true
# Default is true only for development? to raise exception on server if the JS code throws for
# server rendering. The reason is that the server logs will show the error and force you to fix
# any server rendering issues immediately during development.
config.raise_on_prerender_error = Rails.env.development?
# This configuration allows logic to be applied to client rendered props, such as stripping props that are only used during server rendering.
# Add a module with an adjust_props_for_client_side_hydration method that expects the component's name & props hash
# See below for an example definition of RenderingPropsExtension
config.rendering_props_extension = RenderingPropsExtension
################################################################################
# Server Renderer Configuration for ExecJS
################################################################################
# The default server rendering is ExecJS, by default using Node.js runtime
# If you wish to use an alternative Node server rendering for higher performance,
# contact justin@shakacode.com for details.
#
# For ExecJS:
# You can configure your pool of JS virtual machines and specify where it should load code:
# On MRI, use `node.js` runtime for the best performance
# (see https://github.com/shakacode/react_on_rails/issues/1438)
# Also see https://github.com/shakacode/react_on_rails/issues/1457#issuecomment-1165026717 if using `mini_racer`
# On MRI, you'll get a deadlock with `pool_size` > 1
# If you're using JRuby, you can increase `pool_size` to have real multi-threaded rendering.
config.server_renderer_pool_size = 1 # increase if you're on JRuby
config.server_renderer_timeout = 20 # seconds
################################################################################
################################################################################
# FILE SYSTEM BASED COMPONENT REGISTRY
# `render_component` and `render_component_hash` view helper methods can
# auto-load the bundle for the generated component, to avoid having to specify the
# bundle manually for each view with the component.
################################################################################
# components_subdirectory is the name of the subdirectory matched to detect and register components automatically
# The default is nil. You can enable the feature by updating it in the next line.
config.components_subdirectory = nil
# Change to a value like this example to enable this feature
# config.components_subdirectory = "ror_components"
# Default is false.
# The default can be overridden as an option in calls to view helpers
# `render_component` and `render_component_hash`. You may set to true to change the default to auto loading.
config.auto_load_bundle = false
# Default is false
# Set this to true & instead of trying to import the generated server components into your existing
# server bundle entrypoint, the PacksGenerator will create a server bundle entrypoint using
# config.server_bundle_js_file for the filename.
config.make_generated_server_bundle_the_entrypoint = false
# Default is true, which matches Webpacker/Shakapacker's defer default for `append_javascript_pack`
# Set this to false to have `defer: false` added to your `append_javascript_pack` calls for generated entrypoints.
config.defer_generated_component_packs = true
################################################################################
# I18N OPTIONS
################################################################################
# Replace the following line to the location where you keep translation.js & default.js for use
# by the npm packages react-intl. Be sure this directory exists!
# config.i18n_dir = Rails.root.join("client", "app", "libs", "i18n")
#
# If not using the i18n feature, then leave this section commented out or set the value
# of config.i18n_dir to nil.
#
# Replace the following line to the location where you keep your client i18n yml files
# that will source for automatic generation on translations.js & default.js
# By default(without this option) all yaml files from Rails.root.join("config", "locales")
# and installed gems are loaded
config.i18n_yml_dir = Rails.root.join("config", "locales")
# Possible output formats are js and json
# The default format is json
config.i18n_output_format = 'json'
################################################################################
################################################################################
# TEST CONFIGURATION OPTIONS
# Below options are used with the use of this test helper:
# ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
#
# NOTE:
# Instead of using this test helper, you may ensure fresh test files using Shakapacker via:
# 1. Have `config/webpack/test.js` exporting an array of objects to configure both client and server bundles.
# 2. Set the compile option to true in config/shakapacker.yml for env test
################################################################################
# If you are using this in your spec_helper.rb (or rails_helper.rb):
#
# ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
#
# with rspec then this controls what yarn command is run
# to automatically refresh your webpack assets on every test run.
#
config.build_test_command = "RAILS_ENV=test bin/shakapacker"
# CONFIGURE YOUR SOURCE FILES
# The test helper needs to know where your JavaScript files exist. The value is configured
# by your config/shakapacker.yml source_path:
# source_path: client/app # if using recommended /client directory
#
# Define the files we need to check for webpack compilation when running tests.
# The default is `%w( manifest.json )` as will be sufficient for most shakapacker builds.
# However, if you are generating a server bundle that is NOT hashed (present in manifest.json),
# then include the file in this list like this:
config.webpack_generated_files = %w( server-bundle.js manifest.json )
# Note, be sure NOT to include your server-bundle.js if it is hashed, or else React on Rails will
# think the server-bundle.js is missing every time for test runs.
end
```
Example of a ReactOnRailsConfig module for `client_props_extension`:
```ruby
module RenderingPropsExtension
# The modify_props method will be called by ReactOnRails::ReactComponent::RenderOptions if config.client_props_extension is defined
def self.adjust_props_for_client_side_hydration(component_name, props)
component_name == 'HelloWorld' ? props.except(:server_side_only) : props
end
end
```
Example of a ReactOnRailsConfig module for `production_build_command`:
```ruby
module BuildProductionCommand
include FileUtils
# The call method will be called during assets:precompile
def self.call
sh "bin/shakapacker"
end
end
```
Example of a RenderingExtension for custom values in the `rails_context`:
```ruby
module RenderingExtension
# Return a Hash that contains custom values from the view context that will get merged with
# the standard rails_context values and passed to all calls to Render-Functions used by the
# react_component and redux_store view helpers
def self.custom_context(view_context)
{
somethingUseful: view_context.session[:something_useful]
}
end
end
```