Pin npm shakapacker version to match gem in example generation (#2558)

## Summary

- Fix CI example generation failure when a new shakapacker version is
published to npm before/independently of the gem
- `shakapacker:install` adds the npm package with a caret range (e.g.,
`^9.5.0`), so `npm install` can resolve to a newer minor version (e.g.,
9.6.0) while the gem remains at 9.5.0
- Added `pin_shakapacker_npm_version` that reads the exact gem version
from the example app's `Gemfile.lock` and pins the npm `package.json`
entry to match

Fixes the `examples (3.4, latest)` CI failure seen on PR #2516 where npm
shakapacker resolved to 9.6.0 while the gem was 9.5.0.

## Test plan

- [ ] CI `examples (3.4, latest)` job passes
- [ ] Verify that generated example apps have matching gem and npm
shakapacker versions

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Small, localized change to example-generation rake tasks that only
adjusts dependency pinning and should not affect runtime application
behavior.
> 
> **Overview**
> Prevents CI/example app generation failures caused by `shakapacker`
gem/npm version drift by **pinning the npm `shakapacker` dependency to
the exact gem version** after `shakapacker:install`.
> 
> Adds helpers to read the installed Shakapacker gem version from
`Gemfile.lock` and rewrite `package.json` when it contains a semver
range (e.g., `^X.Y.Z`) before running `npm install` for non-react-pinned
examples.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
39fbbb6. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Automatically syncs the npm Shakapacker dependency to the installed
gem version during example app generation to prevent mismatches.
* **Bug Fixes**
* Improved error handling when reading package metadata and only
rewrites files when changes occur.
* **Documentation**
* Added CONTRIBUTING guidance on pinning and updating the Shakapacker
version and regenerating lockfiles.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: justin808

CONTRIBUTING.md

@@ -440,6 +440,31 @@ Run `rake -T` or `rake -D` to see testing options.
 
 See below for verifying changes to the generators.
 
+## Updating the Shakapacker Version for Testing
+
+When a new version of Shakapacker is released, the pinned version used across the test suite needs to be updated. The version is specified in several places:
+
+**Source files (update manually):**
+
+1. `react_on_rails/Gemfile.development_dependencies` — gem version pin
+2. `react_on_rails/spec/dummy/package.json` — npm version pin
+3. `react_on_rails_pro/Gemfile.development_dependencies` — gem version pin (Pro)
+4. `react_on_rails_pro/spec/dummy/package.json` — npm version pin (Pro)
+5. `react_on_rails_pro/spec/execjs-compatible-dummy/Gemfile` — gem version pin (Pro)
+6. `react_on_rails_pro/spec/execjs-compatible-dummy/package.json` — npm version pin (Pro)
+
+**Lock files (regenerated automatically):**
+
+After updating the source files above, regenerate lock files by running `bundle install` and `pnpm install` in the relevant directories:
+
+- `react_on_rails/` and `react_on_rails/spec/dummy/` (OSS)
+- `react_on_rails_pro/` and `react_on_rails_pro/spec/dummy/` and `react_on_rails_pro/spec/execjs-compatible-dummy/` (Pro)
+- Root `Gemfile.lock` and `pnpm-lock.yaml`
+
+**Example apps (handled automatically):**
+
+The CI-generated example apps (under `gen-examples/`) automatically resolve the shakapacker version via the gem dependency. The `pin_shakapacker_npm_version` helper in `react_on_rails/rakelib/shakapacker_examples.rake` ensures the npm version matches the gem.
+
 ## CI Testing and Optimization
 
 React on Rails uses an optimized CI pipeline that runs faster on branches while maintaining full coverage on `master`. Contributors have access to local CI tools to validate changes before pushing.

react_on_rails/rakelib/shakapacker_examples.rake

@@ -16,6 +16,45 @@ require_relative "task_helpers"
 namespace :shakapacker_examples do # rubocop:disable Metrics/BlockLength
   include ReactOnRails::TaskHelpers
 
+  # Pins the shakapacker npm package version to exactly match the installed gem version.
+  # Prevents semver range resolution (e.g., ^9.5.0 -> 9.6.0) from causing version mismatches.
+  def pin_shakapacker_npm_version(dir) # rubocop:disable Metrics/CyclomaticComplexity
+    gem_version = shakapacker_gem_version_from_lockfile(dir)
+    return unless gem_version
+
+    package_json_path = File.join(dir, "package.json")
+    return unless File.exist?(package_json_path)
+
+    begin
+      package_json = JSON.parse(File.read(package_json_path))
+    rescue JSON::ParserError => e
+      puts "  ERROR: Failed to parse #{package_json_path}: #{e.message}"
+      raise
+    end
+
+    changed = false
+    %w[dependencies devDependencies].each do |section|
+      deps = package_json[section]
+      next unless deps&.key?("shakapacker")
+      next if deps["shakapacker"] == gem_version
+
+      puts "  Pinning npm shakapacker in #{section} from #{deps['shakapacker']} to exact #{gem_version}"
+      deps["shakapacker"] = gem_version
+      changed = true
+    end
+
+    File.write(package_json_path, "#{JSON.pretty_generate(package_json)}\n") if changed
+  end
+
+  # Reads the shakapacker gem version from the example app's Gemfile.lock
+  def shakapacker_gem_version_from_lockfile(dir)
+    lockfile = File.join(dir, "Gemfile.lock")
+    return unless File.exist?(lockfile)
+
+    match = File.read(lockfile).match(/^\s+shakapacker\s+\(([^)]+)\)/)
+    match&.[](1)
+  end
+
   # Updates React-related dependencies to a specific version
   def update_react_dependencies(deps, react_version)
     return unless deps
