Trim over-verbose comments across Sub-PR 2 files

Per the repo's CLAUDE.md guidance ("default to writing no comments;
only when the WHY is non-obvious"), stripping comments that explain
WHAT the code does or reference the current-PR context.

Kept (non-obvious WHYs): the `additionalContext: { URL, AbortController }`
reason (react-router-dom NavLink url-is-not-defined), the CI worker-count
cap reason, `clientReferences` scoping rationale, `libraryTarget:
'commonjs2'` requirement for the renderer, `target: 'node'` fix for
SSR-breaking libs, the renderer-fallback-disabled reason, the
renderer-password-must-match pointer, the bundler-utils dual-support
blurb, and the shakapacker.yml tactical-reversal tag.

Dropped (WHAT explanations, redundant with identifiers): JSDoc blocks
describing `configureServer` and `extractLoader`, per-config-key
descriptions in the renderer launcher, Procfile.dev process-purpose
comment, verbose `.env.example` prose, initializer multi-line
explanations of each field.

No code changes — comments only.

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

Author: ihabadham

.env.example

@@ -1,18 +1,11 @@
-# React on Rails Pro license — required in production.
-# Issue a license at https://pro.reactonrails.com/ and paste the JWT token below.
-# Not required in development or test (the Pro engine logs an info notice and
-# continues). Don't commit the real token — copy this file to `.env`, which is
-# gitignored.
+# React on Rails Pro license (JWT token from https://pro.reactonrails.com/).
+# Required in production; optional in development/test.
 REACT_ON_RAILS_PRO_LICENSE=
 
-# Shared secret between the Rails app and the Node renderer. Must match
-# config.renderer_password in config/initializers/react_on_rails_pro.rb.
-# In production, set this to a strong random value via your secret store.
-# In development, both the renderer and the initializer default to
-# `local-dev-renderer-password` so `bin/dev` works without any setup.
+# Shared secret between Rails and the Node renderer. Must match on both sides.
+# Dev/test default to `local-dev-renderer-password` if unset; production must
+# set this explicitly (Pro raises at boot otherwise).
 RENDERER_PASSWORD=
 
-# Node renderer HTTP endpoint. Defaults to http://localhost:3800 in
-# development (where Procfile.dev runs `node renderer/node-renderer.js`).
-# Override in production to point at the deployed renderer host.
+# Node renderer endpoint. Defaults to http://localhost:3800.
 # REACT_RENDERER_URL=http://localhost:3800

Procfile.dev

@@ -12,5 +12,4 @@ rails: bundle exec thrust bin/rails server -p 3000
 wp-client: RAILS_ENV=development NODE_ENV=development bin/shakapacker-dev-server
 # Server webpack watcher for SSR bundle
 wp-server: SERVER_BUNDLE_ONLY=yes bin/shakapacker --watch
-# Pro Node renderer — executes the server bundle for SSR (port 3800)
 node-renderer: NODE_ENV=development node renderer/node-renderer.js

config/initializers/react_on_rails_pro.rb

@@ -1,24 +1,15 @@
 # frozen_string_literal: true
 
 # See https://reactonrails.com/docs/configuration/configuration-pro
-# Production license: set REACT_ON_RAILS_PRO_LICENSE to the JWT token from
-# https://pro.reactonrails.com/. Development and test environments don't
-# require a license — the Pro engine logs an info-level notice only.
+# License: Set REACT_ON_RAILS_PRO_LICENSE environment variable
 ReactOnRailsPro.configure do |config|
-  # Route all server rendering through the Pro Node renderer (port 3800).
-  # Falling back to ExecJS is disabled so any renderer issue surfaces loudly
-  # instead of silently degrading.
   config.server_renderer = "NodeRenderer"
+  # Raise loudly when the renderer is unavailable instead of silently
+  # degrading to ExecJS (default is true).
   config.renderer_use_fallback_exec_js = false
 
-  # Renderer HTTP endpoint. The Node renderer listens on localhost:3800 in
-  # development; override REACT_RENDERER_URL in production to point at the
-  # deployed renderer host.
   config.renderer_url = ENV.fetch("REACT_RENDERER_URL", "http://localhost:3800")
 
-  # Shared secret for renderer authentication. Must match renderer/node-renderer.js.
-  # In production-like envs, Pro's configuration.rb raises at boot if this is
-  # blank and RENDERER_PASSWORD isn't in the environment — so the dev fallback
-  # below never reaches prod as long as RENDERER_PASSWORD is set there.
+  # Must match the password in renderer/node-renderer.js.
   config.renderer_password = ENV.fetch("RENDERER_PASSWORD", "local-dev-renderer-password")
 end

config/webpack/bundlerUtils.js

