Upgrading React on Rails Pro

Upgrading from GitHub Packages to Public Distribution

Who This Guide is For

This guide is for existing React on Rails Pro customers who are:

• Previously using GitHub Packages authentication (private distribution)
• On version 16.2.0-beta.x or earlier
• Upgrading to version 16.2.0 or higher

If you're a new customer, see Installation instead.

What's Changing

React on Rails Pro packages are now publicly distributed via npmjs.org and RubyGems.org:

• ✅ No more GitHub Personal Access Tokens (PATs)
• ✅ No more .npmrc configuration
• ✅ Simplified installation with standard gem install and npm install
• ✅ License validation now happens at runtime using JWT tokens

Package names have changed:

Important: Pro users should now import from react-on-rails-pro instead of react-on-rails. The Pro package includes all core features plus Pro-exclusive functionality.

Breaking Changes and Deprecation Policy

To reduce upgrade risk, React on Rails Pro follows this policy:

1. Deprecate first when practical (docs/changelog + clear replacement).
2. Warn at runtime when practical if a deprecated setup is detected.
3. Remove in a later release with a short migration note in this guide.
4. Exception: security/legal fixes may be removed immediately, but must include an explicit upgrade note.

Your Current Setup (GitHub Packages)

If you're upgrading, you currently have:

1. Gemfile with GitHub Packages source:

source "https://rubygems.pkg.github.com/shakacode-tools" do
  gem "react_on_rails_pro", "16.1.1"
end

2. .npmrc file with GitHub authentication:

always-auth=true
//npm.pkg.github.com/:_authToken=YOUR_TOKEN
@shakacode-tools:registry=https://npm.pkg.github.com

3. Scoped package name in package.json:

{
  "private": true,
  "dependencies": {
    "@shakacode-tools/react-on-rails-pro-node-renderer": "16.1.1"
  }
}

4. Scoped require statements:

const { reactOnRailsProNodeRenderer } = require('@shakacode-tools/react-on-rails-pro-node-renderer');

Migration Steps

Step 1: Update Gemfile

Remove the GitHub Packages source and use standard gem installation:

- source "https://rubygems.pkg.github.com/shakacode-tools" do
-   gem "react_on_rails_pro", "16.1.1"
- end
+ gem "react_on_rails_pro", "~> 16.2"

Then run:

bundle install

Step 2: Remove .npmrc Configuration

If you have a .npmrc file with GitHub Packages authentication, delete it or remove the GitHub-specific lines:

# Remove the entire file if it only contained GitHub Packages config
rm .npmrc

# Or edit it to remove these lines:
# always-auth=true
# //npm.pkg.github.com/:_authToken=YOUR_TOKEN
# @shakacode-tools:registry=https://npm.pkg.github.com

Step 3: Update package.json

Add the client package and update the node renderer package name:

{
  "dependencies": {
+   "react-on-rails-pro": "^16.2.0",
-   "@shakacode-tools/react-on-rails-pro-node-renderer": "16.1.1"
+   "react-on-rails-pro-node-renderer": "^16.2.0"
  }
}

Then reinstall:

npm install
# or
yarn install

Step 4: Update Import Statements

Client code: Change all imports from react-on-rails to react-on-rails-pro:

- import ReactOnRails from 'react-on-rails';
+ import ReactOnRails from 'react-on-rails-pro';

Pro-exclusive features (React Server Components, async loading):

- import { RSCRoute } from 'react-on-rails/RSCRoute';
+ import { RSCRoute } from 'react-on-rails-pro/RSCRoute';

- import registerServerComponent from 'react-on-rails/registerServerComponent/client';
+ import registerServerComponent from 'react-on-rails-pro/registerServerComponent/client';

- import { wrapServerComponentRenderer } from 'react-on-rails/wrapServerComponentRenderer/client';
+ import { wrapServerComponentRenderer } from 'react-on-rails-pro/wrapServerComponentRenderer/client';

Node renderer configuration file:

- const { reactOnRailsProNodeRenderer } = require('@shakacode-tools/react-on-rails-pro-node-renderer');
+ const { reactOnRailsProNodeRenderer } = require('react-on-rails-pro-node-renderer');

Node renderer integrations (Sentry, Honeybadger):

- require('@shakacode-tools/react-on-rails-pro-node-renderer/integrations/sentry').init();
+ require('react-on-rails-pro-node-renderer/integrations/sentry').init();

- require('@shakacode-tools/react-on-rails-pro-node-renderer/integrations/honeybadger').init();
+ require('react-on-rails-pro-node-renderer/integrations/honeybadger').init();

Step 5: Configure License Token (Production Only)

React on Rails Pro uses a license-optional model to simplify evaluation and development.

A license token is optional for non-production environments:

• Evaluation and local development
• Test environments and CI/CD pipelines
• Staging/non-production deployments

A paid license is required only for production deployments.

Configure your React on Rails Pro license token as an environment variable:

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

Migration note (legacy key-file setup): config/react_on_rails_pro_license.key is no longer read by React on Rails Pro. If you previously used that file, move the token into REACT_ON_RAILS_PRO_LICENSE.

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

Where to get your license token: Contact [email protected] if you don't have your license token.

For complete licensing details, see LICENSE_SETUP.md.

Verify Migration

1. Verify Gem Installation

bundle list | grep react_on_rails_pro
# Should show: react_on_rails_pro (16.2.0) or higher

2. Verify NPM Package Installation

# Verify client package
npm list react-on-rails-pro
# Should show: [email protected] or higher

# Verify node renderer (if using)
npm list react-on-rails-pro-node-renderer
# Should show: [email protected] or higher

3. Verify License Status

Start your Rails server and verify behavior:

React on Rails Pro license validated successfully

If no license is set in non-production environments, the app still runs and logs informational status.

For production, ensure a valid license is configured.

4. Test Your Application

• Start your Rails server
• Start the node renderer (if using): npm run node-renderer
• Verify that server-side rendering works correctly

Troubleshooting

"Could not find gem 'react_on_rails_pro'"

• Ensure you removed the GitHub Packages source from your Gemfile
• Run bundle install again
• Check that you have the correct version specified

"Cannot find module 'react-on-rails-pro'" or "Cannot find module 'react-on-rails-pro-node-renderer'"

• Verify you added react-on-rails-pro to your package.json dependencies
• Verify you updated all import/require statements to use the correct package names
• Delete node_modules and reinstall: rm -rf node_modules && npm install

"Cannot mix react-on-rails (core) with react-on-rails-pro"

This error occurs when you import from both react-on-rails and react-on-rails-pro. Pro users should only import from react-on-rails-pro:

- import ReactOnRails from 'react-on-rails';
+ import ReactOnRails from 'react-on-rails-pro';

The Pro package re-exports everything from core, so you don't need both.

"License validation failed" (production)

• Ensure REACT_ON_RAILS_PRO_LICENSE environment variable is set in production.
• Verify the token string is correct (no extra spaces or quotes).
• Contact [email protected] if you need a new token.

Need Help?

If you encounter issues during migration, contact [email protected] for support.