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.

Generator shortcut: Running rails generate react_on_rails:install --pro (or rails generate react_on_rails:pro for existing apps) automatically creates client/node-renderer.js, adds the Node Renderer process to Procfile.dev, and installs the required npm packages. See Installation for details. The manual setup below is for apps that need custom configuration.

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 install the react-on-rails-pro-node-renderer package.
```
yarn init
yarn add react-on-rails-pro-node-renderer
```

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 serverBundleCachePath:

import path from 'path';
import reactOnRailsProNodeRenderer from 'react-on-rails-pro-node-renderer';

const config = {
  serverBundleCachePath: 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.