@@ -1,18 +1,11 @@
-/**
- * Bundler utilities. Returns the active bundler module based on shakapacker.yml's
- * `assets_bundler` setting. Supports both webpack and rspack so this project can
- * switch between them without touching every config file.
- */
+// Returns the active bundler module per shakapacker.yml's `assets_bundler`.
+// Supports both webpack and rspack so this project can switch between them
+// without touching every config file.
 
 const { config } = require('shakapacker');
 
 let _cachedBundler = null;
 
-/**
- * Gets the bundler module for the current build.
- *
- * @returns {Object} webpack or @rspack/core module
- */
 const getBundler = () => {
   if (_cachedBundler) {
     return _cachedBundler;
@@ -23,20 +16,10 @@ const getBundler = () => {
   return _cachedBundler;
 };
 
-/**
- * Checks whether the configured bundler is Rspack.
- *
- * @returns {boolean} True when assets_bundler is rspack
- */
 const isRspack = () => config.assets_bundler === 'rspack';
 
-/**
- * Gets the CSS extraction plugin. Only meaningful on rspack — webpack projects
- * use mini-css-extract-plugin directly via shakapacker's generated config.
- *
- * @returns {Object} CssExtractRspackPlugin
- * @throws {Error} If assets_bundler is not rspack
- */
+// Only meaningful on rspack — webpack projects use mini-css-extract-plugin
+// via shakapacker's generated config.
 const getCssExtractPlugin = () => {
   if (!isRspack()) {
     throw new Error(

config/webpack/serverWebpackConfig.js

@@ -8,17 +8,6 @@ const { RSCWebpackPlugin } = require('react-on-rails-rsc/WebpackPlugin');
 const commonWebpackConfig = require('./commonWebpackConfig');
 const { getBundler } = require('./bundlerUtils');
 
-/**
- * Locates a loader in a rule's `use` array by loader name substring.
- *
- * Exposed on the module exports so rscWebpackConfig.js can call it when
- * deriving the RSC bundle from serverWebpackConfig(true). Matches the
- * `extractLoader` helper used in the Pro dummy and marketplace references.
- *
- * @param {Object} rule Webpack module rule with a `use` array
- * @param {string} loaderName Substring to match against each loader's name
- * @returns {Object|string|undefined} Matching loader entry, or undefined
- */
 function extractLoader(rule, loaderName) {
   if (!Array.isArray(rule.use)) return undefined;
   return rule.use.find((item) => {
@@ -27,26 +16,6 @@ function extractLoader(rule, loaderName) {
   });
 }
 
-/**
- * Generates the server-side rendering (SSR) bundle configuration for Pro's
- * Node renderer.
- *
- * Key Pro-specific settings (applied after shakapacker's generated config):
- * - target: 'node' + node: false — required for Node execution in the renderer
- * - libraryTarget: 'commonjs2' — required so the renderer can `require()` the bundle
- * - RSCWebpackPlugin({ isServer: true }) — emits the server manifest used by
- *   React Server Components (inert until RSC support is enabled in Sub-PR 3)
- * - babelLoader caller = { ssr: true } — lets Babel pick SSR-specific transforms
- * - CSS extraction disabled; css-loader switches to exportOnlyLocals for class
- *   name mapping only
- *
- * The `rscBundle` arg exists so Sub-PR 3's rscWebpackConfig.js can derive the
- * RSC bundle from this same config — when true, the server-manifest plugin is
- * skipped (the RSC bundle emits the client manifest instead).
- *
- * @param {boolean} [rscBundle=false] True when called from rscWebpackConfig.js
- * @returns {Object} Webpack configuration object for the SSR bundle
- */
 const configureServer = (rscBundle = false) => {
   const bundler = getBundler();
 
@@ -56,7 +25,6 @@ const configureServer = (rscBundle = false) => {
   // Using webpack-merge into an empty object avoids this issue.
   const serverWebpackConfig = commonWebpackConfig();
 
-  // We just want the single server bundle entry
   const serverEntry = {
     'server-bundle': serverWebpackConfig.entry['server-bundle'],
   };
@@ -80,18 +48,15 @@ const configureServer = (rscBundle = false) => {
 
   serverWebpackConfig.entry = serverEntry;
 
-  // No splitting of chunks for a server bundle
   serverWebpackConfig.optimization = {
     minimize: false,
   };
   serverWebpackConfig.plugins.unshift(new bundler.optimize.LimitChunkCountPlugin({ maxChunks: 1 }));
 
   if (!rscBundle) {
-    // Limit client-reference discovery to the app source directory. Without
-    // `clientReferences`, the plugin may traverse into node_modules/ and hit
-    // non-JS source files (e.g. .tsx that aren't configured for a loader),
-    // and would re-scan nodes we don't care about. Matches the Pro dummy
-    // pattern in react_on_rails_pro/spec/dummy/config/webpack/serverWebpackConfig.js.
+    // Scope client-reference discovery to the app source dir. Without this,
+    // the plugin can walk into node_modules and hit .tsx source files that
+    // aren't configured for a loader. Matches the Pro dummy pattern.
     serverWebpackConfig.plugins.push(
       new RSCWebpackPlugin({
         isServer: true,
@@ -102,21 +67,16 @@ const configureServer = (rscBundle = false) => {
     );
   }
 
-  // Custom output for the server-bundle.
-  // - libraryTarget: 'commonjs2' is required by the Pro Node renderer so it
-  //   can `require()` the evaluated bundle.
-  // - No publicPath: the server bundle is loaded by the Node renderer via the
-  //   filesystem, never served over HTTP, so asset URLs would go unused.
+  // libraryTarget: 'commonjs2' is required by the Pro Node renderer so it can
+  // `require()` the evaluated bundle. No publicPath: the server bundle is
+  // loaded from the filesystem, never served over HTTP.
   serverWebpackConfig.output = {
     filename: 'server-bundle.js',
     globalObject: 'this',
     libraryTarget: 'commonjs2',
     path: path.resolve(__dirname, '../../ssr-generated'),
   };
 
-  // Don't hash the server bundle b/c would conflict with the client manifest
-  // And no need for CSS extraction plugins (webpack's MiniCssExtractPlugin or
-  // rspack's CssExtractRspackPlugin).
   serverWebpackConfig.plugins = serverWebpackConfig.plugins.filter(
     (plugin) =>
       plugin.constructor.name !== 'WebpackAssetsManifest' &&
@@ -125,11 +85,6 @@ const configureServer = (rscBundle = false) => {
       plugin.constructor.name !== 'ForkTsCheckerWebpackPlugin',
   );
 
-  // Configure loader rules for SSR:
-  // - strip CSS extraction and style-loader (client build handles CSS export)
-  // - css-loader exportOnlyLocals: true (keep class name mapping only)
-  // - babel-loader caller.ssr: true (Babel picks SSR-specific transforms)
-  // - url/file-loader emitFile: false (don't duplicate image assets during SSR)
   serverWebpackConfig.module.rules.forEach((rule) => {
     if (Array.isArray(rule.use)) {
       rule.use = rule.use.filter((item) => {
@@ -161,16 +116,12 @@ const configureServer = (rscBundle = false) => {
     }
   });
 
-  // eval works well for the SSR bundle because it's the fastest and shows
-  // lines in the server bundle which is good for debugging SSR.
   serverWebpackConfig.devtool = 'eval';
 
-  // Target 'node' so the bundle uses real CommonJS require() and Node globals
-  // like __dirname. Avoids polyfills and fixes libraries like Emotion and
-  // loadable-components that break under target: 'web' in SSR.
+  // target: 'node' fixes SSR breakage in libraries (Emotion, loadable-components, etc.)
+  // that don't behave under the default 'web' target. node: false disables the
+  // polyfill shims that only matter when targeting 'web'.
   serverWebpackConfig.target = 'node';
-
-  // Disable Node.js polyfill shims — not needed when targeting Node.
   serverWebpackConfig.node = false;
 
   return serverWebpackConfig;

renderer/node-renderer.js

@@ -29,21 +29,19 @@ function parseIntegerEnv(name, defaultValue, { min, max = Number.MAX_SAFE_INTEGE
 
 const config = {
   serverBundleCachePath: path.resolve(__dirname, '.node-renderer-bundles'),
-  // Default to info per Pro docs (docs/oss/building-features/node-renderer/
-  // container-deployment.md: "logLevel: 'info' // General renderer logs").
-  // Override with RENDERER_LOG_LEVEL=debug when actively debugging.
   logLevel: process.env.RENDERER_LOG_LEVEL || 'info',
   password: rendererPassword,
   port: parseIntegerEnv('RENDERER_PORT', 3800, { min: 1, max: 65535 }),
   supportModules: true,
   workersCount: parseIntegerEnv('NODE_RENDERER_CONCURRENCY', 3, { min: 0 }),
-  // Expose globals the renderer's VM sandbox doesn't auto-provide but that
-  // downstream dependencies use during SSR (react-router-dom's NavLink calls
-  // `new URL(...)` via encodeLocation; various libs use AbortController).
+  // Expose globals the VM sandbox doesn't auto-provide but that downstream
+  // deps rely on during SSR. Without URL, react-router-dom's NavLink throws
+  // `ReferenceError: URL is not defined` via encodeLocation.
   additionalContext: { URL, AbortController },
 };
 
-// Cap CI workers unless the caller has set NODE_RENDERER_CONCURRENCY explicitly.
+// CI hosts report more CPUs than allocated to the container; cap workers to
+// avoid oversubscribing memory.
 if (process.env.CI && process.env.NODE_RENDERER_CONCURRENCY == null) {
   config.workersCount = 2;
 }