Docs(generator): note Pro production devtool for source-mapped SSR stacks (#3893)

[justin808]

Why

Part of the closeout of #3893 (SSR debugging & profiling). The core feature — source-mapped Node-renderer stack traces — shipped in #3940, and the profiling/--inspect docs in #3961. This PR closes one small residual: the generated serverWebpackConfig.js template gave no guidance on the devtool setting needed to actually get those source-mapped stack traces in production.

The template default is:

serverWebpackConfig.devtool = process.env.NODE_ENV === 'production' ? false : 'cheap-module-source-map';

i.e. source maps are disabled in production. That's a reasonable default (no .map files generated/uploaded), but it silently defeats the #3940 feature for Pro users in production: without a production server-bundle source map, the Node renderer has nothing to remap frames against, so production SSR error stacks stay anonymous/minified. Nothing in the generated config tells a Pro user how to opt in.

What

Adds a comment (Pro branch of the template only) documenting how to enable production source maps for source-mapped SSR stack traces, mirroring the existing prose guidance in docs/oss/building-features/node-renderer/debugging.md:

• devtool: 'source-map' — external .map (smaller bundle; stage the .map next to the uploaded bundle), or
• devtool: 'inline-source-map' — simplest; map travels inside the bundle.
• Plus the "never serve server-bundle source maps publicly" caveat.

Comment-only. No behavior change — the default stays false in production; this just documents the opt-in. Scoped to the use_pro? branch because the remapping is a Pro Node-renderer capability.

Scope / what's intentionally NOT here

• The other SSR debugging & profiling: source-mapped Node-renderer stack traces, --inspect workflow, Performance Tracks guide #3893 residual — a Rails-side RSpec asserting mapped .tsx frames in PrerenderError — is environment-heavy (needs the test SSR bundle built+staged with source maps, currently UNKNOWN) and is tracked as a separate P3 follow-up: Residual #3893: Rails RSpec asserting source-mapped .tsx frames in PrerenderError #4112 (not forced into this PR).
• I did not change the production devtool default. Flipping it to emit maps for all Pro users would add .map generation/upload and privacy considerations; an opt-in comment is the correct, behavior-preserving scope.

Validation

• Comment-only change inside the existing <% if use_pro? -%> block; no ERB interpolation introduced (the install_generator_spec.rb .tt-interpolation regression remains satisfied).
• Generator specs assert generated serverWebpackConfig.js content via include(...) substring checks (pro_generator_spec.rb, rsc_generator_spec.rb), and pro_server_webpack_content in generator_spec_helper.rb is a hand-written input fixture independent of this template — so added comments don't affect them.

Merge confidence

• Risk: very low. Comment-only template addition; no runtime, API, or generated-behavior change.
• Authorization: maintainer (justin808) explicitly authorized merge for confident, documented changes in this batch.
• Merge gate: pending hosted-CI green on required checks for the current head.

---

Note

Low Risk
Comment-only template change with no runtime or generated-config behavior change.

Overview
Adds comment-only guidance in the Pro serverWebpackConfig.js generator template so users know production SSR stack remapping needs non-default devtool settings.

The new block sits after the existing target: 'node' / node: false lines and explains that the default devtool: false in production blocks source-mapped frames, points to debugging.md, and shows opt-in examples (source-map vs inline-source-map) plus a warning not to expose server-bundle maps publicly. No generated webpack behavior changes — production still disables source maps by default.

^{Reviewed by Cursor Bugbot for commit cd2fe40. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• Documentation
  • Updated Pro server webpack configuration guidance with clearer instructions on enabling production server source maps, noting how this affects the underlying build setting.
  • Included security-focused clarification that the server bundle is not meant to be served to browsers and that source maps should not be exposed publicly.

[coderabbitai]

Caution

Review failed

An error occurred during the review process. Please try again later.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/3893-ssr-devtool-template-note

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[justin808]

+ci-run-hosted

[greptile-apps]

Greptile Summary

This PR adds a documentation comment inside the <% if use_pro? -%> ERB block of the server webpack config template, explaining how Pro users can enable production source maps to get source-mapped SSR stack traces via the Pro Node renderer.

• Adds a multi-line comment (lines 223–231) pointing to the debugging docs and showing two opt-in devtool patterns ('source-map' and 'inline-source-map'), plus a privacy reminder about not serving server-bundle maps publicly.
• No template logic, ERB interpolation, or generated-file behavior is changed; the production default remains devtool: false.

Confidence Score: 4/5

Safe to merge — comment-only addition with no generated-file behavior change.

The change is entirely documentation inside a template comment block. The one usability concern is that the example snippets show unconditional devtool assignments; a user following them verbatim would also overwrite the development cheap-module-source-map setting, which is likely unintentional. No runtime or generated config is affected.

The single changed template file is worth a quick read to confirm the example snippets are clear enough for the target audience.

Important Files Changed

Filename	Overview
react_on_rails/lib/generators/react_on_rails/templates/base/base/config/webpack/serverWebpackConfig.js.tt	Comment-only addition inside the use_pro? ERB block documenting how to enable production source maps for SSR stack traces; the example snippets are not production-conditional, which could mislead users into overriding the dev devtool as well.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[serverWebpackConfig.js.tt template] --> B{use_pro?}
    B -- "yes (Pro)" --> C["devtool = NODE_ENV === 'production' ? false : 'cheap-module-source-map'"]
    C --> D["NEW: Comment — how to opt in\nto production source maps"]
    D --> E["Option A: 'source-map'\nexternal .map file"]
    D --> F["Option B: 'inline-source-map'\nmap embedded in bundle"]
    B -- "no (OSS)" --> G["target stays 'web'\n(no Node renderer)"]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[serverWebpackConfig.js.tt template] --> B{use_pro?}
    B -- "yes (Pro)" --> C["devtool = NODE_ENV === 'production' ? false : 'cheap-module-source-map'"]
    C --> D["NEW: Comment — how to opt in\nto production source maps"]
    D --> E["Option A: 'source-map'\nexternal .map file"]
    D --> F["Option B: 'inline-source-map'\nmap embedded in bundle"]
    B -- "no (OSS)" --> G["target stays 'web'\n(no Node renderer)"]

Loading

_{Reviews (1): Last reviewed commit: "Docs(generator): note Pro production dev..." | Re-trigger Greptile}

[github-actions]

Hosted CI Requested

Triggered 9 workflow(s) for efe42276beb5.
Mode: optimized hosted CI (path-selected by script/ci-changes-detector).
Added ready-for-hosted-ci, so future commits will keep running optimized hosted CI until +ci-stop-hosted is used.

View progress in the Actions tab.

[coderabbitai]

🧹 Nitpick comments (1)

react_on_rails/lib/generators/react_on_rails/templates/base/base/config/webpack/serverWebpackConfig.js.tt (1)

230-231: 💤 Low value

Minor: Clarify the phrasing on lines 230–231.

The sentence "The server bundle is never served to browsers, but never serve server-bundle source maps publicly" uses "but" in a way that could be slightly confusing—it reads as a contrast when the intent is to reinforce a security best practice. Consider rephrasing for clarity:

// The server bundle is never served to browsers. As a security best practice,
// never serve server-bundle source maps publicly.

This is a minor suggestion and does not block the PR.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@react_on_rails/lib/generators/react_on_rails/templates/base/base/config/webpack/serverWebpackConfig.js.tt`
around lines 230 - 231, The comment on lines 230-231 in the serverWebpackConfig
file uses confusing phrasing with "but never serve" that makes the intent
unclear. Revise the comment to separate the two related ideas into distinct
statements: first clarify that the server bundle is not served to browsers, then
add a separate statement emphasizing the security best practice of never serving
server-bundle source maps publicly. Use a period or new comment line to create
this logical separation rather than using "but" as a connector.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In
`@react_on_rails/lib/generators/react_on_rails/templates/base/base/config/webpack/serverWebpackConfig.js.tt`:
- Around line 230-231: The comment on lines 230-231 in the serverWebpackConfig
file uses confusing phrasing with "but never serve" that makes the intent
unclear. Revise the comment to separate the two related ideas into distinct
statements: first clarify that the server bundle is not served to browsers, then
add a separate statement emphasizing the security best practice of never serving
server-bundle source maps publicly. Use a period or new comment line to create
this logical separation rather than using "but" as a connector.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: b5ad0004-7389-44ba-9e0e-b90517914678

📥 Commits

Reviewing files that changed from the base of the PR and between 7d8887e and efe4227.

📒 Files selected for processing (1)

• react_on_rails/lib/generators/react_on_rails/templates/base/base/config/webpack/serverWebpackConfig.js.tt

[claude]

Code Review

Summary: Comment-only addition to the serverWebpackConfig.js.tt generator template, scoped to the <% if use_pro? %> branch. No runtime or generated-behavior change. Risk is very low.

What the PR does well

• Correctly placed inside the use_pro? ERB guard — the feature it documents (source-mapped stack traces) is Pro-only.
• Both devtool options ('source-map' and 'inline-source-map') are accurate and match Webpack/Rspack.
• Cross-references the correct doc file (docs/oss/building-features/node-renderer/debugging.md).
• Includes the "never serve server-bundle source maps publicly" security caveat, consistent with the docs.
• Generator specs are unaffected (fixture in generator_spec_helper.rb is hand-written and independent of this template).

Minor wording issue

The last two lines read:

// The server bundle is never served to browsers, but never serve server-bundle
// source maps publicly.

The conjunction "but" implies a contrast that isn't there — both halves express things that shouldn't be served. Suggested fix:

// Server bundles never reach browsers, but keep any .map files off your
// public CDN / asset host.

Optional: surface the bundle-size trade-off for inline-source-map

The current comment says "simplest; map travels inside the bundle" but omits the size cost. A brief parenthetical would make the trade-off self-contained without requiring the doc link:

//   serverWebpackConfig.devtool = 'inline-source-map'; // simplest; map inside the bundle (larger file)

Verdict

Approve with optional nits. The guidance is accurate, correctly scoped to the Pro branch, and consistent with the referenced docs. Ready to merge once CI is green.

[claude]

Review: Comment-only template addition for Pro production devtool. This PR adds documentation comments to the generated serverWebpackConfig.js template (Pro path only) explaining how to opt in to production source maps for source-mapped SSR stack traces. Comment-only, well-scoped, low-risk. Full review posted as inline comments.

[claude]

Code Review - PR 4113 | Verdict: Approve with minor observations

The change is technically accurate, well-scoped, and fills a real documentation gap for Pro users. Low risk.

What is good:

• Correct scoping inside the use_pro? ERB guard.
• Both suggested devtool values (source-map, inline-source-map) are non-eval, satisfying the webpack 5.106+ constraint already documented above.
• Security caveat about not exposing server-bundle maps is appropriate.
• No test changes needed since generator specs use hand-written fixtures independent of this template.

Minor observations (non-blocking) - see inline comments for details.