@@ -110,9 +149,11 @@ namespace :shakapacker_examples do # rubocop:disable Metrics/BlockLength
         apply_react_version(example_type.dir, example_type.react_version_string)
         # Re-run bundle install to ensure dependencies are resolved correctly
         bundle_install_in(example_type.dir)
-        # Run npm install BEFORE shakapacker:binstubs to ensure the npm shakapacker version
-        # matches the gem version. The binstubs task loads the Rails environment which
-        # validates version matching between gem and npm package.
+        # Pin the npm shakapacker version to exactly match the installed gem version.
+        # shakapacker:install may add "^X.Y.Z" to package.json, which allows npm to
+        # resolve a newer minor version (e.g., 9.6.0 when gem is 9.5.0), causing
+        # Shakapacker's gem/npm version consistency check to fail.
+        pin_shakapacker_npm_version(example_type.dir)
         # Use --legacy-peer-deps to avoid peer dependency conflicts when
         # react-on-rails expects newer React versions
         # Use --install-links to copy file: dependencies instead of symlinking,
@@ -122,6 +163,11 @@ namespace :shakapacker_examples do # rubocop:disable Metrics/BlockLength
         # The binstub format may differ between major versions
         unbundled_sh_in_dir(example_type.dir, "bundle exec rake shakapacker:binstubs")
       else
+        # Pin the npm shakapacker version to exactly match the installed gem version.
+        # shakapacker:install may add "^X.Y.Z" to package.json, which allows npm to
+        # resolve a newer minor version (e.g., 9.6.0 when gem is 9.5.0), causing
+        # Shakapacker's gem/npm version consistency check to fail.
+        pin_shakapacker_npm_version(example_type.dir)
         # Use --install-links to copy file: dependencies instead of symlinking,
         # preventing duplicate React instances from webpack resolving through symlinks
         sh_in_dir(example_type.dir, "npm install --install-links")

