fix: use env-var-driven ports in Procfile templates to support multiple worktrees

docs/building-features/process-managers.md

@@ -327,11 +327,35 @@ Edit `Procfile.dev` in your project root to customize which processes run and th
 The default `Procfile.dev` includes:
 
 ```procfile
-rails: bundle exec rails s -p 3000
+rails: bundle exec rails s -p ${PORT:-3000}
 wp-client: bin/shakapacker-dev-server
 wp-server: SERVER_BUNDLE_ONLY=true bin/shakapacker --watch
 ```
 
+## Running Multiple Worktrees Simultaneously
+
+If you use [git worktrees](https://git-scm.com/docs/git-worktree) to work on multiple branches in parallel, each worktree's `bin/dev` will conflict on the default ports (3000 for Rails, 3035 for webpack-dev-server).
+
+Create a `.env` file in each worktree (gitignored by default in Rails apps). Both foreman and overmind read `.env` automatically on startup.
+
+The generated `Procfile.dev` uses `${PORT:-3000}`, so setting `PORT` is enough for Rails. For the webpack dev server, Shakapacker reads `SHAKAPACKER_DEV_SERVER_PORT` natively on both the Ruby proxy and the webpack-dev-server JS sides — no `shakapacker.yml` changes needed.
+
+**Worktree 1** — use defaults (no `.env` needed), or set explicitly:
+
+```sh
+PORT=3000
+SHAKAPACKER_DEV_SERVER_PORT=3035
+```
+
+**Worktree 2 `.env`:**
+
+```sh
+PORT=3001
+SHAKAPACKER_DEV_SERVER_PORT=3036
+```
+
+A `.env.example` is generated by `rails g react_on_rails:install` as a starting point. Copy it to `.env` and adjust ports as needed.
+
 ## See Also
 
 - [HMR and Hot Reloading](./hmr-and-hot-reloading-with-the-webpack-dev-server.md)

react_on_rails/lib/generators/react_on_rails/base_generator.rb

@@ -59,6 +59,7 @@ def copy_base_files
                         Procfile.dev-static-assets
                         Procfile.dev-prod-assets
                         .dev-services.yml.example
+                        .env.example
                         bin/shakapacker-precompile-hook]
 
         # HelloServer uses the hello_world layout so React on Rails can inject generated

react_on_rails/lib/generators/react_on_rails/templates/base/base/.env.example

@@ -0,0 +1,18 @@
+# Development environment configuration
+# Copy this file to .env to override default ports.
+#
+# This is especially useful when running multiple git worktrees simultaneously.
+# Each worktree needs its own .env with different ports to avoid conflicts.
+#
+# Shakapacker reads SHAKAPACKER_DEV_SERVER_PORT on both the Ruby (proxy) and
+# JS (webpack-dev-server) sides, so no shakapacker.yml changes are needed.
+#
+# Example for a second worktree:
+#   PORT=3001
+#   SHAKAPACKER_DEV_SERVER_PORT=3036
+
+# Rails server port (default: 3000, used by Procfile.dev)
+# PORT=3000
+
+# Webpack dev server port (default: 3035, used by shakapacker)
+# SHAKAPACKER_DEV_SERVER_PORT=3035

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

@@ -1,5 +1,9 @@
 # Procfile for development
 # You can run these commands in separate shells
-rails: bundle exec rails s -p 3000
+#
+# To run multiple worktrees simultaneously, set different ports in each worktree's .env:
+#   PORT=3001
+#   SHAKAPACKER_DEV_SERVER_PORT=3036
+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/support/shared_examples/base_generator_examples.rb

@@ -15,7 +15,16 @@
        config/initializers/react_on_rails.rb
        Procfile.dev
        Procfile.dev-static-assets
-       Procfile.dev-prod-assets].each { |file| assert_file(file) }
+       Procfile.dev-prod-assets
+       .env.example].each { |file| assert_file(file) }
+  end
+
+  it "uses env-var-driven port in Procfile.dev" do
+    assert_file "Procfile.dev", /\$\{PORT:-3000\}/
+  end
+
+  it "uses env-var-driven port in Procfile.dev-static-assets" do
+    assert_file "Procfile.dev-static-assets", /\$\{PORT:-3000\}/
   end
 end