Release Notes
Contributors Info
React Server Components
Node Renderer
Shakacode logoShakaCodeDeveloped by

Copyright 2026 ShakaCode

React on rails logo
React on Rails Pro
ShakaCode WebsiteCommunityReact on Rails Pro
Press Ctrl+K to search anytime

Installation

React on Rails Pro packages are published publicly on npmjs.org and RubyGems.org. A paid license is required for production deployments only. No license token is needed for evaluation, local development, testing, or CI/CD. Contact [email protected] to purchase a license.

Upgrading from GitHub Packages? See the Upgrading Guide for migration instructions.

Check the CHANGELOG to see what version you want.

Version Format

For the below docs, find the desired <version> in the CHANGELOG. Note that for pre-release versions:

  • Gems use all periods: 16.2.0.beta.1
  • NPM packages use dashes: 16.2.0-beta.1

Ruby Gem Installation

Prerequisites

Ensure your Rails app is using the react_on_rails gem, version 16.0.0 or higher.

Install react_on_rails_pro Gem

Add the react_on_rails_pro gem to your Gemfile:

gem "react_on_rails_pro", "~> 16.2"

Then run:

bundle install

Or install directly:

gem install react_on_rails_pro --version "<version>"

License Configuration (Production Only)

React on Rails Pro uses a license-optional model to simplify evaluation and development. A license token is optional for evaluation, local development, test environments, CI/CD pipelines, and staging/non-production deployments.

For production deployments, set your license token as an environment variable:

export REACT_ON_RAILS_PRO_LICENSE="your-license-token-here"

Or create a config file at config/react_on_rails_pro_license.key:

echo "your-license-token-here" > config/react_on_rails_pro_license.key

⚠️ Security Warning: Never commit your license token to version control. Add config/react_on_rails_pro_license.key to your .gitignore. For production, use environment variables or secure secret management systems (Rails credentials, Heroku config vars, AWS Secrets Manager, etc.).

For complete license setup instructions, see LICENSE_SETUP.md.

Rails Configuration

You don't need to create an initializer if you are satisfied with the defaults as described in Configuration.

For basic setup:

# config/initializers/react_on_rails_pro.rb
ReactOnRailsPro.configure do |config|
  # Your configuration here
  # See docs/configuration.md for all options
end

Client Package Installation

All React on Rails Pro users need to install the react-on-rails-pro npm package for client-side React integration.

Install react-on-rails-pro

Using npm:

npm install react-on-rails-pro

Using yarn:

yarn add react-on-rails-pro

Using pnpm:

pnpm add react-on-rails-pro

Usage

Important: Import from react-on-rails-pro, not react-on-rails. The Pro package re-exports everything from the core package plus Pro-exclusive features.

// Correct - use react-on-rails-pro
import ReactOnRails from 'react-on-rails-pro';

// Register components
ReactOnRails.register({ MyComponent });

Pro-exclusive imports:

// React Server Components
import { RSCRoute } from 'react-on-rails-pro/RSCRoute';
import registerServerComponent from 'react-on-rails-pro/registerServerComponent/client';

// Async component loading
import { wrapServerComponentRenderer } from 'react-on-rails-pro/wrapServerComponentRenderer/client';

See the React Server Components tutorial for detailed usage.

Node Renderer Installation

Note: You only need to install the Node Renderer if you are using the standalone node renderer (NodeRenderer). If you're using ExecJS (the default), skip this section.

Install react-on-rails-pro-node-renderer

Using npm:

npm install react-on-rails-pro-node-renderer

Using yarn:

yarn add react-on-rails-pro-node-renderer

Add to package.json:

{
  "dependencies": {
    "react-on-rails-pro-node-renderer": "^16.2.0"
  }
}

Node Renderer Setup

Create a JavaScript file to configure and launch the node renderer, for example react-on-rails-pro-node-renderer.js:

const path = require('path');
const { reactOnRailsProNodeRenderer } = require('react-on-rails-pro-node-renderer');

const env = process.env;

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

  // Listen at RENDERER_PORT env value or default port 3800
  logLevel: env.RENDERER_LOG_LEVEL || 'debug', // show all logs

  // Password for Rails <-> Node renderer communication
  // See value in /config/initializers/react_on_rails_pro.rb
  password: env.RENDERER_PASSWORD || 'changeme',

  port: env.RENDERER_PORT || 3800,

  // supportModules should be set to true to allow the server-bundle code to
  // see require, exports, etc. (`false` is like the ExecJS behavior)
  // This option is required to equal `true` in order to use loadable components
  supportModules: true,

  // workersCount defaults to the number of CPUs minus 1
  workersCount: Number(env.NODE_RENDERER_CONCURRENCY || 3),

  // Optional: Automatic worker restarting (for memory leak mitigation)
  // allWorkersRestartInterval: 15, // minutes between restarting all workers
  // delayBetweenIndividualWorkerRestarts: 2, // minutes between each worker restart
  // gracefulWorkerRestartTimeout: undefined, // timeout for graceful worker restart; forces restart if worker stuck
};

// Renderer detects a total number of CPUs on virtual hostings like Heroku
// or CircleCI instead of CPUs number allocated for current container. This
// results in spawning many workers while only 1-2 of them really needed.
if (env.CI) {
  config.workersCount = 2;
}

reactOnRailsProNodeRenderer(config);

Add a script to your package.json:

{
  "scripts": {
    "node-renderer": "node ./react-on-rails-pro-node-renderer.js"
  }
}

Start the renderer:

npm run node-renderer

Rails Configuration for Node Renderer

Configure Rails to use the remote node renderer:

# config/initializers/react_on_rails_pro.rb
ReactOnRailsPro.configure do |config|
  config.server_renderer = "NodeRenderer"

  # Configure renderer connection
  config.renderer_url = ENV["REACT_RENDERER_URL"] || "http://localhost:3800"
  config.renderer_password = ENV["RENDERER_PASSWORD"] || "changeme"

  # Enable prerender caching (recommended)
  config.prerender_caching = true
end

Configuration Options

See Rails Configuration Options for all available settings.

Pay attention to:

  • config.server_renderer = "NodeRenderer" - Required to use node renderer
  • config.renderer_url - URL where your node renderer is running
  • config.renderer_password - Shared secret for authentication
  • config.prerender_caching - Enable caching (recommended)

Webpack Configuration

Set your server bundle webpack configuration to use a target of node per the Webpack docs.

Additional Documentation