react_on_rails/spec/react_on_rails/shakapacker_examples_rake_spec.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative "spec_helper"
+require_relative "../../rakelib/example_type"
+require "json"
+require "rake"
+require "tmpdir"
+
+RSpec.describe "shakapacker_examples rake helpers" do
+  let(:rake_file) { File.expand_path("../../rakelib/shakapacker_examples.rake", __dir__) }
+  let(:task_context) { TOPLEVEL_BINDING.eval("self") }
+
+  describe "#pin_shakapacker_npm_version" do
+    before do
+      Rake::Task.clear
+      allow(ReactOnRails::TaskHelpers::ExampleType).to receive(:all).and_return({ shakapacker_examples: [] })
+      load rake_file
+    end
+
+    it "pins shakapacker in both dependency sections" do
+      Dir.mktmpdir do |dir|
+        File.write(File.join(dir, "Gemfile.lock"), "    shakapacker (9.5.0)\n")
+        File.write(
+          File.join(dir, "package.json"),
+          <<~JSON
+            {
+              "dependencies": {
+                "shakapacker": "^9.5.0"
+              },
+              "devDependencies": {
+                "shakapacker": "~9.5.0"
+              }
+            }
+          JSON
+        )
+
+        task_context.send(:pin_shakapacker_npm_version, dir)
+
+        package_json = JSON.parse(File.read(File.join(dir, "package.json")))
+        expect(package_json.dig("dependencies", "shakapacker")).to eq("9.5.0")
+        expect(package_json.dig("devDependencies", "shakapacker")).to eq("9.5.0")
+      end
+    end
+
+    it "reads prerelease shakapacker gem versions from Gemfile.lock" do
+      Dir.mktmpdir do |dir|
+        File.write(File.join(dir, "Gemfile.lock"), "    shakapacker (9.6.0.beta.0)\n")
+
+        gem_version = task_context.send(:shakapacker_gem_version_from_lockfile, dir)
+
+        expect(gem_version).to eq("9.6.0.beta.0")
+      end
+    end
+  end
+
+  describe "pinned React example generation" do
+    let(:example_dir) { "/tmp/example-app" }
+    let(:example_type) do
+      instance_double(
+        ReactOnRails::TaskHelpers::ExampleType,
+        dir: example_dir,
+        name: "example-app",
+        name_pretty: "example-app example app",
+        rails_options: "--skip-bundle",
+        gemfile: "#{example_dir}/Gemfile",
+        generator_shell_commands: ["rails generate react_on_rails:install"],
+        pinned_react_version?: true,
+        react_version_string: "18.0.0",
+        clobber_task_name_short: "clobber_example_app",
+        clobber_task_name: "shakapacker_examples:clobber_example_app",
+        gen_task_name_short: "gen_example_app",
+        gen_task_name: "shakapacker_examples:gen_example_app"
+      )
+    end
+
+    before do
+      Rake::Task.clear
+      allow(ReactOnRails::TaskHelpers::ExampleType).to receive(:all).and_return(
+        { shakapacker_examples: [example_type] }
+      )
+      load rake_file
+
+      allow(task_context).to receive(:puts)
+      allow(task_context).to receive(:mkdir_p)
+      allow(task_context).to receive(:rm_rf)
+      allow(task_context).to receive(:sh_in_dir)
+      allow(task_context).to receive(:unbundled_sh_in_dir)
+      allow(task_context).to receive(:apply_react_version)
+    end
+
+    it "pins shakapacker after the pinned React branch bundle install and before npm install" do
+      bundle_install_calls = 0
+
+      allow(task_context).to receive(:bundle_install_in) do |_dir|
+        bundle_install_calls += 1
+      end
+
+      expect(task_context).to receive(:pin_shakapacker_npm_version).with(example_dir).ordered do
+        expect(bundle_install_calls).to eq(3)
+      end
+      expect(task_context).to receive(:sh_in_dir)
+        .with(example_dir, "npm install --legacy-peer-deps --install-links")
+        .ordered
+
+      Rake::Task["shakapacker_examples:gen_example_app"].invoke
+    end
+  end
+end