Improve fresh Pro install docs and generator defaults

docs/getting-started/installation-into-an-existing-rails-app.md

@@ -4,38 +4,43 @@
 
 **If you have Rails 5 API only project**, first [convert the Rails 5 API only app to a normal Rails app](../migrating/convert-rails-5-api-only-app.md).
 
-1. Add the following to your Gemfile and `bundle install`. We recommend fixing the version of React on Rails, as you will need to keep the exact version in sync with the version in your `package.json` file.
+1. Add the following to your Gemfile and run `bundle install`.
+   We recommend fixing exact versions, as the gem and npm package versions should stay in sync.
+   For pre-release versions, gems use periods (for example, `16.4.0.rc.5`) and npm packages use dashes
+   (for example, `16.4.0-rc.5`).
 
    ```ruby
-   gem "shakapacker", "7.0.1"     # Use the latest and the exact version
-   gem "react_on_rails", "13.3.1" # Use the latest and the exact version
+   gem "shakapacker", "<shakapacker_version>"
+   gem "react_on_rails", "<react_on_rails_gem_version>"
    ```
 
    Or use `bundle add`:
 
    ```bash
-   bundle add shakapacker --version=7.0.1 --strict
-   bundle add react_on_rails --version=13.3.1 --strict
+   bundle add shakapacker --version="<shakapacker_version>" --strict
+   bundle add react_on_rails --version="<react_on_rails_gem_version>" --strict
    ```
 
