Move Node Renderer entry point to renderer/ directory (#3165)

## Summary

Establishes `renderer/node-renderer.js` as the canonical location for
the Pro Node Renderer entry point. Previously the path was inconsistent
across docs (`node-renderer.js`, `client/node-renderer.js`, or
`react-on-rails-pro-node-renderer.js`).

Using a dedicated top-level `renderer/` directory also makes it trivial
to exclude from production Docker builds that strip JS sources after
bundling — the Node Renderer process still needs its entry file at
runtime.

## Changes

- **Generator** (`pro_setup.rb`, `base_generator.rb`,
`demo_page_config.rb`, `USAGE`, initializer template) now creates the
entry at `renderer/node-renderer.js`
- **Template file** moved to
`templates/pro/base/renderer/node-renderer.js`
- **Pro `spec/dummy`** — renderer file, `Procfile.dev`, `Procfile.prod`,
`package.json` scripts, `.controlplane/rails.yml`, and
`benchmarks/bench-node-renderer.rb` updated
- **All 13 docs** now use `renderer/node-renderer.js` consistently; the
Docker-cleanup rationale is added to the container deployment guide
- **Generator specs** updated; 13 renderer-related examples pass

Existing apps are unaffected — the generator skips files that already
exist, so upgrades keep their current `client/node-renderer.js`.

## Test plan

- [x] `rubocop` passes on all changed Ruby files
- [x] `prettier --check` passes on all changed docs + JS
- [x] Renderer-related generator specs all pass (`rspec ... --example
"creates node-renderer" --example "adds node-renderer process" --example
"does not overwrite existing"`, 13 examples)
- [x] Full `pro_generator_spec.rb` passes (79 examples)
- [x] Link-check (`lychee`) passes on all modified docs
- [ ] Review rendered markdown

Fixes #3073

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Moderate risk because it changes the Pro generator’s output paths and
Procfile wiring for SSR, which could break dev/prod startup if projects
rely on the old `client/node-renderer.js` location or have customized
Procfiles.
> 
> **Overview**
> **Pro installs now standardize the Node Renderer entrypoint at
`renderer/node-renderer.js`** (instead of `client/node-renderer.js`),
including updated generator hints, initializer comments, and a new
template under `templates/pro/base/renderer/`.
> 
> The Pro generator adds safer upgrade behavior: it detects an existing
legacy `client/node-renderer.js`, avoids overwriting it, conditionally
skips/avoids duplicating `Procfile.dev` entries, and emits targeted
warnings when a Procfile still points at the legacy path.
> 
> Docs, dummy app scripts/Procfiles, deployment examples
(Docker/K8s/Heroku), benchmarks, and generator specs are updated to
reference the new `renderer/` path consistently, with added
documentation explaining the Docker build rationale.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
20633e7. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

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

* **Changed**
* Pro generator now places the Node renderer in a dedicated top-level
renderer directory, preserves existing legacy renderer files, and adds a
configurable server-bundle cache location.
* **Documentation**
* Updated guides, examples, deployment and profiling docs, and sample
startup scripts to reference the new renderer location.
* **Tests**
* Added/updated generator tests to cover legacy vs. new renderer
presence and Procfile/script handling.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: justin808

CHANGELOG.md

@@ -24,6 +24,10 @@ After a release, run `/update-changelog` in Claude Code to analyze commits, writ
 
 ### [Unreleased]
 
+#### Changed
+
+- **[Pro]** **Pro generator now creates the Node Renderer at `renderer/node-renderer.js`**: The canonical location for the Node Renderer entry point is now a dedicated top-level `renderer/` directory instead of `client/`, making it straightforward to exclude from production Docker builds that strip JS sources after bundling. Docs and Pro `spec/dummy` now use the new path consistently. Existing apps are unaffected — the generator skips files that already exist (including a legacy `client/node-renderer.js`). Fixes [Issue 3073](https://github.com/shakacode/react_on_rails/issues/3073). [PR 3165](https://github.com/shakacode/react_on_rails/pull/3165) by [justin808](https://github.com/justin808).
+
 #### Fixed
 
 - **Client startup now recovers if initialization begins during `interactive` after `DOMContentLoaded` already fired**: React on Rails now still initializes the page when the client bundle starts in the browser timing window after `DOMContentLoaded` but before the document reaches `complete`. Fixes [Issue 3150](https://github.com/shakacode/react_on_rails/issues/3150). [PR 3151](https://github.com/shakacode/react_on_rails/pull/3151) by [ihabadham](https://github.com/ihabadham).

benchmarks/bench-node-renderer.rb

@@ -23,7 +23,7 @@ def read_protocol_version
 
 def read_password_from_config
   config_path = File.expand_path(
-    "../react_on_rails_pro/spec/dummy/client/node-renderer.js",
+    "../react_on_rails_pro/spec/dummy/renderer/node-renderer.js",
     __dir__
   )
   config_content = File.read(config_path)

docs/oss/api-reference/generator-details.md

@@ -50,7 +50,7 @@ can pass the redux option if you'd like to have redux setup for you automaticall
     Passing the --pro generator option sets up React on Rails Pro with Node
     server rendering, fragment caching, and code-splitting support.
     Requires the react_on_rails_pro gem (add it to your Gemfile first).
-    Creates the Pro initializer, node-renderer.js, and adds the Node Renderer
+    Creates the Pro initializer, renderer/node-renderer.js, and adds the Node Renderer
     process to Procfile.dev.
 
 * RSC (React Server Components)
@@ -215,7 +215,7 @@ rails generate react_on_rails:install --pro
 **What gets created:**
 
 - `config/initializers/react_on_rails_pro.rb` - Pro configuration with Node Renderer settings
-- `client/node-renderer.js` - Node Renderer bootstrap file
+- `renderer/node-renderer.js` - Node Renderer bootstrap file
 - Node Renderer process added to `Procfile.dev`
 - Pro npm packages (`react-on-rails-pro`, `react-on-rails-pro-node-renderer`)
 

docs/oss/building-features/code-splitting.md

@@ -252,7 +252,7 @@ in your webpack configuration. That turns off the polyfills for things like `__d
 
 ### Node Renderer
 
-In your `node-renderer.js` file which runs node renderer, you need to specify `supportModules` options as follows:
+In your `renderer/node-renderer.js` file which runs node renderer, you need to specify `supportModules` options as follows:
 
 ```js
 const path = require('path');

docs/oss/building-features/node-renderer/basics.md

@@ -27,7 +27,7 @@ See the [Memory Leaks guide](../../../pro/js-memory-leaks.md) for common leak pa
 
 **node-renderer** is a standalone Node application to serve React SSR requests from a **Rails** client. You don't need any **Ruby** code to setup and launch it. You can configure with the command line or with a launch file.
 
-> **Generator shortcut:** Running `rails generate react_on_rails:install --pro` (or `rails generate react_on_rails:pro` for existing apps) automatically creates `client/node-renderer.js`, adds the Node Renderer process to `Procfile.dev`, and installs the required npm packages. See [Installation](../../../pro/installation.md) for details. The manual setup below is for apps that need custom configuration.
+> **Generator shortcut:** Running `rails generate react_on_rails:install --pro` (or `rails generate react_on_rails:pro` for existing apps) automatically creates `renderer/node-renderer.js`, adds the Node Renderer process to `Procfile.dev`, and installs the required npm packages. See [Installation](../../../pro/installation.md) for details. The manual setup below is for apps that need custom configuration.
 
 ## Simple Command Line for node-renderer
 
@@ -65,7 +65,7 @@ For the most control over the setup, create a JavaScript file to start the NodeR
    # or: yarn add react-on-rails-pro-node-renderer
    # or: bun add react-on-rails-pro-node-renderer
    ```
-4. Configure a JavaScript file that will launch the rendering server per the docs in [Node Renderer JavaScript Configuration](./js-configuration.md). For example, create a file `node-renderer.js`. Here is a simple example that uses all the defaults except for serverBundleCachePath:
+4. Configure a JavaScript file that will launch the rendering server per the docs in [Node Renderer JavaScript Configuration](./js-configuration.md). For example, create a file `renderer/node-renderer.js`. Here is a simple example that uses all the defaults except for serverBundleCachePath:
 
    ```javascript
    import path from 'path';
@@ -78,7 +78,7 @@ For the most control over the setup, create a JavaScript file to start the NodeR
    reactOnRailsProNodeRenderer(config);
    ```
 
-5. Now you can launch your renderer server with `node node-renderer.js`. You will probably add a script to your `package.json`.
+5. Now you can launch your renderer server with `node renderer/node-renderer.js`. You will probably add a script to your `package.json`.
 6. You can use a command line argument of `-p SOME_PORT` to override any configured or ENV value for the port.
 
 ## Setup Rails Application
@@ -164,7 +164,7 @@ jobs:
     steps:
       - name: Start Node Renderer
         run: |
-          node client/node-renderer.js &
+          node renderer/node-renderer.js &
           # Wait for the renderer to be ready.
           # The renderer uses cleartext HTTP/2 (h2c), so use --http2-prior-knowledge for the probe.
           # --max-time 2 prevents hangs if the port is open but the process is stalled.

docs/oss/building-features/node-renderer/container-deployment.md

@@ -131,6 +131,8 @@ end
 
 ## Dockerfile Example
 
+> **Why the renderer entry point lives in a dedicated `renderer/` directory:** Production Docker builds commonly strip JavaScript sources after the client bundles are built, since the Rails app no longer needs them at runtime. Keeping the renderer entry point in its own top-level directory (separate from `client/`) makes it trivial to exclude from that cleanup — the Node Renderer process still needs its entry file and dependencies at runtime.
+
 A minimal Dockerfile that bundles Rails and the Node Renderer in a single image:
 
 ```dockerfile
@@ -175,10 +177,10 @@ For the single-container pattern, use a process manager like [overmind](https://
 ```text
 # Procfile
 rails: bundle exec rails server -b 0.0.0.0 -p 3000
-renderer: node client/node-renderer.js
+renderer: node renderer/node-renderer.js
 ```
 
-> **Tip:** For sidecar containers, use the same image but override the `CMD` — one container runs `bundle exec rails server`, the other runs `node client/node-renderer.js` (or your Node Renderer entry point).
+> **Tip:** For sidecar containers, use the same image but override the `CMD` — one container runs `bundle exec rails server`, the other runs `node renderer/node-renderer.js` (or your Node Renderer entry point).
 
 ## Docker Compose Example
 
@@ -199,7 +201,7 @@ services:
 
   renderer:
     build: .
-    command: node client/node-renderer.js
+    command: node renderer/node-renderer.js
     ports:
       - '3800:3800'
     environment:
@@ -220,7 +222,7 @@ services:
 By default, the Node Renderer binds to `localhost`. For **sidecar containers** in the same Kubernetes pod, that works because the containers share a network namespace. For **separate workloads** or Docker Compose setups without shared networking, bind to `0.0.0.0`:
 
 ```javascript
-// node-renderer.js
+// renderer/node-renderer.js
 import { reactOnRailsProNodeRenderer } from 'react-on-rails-pro-node-renderer';
 
 const config = {
@@ -488,7 +490,7 @@ spec:
 
         - name: node-renderer
           image: your-app:latest # Same image as Rails
-          command: ['node', 'client/node-renderer.js']
+          command: ['node', 'renderer/node-renderer.js']
           ports:
             - containerPort: 3800
           env:

docs/oss/building-features/node-renderer/debugging.md

@@ -63,7 +63,7 @@ Use Node's built-in flag to write heap snapshots on demand:
 ```bash
 cd react_on_rails_pro/spec/dummy
 # Adjust the port if your Rails app points at a different renderer URL.
-NODE_OPTIONS="--heapsnapshot-signal=SIGUSR2" RENDERER_PORT=3800 node client/node-renderer.js
+NODE_OPTIONS="--heapsnapshot-signal=SIGUSR2" RENDERER_PORT=3800 node renderer/node-renderer.js
 ```
 
 Then capture snapshots at different times:

docs/oss/building-features/node-renderer/heroku.md

@@ -46,7 +46,7 @@ Define the script in your root `package.json` so Heroku can run it from the app
 ```json
 {
   "scripts": {
-    "node-renderer": "node client/node-renderer.js"
+    "node-renderer": "node renderer/node-renderer.js"
   }
 }
 ```

docs/oss/building-features/node-renderer/js-configuration.md

@@ -58,12 +58,12 @@ Deprecated options:
 
 ### Testing example:
 
-[spec/dummy/client/node-renderer.js](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails_pro/spec/dummy/client/node-renderer.js)
+[react_on_rails_pro/spec/dummy/renderer/node-renderer.js](../../../../react_on_rails_pro/spec/dummy/renderer/node-renderer.js)
 
 ### Simple example:
 
-Create a file `client/node-renderer.js`. The generator uses this filename and CommonJS syntax so
-the file runs directly with `node client/node-renderer.js` without extra ESM configuration.
+Create a file `renderer/node-renderer.js`. The generator uses this filename and CommonJS syntax so
+the file runs directly with `node renderer/node-renderer.js` without extra ESM configuration.
 
 ```js
 const path = require('path');
@@ -94,7 +94,7 @@ And add a root-level script to the `scripts` section of your `package.json`
 
 ```json
   "scripts": {
-    "node-renderer": "node client/node-renderer.js"
+    "node-renderer": "node renderer/node-renderer.js"
   },
 ```
 
@@ -113,7 +113,7 @@ For advanced use cases, you can customize the Fastify server instance by importi
 When running the node-renderer in Docker or Kubernetes, you may need a `/health` endpoint for container health checks:
 
 The advanced examples below use ES modules for readability. If you want this file to keep running
-as `node client/node-renderer.js`, either keep using the CommonJS pattern shown in the simple
+as `node renderer/node-renderer.js`, either keep using the CommonJS pattern shown in the simple
 example above or switch the file to `.mjs` or `"type": "module"`.
 
 ```js

docs/oss/deployment/docker-deployment.md

@@ -411,7 +411,7 @@ containers:
 
   - name: node-renderer
     image: your-registry/myapp-node-renderer:latest # must include Node.js
-    command: ['node', 'node-renderer.js']
+    command: ['node', 'renderer/node-renderer.js']
     ports:
       - containerPort: 3800
     env: