ContextQMD
Back to React On Rails

Node Renderer Basics

docs/oss/building-features/node-renderer/basics.md

16.6.07.3 KB
Original Source

Node Renderer Basics

Pro Feature — Available with React on Rails Pro. Free or very low cost for startups and small companies. Upgrade or licensing details →

Requirements

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

Install the Gem and the Node Module

See Installation.

Memory Management

The Node Renderer reuses V8 VM contexts across requests for performance. This means module-level state in your server bundle persists across all SSR requests. Any unbounded caches, _.memoize calls, or growing data structures at module scope will leak memory until the worker restarts.

Essential for production:

  • Set NODE_OPTIONS=--max-old-space-size=<MB> to prevent V8 from deferring garbage collection
  • Enable worker rolling restarts via allWorkersRestartInterval and delayBetweenIndividualWorkerRestarts
  • Audit your server bundle for module-level mutable state

See the Memory Leaks guide for common leak patterns and how to fix them.

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

  1. ENV values for the default config are (See JS Configuration for more details):
    • RENDERER_PORT
    • RENDERER_HOST
    • 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
  2. 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:
    bash
    RENDERER_BUNDLE_PATH=/app/.node-renderer-bundles node-renderer
  3. 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.

  1. Create some project directory, let's say renderer-app:

    sh
    mkdir renderer-app
cd renderer-app

  2. Make sure you have Node.js 18+ and a JavaScript package manager such as npm, pnpm, Yarn, or bun.

  3. Initialize a Node application and install the react-on-rails-pro-node-renderer package.

    sh
    npm init -y
npm install react-on-rails-pro-node-renderer
# or: pnpm add react-on-rails-pro-node-renderer
# or: yarn add react-on-rails-pro-node-renderer
# or: bun add react-on-rails-pro-node-renderer

  4. 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:

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

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

reactOnRailsProNodeRenderer(config);

  5. Now you can launch your renderer server with node node-renderer.js. You will probably add a script to your package.json.

  6. 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:

  1. Set config.server_renderer = "NodeRenderer"
  2. Decide whether to enable config.prerender_caching = true. The default is false; turn it on only if you want Rails cache-backed SSR result caching and your cache is configured for the additional load.
  3. Configure values beginning with renderer_
  4. 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.
  5. Here's a tiny example using mostly defaults:
ruby
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

Network Security

The Node Renderer executes JavaScript sent to it by the Rails application using Node.js vm.runInContext(). This makes it, by design, a remote code execution service — any client that can reach the HTTP port can execute arbitrary JavaScript on the host machine.

Node.js vm contexts are not a security boundary. Escaping a vm sandbox to access the full Node.js runtime (file system, child processes, network) is well-documented and straightforward.

To mitigate this, the renderer uses the same approach as PostgreSQL: it binds to localhost by default, so it is not reachable from the network at all. This provides two layers of defense:

  1. Network layer — Only processes on the same machine (or same Kubernetes pod network namespace) can reach the renderer. No remote attacker can connect.
  2. Authentication layer — The optional password setting (required in production-like environments) protects against unauthorized local callers.

This means a developer running the renderer locally without a password is safe by default — the renderer is only reachable from their own machine, just as a default PostgreSQL installation only accepts local connections.

When you must bind to 0.0.0.0 (e.g., separate container workloads in Docker Compose or Kubernetes separate-workload deployments):

  • Always set RENDERER_PASSWORD to a strong value
  • Place the renderer behind private networking or firewall rules
  • Never expose the renderer port to the public internet

See JS Configuration for the host and password options, and Container Deployment for architecture-specific guidance.

Troubleshooting

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.

References