Skip to main content
Edit

Consuming an Unreleased Build

Use this page when you need to test an unreleased version of React on Rails in your own application — before it is published to RubyGems or npm.

note

Summary for AI agents: This is the adopter-facing version of the "Testing your changes in an external application" section of CONTRIBUTING.md. It covers pointing a downstream app at a Git branch (gems) and at the per-package npm subdirectories. The two non-obvious gotchas are the OSS-vs-Pro glob: asymmetry for gems and the fact that bare owner/repo#ref npm refs do not work for the subdirectory packages.

When you need this​

React on Rails ships the gem and several npm packages from a single monorepo. When a fix or feature has landed on main (or another branch) but has not yet been released, you can still consume it directly from Git so you can validate it in a real application before the next release.

This is useful when you want to:

  • Verify a bug fix against your app before it is published.
  • Try a feature on an upcoming branch.
  • Reproduce or confirm behavior reported in an issue or PR.

Ruby gems​

Point your Gemfile at the Git repository and branch:

gem 'react_on_rails',
  git: 'https://github.com/shakacode/react_on_rails',
  branch: 'main'
gem 'react_on_rails_pro',
  git: 'https://github.com/shakacode/react_on_rails',
  glob: 'react_on_rails_pro/react_on_rails_pro.gemspec',
  branch: 'main'

Note the asymmetry: the open-source react_on_rails gem needs no glob: option — its gemspec lives at the repository root and Bundler finds it automatically. Only react_on_rails_pro needs an explicit glob: 'react_on_rails_pro/react_on_rails_pro.gemspec' because its gemspec lives in a subdirectory. Run bundle install afterward, and use bundle update react_on_rails react_on_rails_pro to pull newer commits from the branch.

npm packages​

The npm packages live in subdirectories of the monorepo (packages/react-on-rails, packages/react-on-rails-pro, packages/react-on-rails-pro-node-renderer). Not every package manager can depend on a single subdirectory of a Git repo, so the recommended path depends on your manager.

pnpm can install a subdirectory of a Git repo directly:

pnpm add "github:shakacode/react_on_rails#main&path:packages/react-on-rails"

For Pro, add the additional packages the same way, substituting packages/react-on-rails-pro and packages/react-on-rails-pro-node-renderer for the path: value.

Yarn Berry​

Yarn Berry supports the Git protocol with a workspace selector:

yarn add "git@github.com:shakacode/react_on_rails.git#workspace=react-on-rails&head=main"

npm (and managers that can't resolve a Git subdirectory)​

npm does not support depending on a subdirectory of a Git repo, so build a tarball with pnpm pack and install that:

# In the React on Rails checkout
pnpm install && pnpm run build
cd packages/react-on-rails && pnpm pack   # creates react-on-rails-<version>.tgz

# In your app
npm install <path-to-tarball>

For rapid iteration, yalc is an alternative: after pnpm run build, run yalc publish from each packages/* directory you changed, then yalc add <package> in your app.

tip

Why a bare owner/repo#ref fails for these packages: a bare Git ref resolves the workspace root, not the publishable subdirectory you want. In addition, each package's lib/ output is gitignored (packages/*/lib/) and produced by the package's prepare/build script — which some package managers skip for Git dependencies — so you would end up without the built output. The pnpm path: selector and the tarball both avoid this.

Version pairing​

When you consume an unreleased build, bump the related packages together so versions stay compatible:

  • react_on_rails (gem)
  • react-on-rails (npm)
  • react_on_rails_pro (gem)
  • react-on-rails-pro (npm)
  • react-on-rails-pro-node-renderer (npm)
  • react-on-rails-rsc (npm), if you use React Server Components — see shakacode/react_on_rails_rsc#109

Mixing a new gem with old npm packages (or vice versa) is the most common cause of confusing failures when testing an unreleased build.

See also​

For the contributor-oriented version — including local path: dependencies and testing changes against the in-repo dummy apps — see Testing your changes in an external application in CONTRIBUTING.md.