Requirements

You must use React on Rails v11.0.7 or higher.

Install the Gem and the Node Module

Setup Node Renderer Server

node-renderer is a standalone Node application to serve React SSR requests from a Rails client. You don't need any Ruby code to setup and launch it. You can configure with the command line or with a launch file.

Simple Command Line for node-renderer

ENV values for the default config are (See JS Configuration for more details):
- RENDERER_PORT
- RENDERER_LOG_LEVEL
- RENDERER_BUNDLE_PATH
- RENDERER_WORKERS_COUNT
- RENDERER_PASSWORD
- RENDERER_ALL_WORKERS_RESTART_INTERVAL
- RENDERER_DELAY_BETWEEN_INDIVIDUAL_WORKER_RESTARTS
- RENDERER_SUPPORT_MODULES
Configure ENV values and run the command. Note, you can set port with args -p <PORT>. For example, assuming node-renderer is in your path:
```
RENDERER_BUNDLE_PATH=/app/.node-renderer-bundles node-renderer
```
You can use a command line argument of -p SOME_PORT to override any ENV value for the PORT.

JavaScript Configuration File

For the most control over the setup, create a JavaScript file to start the NodeRenderer.

Create some project directory, let's say renderer-app:
```
mkdir renderer-app
cd renderer-app
```
Make sure you have Node.js version 14 or higher and Yarn installed.

Init node application and yarn add to install @shakacode-tools/react-on-rails-pro-node-renderer package.

yarn init
yarn add https://[your-github-token]:[email protected]/shakacode/react_on_rails_pro.git\#master

Configure a JavaScript file that will launch the rendering server per the docs in Node Renderer JavaScript Configuration. For example, create a file node-renderer.js. Here is a simple example that uses all the defaults except for bundlePath:

import path from 'path';
import reactOnRailsProNodeRenderer from '@shakacode-tools/react-on-rails-pro-node-renderer';

const config = {
  bundlePath: path.resolve(__dirname, '../.node-renderer-bundles'),
};

reactOnRailsProNodeRenderer(config);

Now you can launch your renderer server with node node-renderer.js. You will probably add a script to your package.json.
You can use a command line argument of -p SOME_PORT to override any configured or ENV value for the port.

Setup Rails Application

Create config/initializers/react_on_rails_pro.rb and configure the renderer server. See configuration values in Configuration. Pay attention to:

Set config.server_renderer = "NodeRenderer"
Leave the default of config.prerender_caching = true and ensure your Rails cache is properly configured to handle the additional cache load.
Configure values beginning with renderer_
Use ENV values for values like renderer_url so that your deployed server is properly configured. If the ENV value is unset, the default for the renderer_url is localhost:3800.
Here's a tiny example using mostly defaults:

ReactOnRailsPro.configure do |config|
 config.server_renderer = "NodeRenderer"
 
 # when this ENV value is not defined, the local server at localhost:3800 is used 
 config.renderer_url = ENV["REACT_RENDERER_URL"] 
end

Troublshooting

See JS Memory Leaks.

Upgrading

The NodeRenderer has a protocol version on both the Rails and Node sides. If the Rails server sends a protocol version that does not match the Node side, an error is returned. Ideally, you want to keep both the Rails and Node sides at the same version.