-2. Run the following 2 commands to install Shakapacker with React. Note, if you are using an older version of Rails than 5.1, you'll need to install Webpacker with React per the instructions [here](https://github.com/rails/webpacker).
+2. Run the following command to install Shakapacker with React. Note, if you are using an older version of
+   Rails than 5.1, you'll need to install Webpacker with React per the instructions
+   [here](https://github.com/rails/webpacker).
 
    ```bash
-   rails shakapacker:install
+   bundle exec rails shakapacker:install
    ```
 
 3. Commit this to git (or else you cannot run the generator unless you pass the option `--ignore-warnings`).
 
 4. Run the generator with a simple "Hello World" example (more options below):
 
    ```bash
-   rails generate react_on_rails:install
+   bundle exec rails generate react_on_rails:install
    ```
 
    For more information about this generator use `--help` option:
 
    ```bash
-   rails generate react_on_rails:install --help
+   bundle exec rails generate react_on_rails:install --help
    ```
 
 5. Ensure that you have `overmind` or `foreman` installed.
@@ -48,7 +53,11 @@
    ./bin/dev
    ```
 
-   Note: `foreman` defaults to PORT 5000 unless you set the value of PORT in your environment. For example, you can `export PORT=3000` to use the Rails default port of 3000. For the hello_world example, this is already set.
+   If port 3000 is already in use, set an explicit port:
+
+   ```bash
+   PORT=3001 ./bin/dev
+   ```
 
 7. Visit [localhost:3000/hello_world](http://localhost:3000/hello_world).
 

packages/react-on-rails-pro-node-renderer/src/worker/vm.ts

@@ -192,7 +192,13 @@ export async function buildVM(filePath: string) {
     return Promise.resolve(true);
   }
 
-  // Create a new promise for this VM creation
+  // Create the VM creation promise. The IIFE runs synchronously until its first
+  // `await`, so we must store it in the map immediately after creation — before
+  // the microtask queue is drained — to prevent concurrent callers from starting
+  // a duplicate build. Cleanup uses `.finally()` on the stored promise rather
+  // than a try/finally inside the IIFE, because an IIFE's finally block can
+  // execute synchronously (before `vmCreationPromises.set`) when the code throws
+  // before the first `await`, which would leave a stale rejected promise in the map.
   const vmCreationPromise = (async () => {
     try {
       const { supportModules, stubTimers, additionalContext } = getConfig();
@@ -335,15 +341,22 @@ export async function buildVM(filePath: string) {
       log.error({ error }, 'Caught Error when creating context in buildVM');
       errorReporter.error(error as Error);
       throw error;
-    } finally {
-      // Always remove the promise from the map when done
-      vmCreationPromises.delete(filePath);
     }
   })();
 
-  // Store the promise
+  // Store the promise BEFORE any async work completes, so concurrent callers
+  // find it via the has() check above.
   vmCreationPromises.set(filePath, vmCreationPromise);
 
+  // Remove from the map after the promise settles. Using .finally() on the
+  // stored promise guarantees this runs after set(), unlike a try/finally
+  // inside the IIFE which can run synchronously before set() on sync throws.
+  void vmCreationPromise
+    .catch(() => {})
+    .finally(() => {
+      vmCreationPromises.delete(filePath);
+    });
+
   return vmCreationPromise;
 }
 

packages/react-on-rails-pro-node-renderer/tests/vm.test.ts

@@ -542,6 +542,22 @@ describe('buildVM and runInVM', () => {
       expect(vmContext1).toBe(vmContext2);
     });
 
+    test('buildVM recovers after failure for nonexistent bundle', async () => {
+      const config = getConfig();
+      config.supportModules = true;
+      config.stubTimers = false;
+
+      const nonExistentPath = path.resolve(__dirname, './tmp/nonexistent-bundle.js');
+
+      // First call should fail because the bundle file does not exist
+      await expect(buildVM(nonExistentPath)).rejects.toThrow();
+
+      // After failure, the vmCreationPromises map should be cleaned up,
+      // allowing a retry with the correct path to succeed
+      await buildVM(serverBundlePath);
+      expect(hasVMContextForBundle(serverBundlePath)).toBeTruthy();
+    });
+
     test('running runInVM before buildVM', async () => {
       resetVM();
       void prepareVM(true);

react_on_rails/lib/generators/react_on_rails/base_generator.rb

@@ -130,6 +130,10 @@ def copy_packer_config
         # Always ensure precompile_hook is configured (Shakapacker 9.0+ only)
         # This handles all scenarios: fresh install, pre-installed Shakapacker, or user declined overwrite
         configure_precompile_hook_in_shakapacker
+
+        # For SSR bundles, configure Shakapacker private_output_path (9.0+ only)
+        # This keeps Shakapacker and React on Rails server bundle paths in sync.
+        configure_private_output_path_in_shakapacker
       end
 
       def add_base_gems_to_gemfile
@@ -362,6 +366,38 @@ def configure_precompile_hook_in_shakapacker
 
         puts Rainbow("✅ Configured precompile_hook in shakapacker.yml").green
       end
+
+      def configure_private_output_path_in_shakapacker
+        # private_output_path is only supported in Shakapacker 9.0+
+        return unless ReactOnRails::PackerUtils.shakapacker_version_requirement_met?("9.0.0")
+
+        shakapacker_config_path = "config/shakapacker.yml"
+        return unless File.exist?(shakapacker_config_path)
+
+        content = File.read(shakapacker_config_path)
+
+        # Already configured? Do nothing.
+        return if content.match?(/^\s*private_output_path:\s*\S+/)
+
+        # First try: uncomment an existing private_output_path placeholder line.
+        updated_content = content.sub(
+          /^(\s*)#\s*private_output_path:\s*.*$/,
+          "\\1private_output_path: ssr-generated"
+        )
+
+        # Fallback: insert directly after public_output_path in the default section.
+        if updated_content == content
+          updated_content = content.sub(
+            /^(\s*)public_output_path:\s*.*\n/,
+            "\\0\\1private_output_path: ssr-generated\n"
+          )
+        end
+
+        return if updated_content == content
+
+        File.write(shakapacker_config_path, updated_content)
+        puts Rainbow("✅ Configured private_output_path in shakapacker.yml").green
+      end
     end
   end
 end

react_on_rails/lib/generators/react_on_rails/templates/base/base/Procfile.dev

@@ -1,5 +1,5 @@
 # Procfile for development
 # You can run these commands in separate shells
-rails: bundle exec rails s -p 3000
+rails: bundle exec rails s -p ${PORT:-3000}
 dev-server: bin/shakapacker-dev-server
 server-bundle: SERVER_BUNDLE_ONLY=yes bin/shakapacker --watch

react_on_rails/lib/generators/react_on_rails/templates/base/base/Procfile.dev-prod-assets

@@ -2,7 +2,7 @@
 # Uses production-optimized, precompiled assets with development environment
 # Uncomment additional processes as needed for your app
 
-rails: bundle exec rails s -p 3001
+rails: bundle exec rails s -p ${PORT:-3001}
 # sidekiq: bundle exec sidekiq -C config/sidekiq.yml
 # redis: redis-server
 # mailcatcher: mailcatcher --foreground

react_on_rails/lib/generators/react_on_rails/templates/base/base/Procfile.dev-static-assets

@@ -1,2 +1,2 @@
-web: bin/rails server -p 3000
+web: bin/rails server -p ${PORT:-3000}
 js: bin/shakapacker --watch

react_on_rails/spec/react_on_rails/generators/install_generator_spec.rb

@@ -181,6 +181,7 @@
             source_entry_path: packs
             public_root_path: public
             public_output_path: packs
+            # private_output_path: ssr-generated
             cache_path: tmp/shakapacker
             webpack_compile_output: true
             shakapacker_precompile: true
@@ -221,6 +222,17 @@
       end
     end
 
+    it "configures private_output_path for SSR bundles on Shakapacker 9+" do
+      assert_file "config/shakapacker.yml" do |content|
+        if ReactOnRails::PackerUtils.shakapacker_version_requirement_met?("9.0.0")
+          expect(content).to include("private_output_path: ssr-generated")
+          expect(content).not_to match(/^\s*#\s*private_output_path:/)
+        else
+          expect(content).to match(/^\s*#\s*private_output_path:/)
+        end
+      end
+    end
+
     it "preserves other shakapacker.yml settings and comments" do
       assert_file "config/shakapacker.yml" do |content|
         # Comments should be preserved
@@ -341,6 +353,14 @@
       end
     end
 
+    it "adds private_output_path on Shakapacker 9+ when missing" do
+      assert_file "config/shakapacker.yml" do |content|
+        if ReactOnRails::PackerUtils.shakapacker_version_requirement_met?("9.0.0")
+          expect(content).to include("private_output_path: ssr-generated")
+        end
+      end
+    end
+
     it "preserves YAML structure in shakapacker.yml" do
       assert_file "config/shakapacker.yml" do |content|
         # YAML anchors should be preserved

react_on_rails_pro/docs/installation.md

@@ -8,7 +8,8 @@ Check the [CHANGELOG](https://github.com/shakacode/react_on_rails/blob/master/CH
 
 ## Version Format
 
-For the below docs, find the desired `<version>` in the CHANGELOG. Note that for pre-release versions:
+For the commands below, choose versions from the CHANGELOG and replace placeholders like
+`<gem_version>` and `<npm_version>`. Note that for pre-release versions:
 
 - Gems use all periods: `16.2.0.beta.1`
 - NPM packages use dashes: `16.2.0-beta.1`
@@ -22,11 +23,15 @@ The easiest way to set up React on Rails Pro is using the generator. This automa
 For new React on Rails apps, use the `--pro` flag:
 
 ```bash
-# Add the Pro gem to your Gemfile first
-bundle add react_on_rails_pro
+# Add the Pro gem first (pin exact version)
+bundle add react_on_rails_pro --version="<gem_version>" --strict
+
+# The generator requires a clean git working tree
+git add .
+git commit -m "Prepare app for React on Rails Pro install"
 
 # Run the generator with --pro
-rails generate react_on_rails:install --pro
+bundle exec rails generate react_on_rails:install --pro
 ```
 
 This creates the Pro initializer, node-renderer.js, installs npm packages, and adds the Node Renderer to Procfile.dev.
@@ -37,17 +42,31 @@ For existing React on Rails apps, use the standalone Pro generator:
 
 ```bash
 # Add the Pro gem to your Gemfile
-bundle add react_on_rails_pro
+bundle add react_on_rails_pro --version="<gem_version>" --strict
 
 # Run the Pro generator
-rails generate react_on_rails:pro
+bundle exec rails generate react_on_rails:pro
 ```
 
 The standalone generator adds Pro-specific files and modifies your existing webpack configs (`serverWebpackConfig.js` and `ServerClientOrBoth.js`) to enable Pro features like `libraryTarget: 'commonjs2'` and `target = 'node'`.
 
 ## After Running the Generator
 
-You still need to configure your license. Set the environment variable:
+Run a quick validation, then configure your license.
+
+```bash
+bundle exec rails react_on_rails:doctor
+bin/shakapacker
+bin/dev
+```
+
+If port 3000 is already in use:
+
+```bash
+PORT=3001 bin/dev
+```
+
+Set the license environment variable:
 
 ```bash
 export REACT_ON_RAILS_PRO_LICENSE="your-license-token-here"
@@ -61,10 +80,10 @@ RSC requires React on Rails Pro and React 19.0.x. To add RSC support, use `--rsc
 
 ```bash
 # Fresh install with RSC
-rails generate react_on_rails:install --rsc
+bundle exec rails generate react_on_rails:install --rsc
 
 # Or add RSC to existing Pro app
-rails generate react_on_rails:rsc
+bundle exec rails generate react_on_rails:rsc
 ```
 
 The RSC generator creates `rscWebpackConfig.js`, adds `RSCWebpackPlugin` to both server and client webpack configs, configures `RSC_BUNDLE_ONLY` handling in `ServerClientOrBoth.js`, and sets up the RSC bundle watcher process. See [React Server Components](./react-server-components/tutorial.md) for more information.
@@ -86,7 +105,7 @@ Ensure your **Rails** app is using the **react_on_rails** gem, version 16.0.0 or
 Add the `react_on_rails_pro` gem to your **Gemfile**:
 
 ```ruby
-gem "react_on_rails_pro", "~> 16.2"
+gem "react_on_rails_pro", "= <gem_version>"
 ```
 
 Then run:
@@ -138,19 +157,19 @@ All React on Rails Pro users need to install the `react-on-rails-pro` npm packag
 ### Using npm:
 
 ```bash
-npm install react-on-rails-pro
+npm install react-on-rails-pro@<npm_version> --save-exact
 ```
 
 ### Using yarn:
 
 ```bash
-yarn add react-on-rails-pro
+yarn add react-on-rails-pro@<npm_version> --exact
 ```
 
 ### Using pnpm:
 
 ```bash
-pnpm add react-on-rails-pro
+pnpm add react-on-rails-pro@<npm_version> --save-exact
 ```
 
 ## Usage
@@ -187,21 +206,21 @@ See the [React Server Components tutorial](./react-server-components/tutorial.md
 ### Using npm:
 
 ```bash
-npm install react-on-rails-pro-node-renderer
+npm install react-on-rails-pro-node-renderer@<npm_version> --save-exact
 ```
 
 ### Using yarn:
 
 ```bash
-yarn add react-on-rails-pro-node-renderer
+yarn add react-on-rails-pro-node-renderer@<npm_version> --exact
 ```
 
 ### Add to package.json:
 
 ```json
 {
   "dependencies": {
-    "react-on-rails-pro-node-renderer": "^16.2.0"
+    "react-on-rails-pro-node-renderer": "<npm_version>"
   }
 }
 ```