Docs: add React Performance Tracks profiling guide by justin808 · Pull Request #3961 · shakacode/react_on_rails

justin808 · 2026-06-12T07:51:10Z

Summary

Part of #3893. This completes the docs remainder from the 2026-06-11 triage and intentionally avoids source-map-specific claims while #3940 remains open.

adds a React Performance Tracks and profiling guide
refreshes the existing Node Renderer --inspect debugging page
refreshes the Pro SSR profiling page and links it back to the debugging/profiling decision guide
adds the new guide to docs/sidebars.ts
regenerates llms-full.txt

Coordination

Add source-mapped stack traces to the Pro node renderer (#3893 core) #3940 is still open and edits docs/oss/building-features/node-renderer/debugging.md; whichever branch lands second may need a small textual conflict resolution.
No semantic merge-after dependency on Add source-mapped stack traces to the Pro node renderer (#3893 core) #3940: this PR omits source-map behavior references.

Test plan

node script/generate-llms-full.mjs -> generated 146 pages, 2042 KiB, 72 docs URLs validated
node script/generate-llms-full.mjs --check -> pass
script/check-docs-sidebar -> pass
script/ci-changes-detector origin/main -> documentation-only, recommended CI: none
pnpm start format.listDifferent -> pass
bin/check-links -> pass, 2784 total, 0 errors
git diff --check origin/main...HEAD -> pass
(cd react_on_rails && BUNDLE_GEMFILE=../Gemfile bundle exec rubocop) -> pass

Labels: none — docs-only, no code/workflow surface.

Note

Low Risk
Documentation-only changes with no runtime, API, or workflow code paths affected.

Overview
Adds performance-tracks-and-profiling.md, a decision guide for browser React Performance Tracks, Pro Node Renderer CPU profiling, breakpoints, memory, and production telemetry (Web Vitals, OpenTelemetry, error tracing), plus workflows for recording tracks, correlating browser and renderer traces, and User Timing in the renderer VM.

Refreshes the Node Renderer debugging page with a concrete overmind stop + pnpm run node-renderer:debug quick start, a Breakpoints vs. profiles section, and cross-links; drops the old external Node debugger stub.

Modernizes the Pro SSR profiling guide (title, node-renderer:debug script, clearer timeout/caching notes, hydration pointer to the new guide, ExecJS log typo isolate, speedscope via pnpm dlx / npx / yarn dlx instead of global install).

Registers the new page under Development & Ops in docs/sidebars.ts and regenerates llms-full.txt.

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

Summary by CodeRabbit

Documentation
- Expanded renderer debugging guide with clearer quick-start steps for attaching the inspector, isolating renderer logs, setting breakpoints, and alternative inspect workflows
- Added a comprehensive performance-profiling guide mapping symptoms to workflows and explaining React Performance Tracks and trace correlation
- Modernized server-side rendering profiling guidance with updated recording, timeout troubleshooting, and analysis workflows
- Updated docs navigation to surface the new profiling guidance

Agent Merge Confidence

Mode: accelerated-rc
Current head SHA: e35d684
Score: 8/10
Auto-merge recommendation: yes
Affected areas: OSS/Pro docs, docs sidebar, llms-full generated reference
CI detector: script/ci-changes-detector origin/main -> Documentation-only changes; recommends no CI jobs
Validation run:

node script/generate-llms-full.mjs -> generated; 146 pages, 2048 KiB, split threshold 2048 KiB; 73 docs URLs and 8 sidebar top-level sections validated
node script/generate-llms-full.mjs --check -> current; 146 pages, 2048 KiB, split threshold 2048 KiB
script/check-docs-sidebar -> new doc building-features/performance-tracks-and-profiling has sidebar entry
pnpm start format.listDifferent -> pass
Pre-commit/pre-push markdown link hooks -> pass
Review/check gate:
GitHub checks: complete for e35d6847a899ee5ed32bdda92a54adac9cbc0b7e; 15 pass, 2 expected skips explained
Expected skips: secondary claude job skipped while claude-review passed; build in Lint JS and Ruby skipped by docs-only path selection while docs-format and local Prettier passed
Review threads: GraphQL unresolved count is 0
Current-head reviewer verdicts:
- Claude review: claude-review check passed for e35d6847a899ee5ed32bdda92a54adac9cbc0b7e; actionable debugging-flow threads fixed; later clarity nits triaged optional and resolved
- CodeRabbit: check succeeded with "Review skipped"
  Known residual risk: Low; PR Add source-mapped stack traces to the Pro node renderer (#3893 core) #3940 is still open, so this docs PR intentionally avoids source-map behavior references. llms-full is exactly at the 2048 KiB no-split threshold, so future docs additions will likely need the OSS/Pro split.
  Finalized by: claude-review GitHub check / Claude Code Review workflow for current head, run https://github.com/shakacode/react_on_rails/actions/runs/27463255831/job/81180874270

coderabbitai · 2026-06-12T07:51:26Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

Walkthrough

This PR expands and reorganizes debugging and profiling documentation: it rewrites node-renderer debugging with Node inspector guidance, adds a React Performance Tracks profiling guide, modernizes Pro SSR profiling and ExecJS analysis, and updates the docs sidebar.

Changes

Debugging and Performance Profiling Documentation Expansion

Layer / File(s)	Summary
Node Renderer Debugging Walkthrough `docs/oss/building-features/node-renderer/debugging.md`	Updated opening to recommend Node's inspector for renderer debugging; rewrote "Quick start" with Overmind-based renderer isolation and Chrome debugger attach steps; added "Breakpoints vs. profiles"; removed older Node debugger link.
React Performance Tracks Profiling Guide `docs/oss/building-features/performance-tracks-and-profiling.md`	New guide differentiating browser vs. Pro Node Renderer vs. real-user profiling needs; includes a symptom→tool decision table, steps to record and interpret Scheduler/Components/Server/RSC tracks, profile naming guidance, browser-renderer correlation tips, and production-safe observability recommendations.
Server-Side Rendering Profiling Modernization `docs/pro/profiling-server-side-rendering-code.md`	Reworked Pro Node Renderer profiling workflow with Chrome DevTools `chrome://inspect` steps, timeout troubleshooting, structured profile analysis, high-load guidance, and updated ExecJS V8 log analysis to `pnpm dlx speedscope`.
Documentation Navigation Update `docs/sidebars.ts`	Added `building-features/performance-tracks-and-profiling` to the "Development & Ops" list under "Building Features".

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

shakacode/react_on_rails#3960: Related docs/sidebar changes required by llms-full generation and CI validation.
shakacode/react_on_rails#3903: Prior profiling/debugging docs updates and llms-full artifact changes.

Suggested labels

review-needed, documentation, P3

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'Docs: add React Performance Tracks profiling guide' accurately captures the primary change: introduction of a new comprehensive profiling guide. It is concise, specific, and directly reflects the main objective of the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch jg-codex/3893-ssr-profiling-docs-v2

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

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

claude · 2026-06-12T07:55:20Z

Code Review: Docs — React Performance Tracks and Profiling Guide

Overall assessment: Good to merge with minor notes. This is a clean, docs-only PR that fills a real gap in the profiling/debugging decision tree. The cross-linking strategy — each page pointing at the right sibling for its non-scope cases — is well executed and meaningfully improves discoverability.

What works well

Decision table in performance-tracks-and-profiling.md is the strongest addition: a single symptom → tool mapping that immediately answers "which guide should I read?" This kind of signpost belongs at the top of any profiling section.
Cross-links are consistent: all three pages (debugging, profiling, performance-tracks) now reference each other in their opening paragraphs. No dead ends.
ExecJS typo fix (isloate-0x*.log → isolate-0x*.log) is a real user-facing correction that was silently causing confusion.
speedscope via pnpm dlx removes the "global install tax" from the profiling workflow.
"Breakpoints vs. profiles" section in debugging.md is a useful 4-bullet navigator.
Removal of the stale GitHub issue link (#1196) in "Debugging using the Node debugger" is the right call — the replacement inline docs are much better.
overmind stop + pnpm run node-renderer:debug as a bash block is clearer for copy-paste than the old prose description.

Minor issues (see inline comments)

ssr_timeout note dropped the initializer file path — the new prose is terser but loses the config/initializers/react_on_rails_pro.rb location hint that new users need.
pnpm dlx speedscope is pnpm-only — users on npm or yarn don't have dlx. A brief fallback mention avoids a "command not found" moment.
Intro says "three different performance questions" but the guide covers six — the numbered list and the decision table have different granularity. Not wrong, but mildly confusing for a first-time reader.

`llms-full.txt`

The regenerated llms-full.txt is ~90% of the diff by line count but is entirely generated output. The test plan confirms the generation passed (146 pages, 0 link errors, --check pass). No concerns here — the new content (React Compiler guide, Tailwind, View Transitions, Fast Images) comes from previously merged PRs that weren't in the old snapshot.

greptile-apps · 2026-06-12T07:55:36Z

Greptile Summary

This PR adds a new React Performance Tracks and Profiling guide (docs/oss/building-features/performance-tracks-and-profiling.md), refreshes the Node Renderer debugging and Pro SSR profiling pages, and adds the new guide to the sidebar and llms-full.txt.

New guide introduces a symptom-to-tool decision table, step-by-step Chrome DevTools recording instructions, Scheduler/Components/Server track interpretation, User Timing marks for renderer-side spans, and production telemetry guidance — all cross-linked correctly to the existing debugging and SSR profiling pages.
debugging.md gains a clearer quick-start procedure, a new "Breakpoints vs. profiles" decision section, and back-links to the two sibling profiling pages; the stale link to GitHub issue Debugging Server Rendering with the Node VM Rendering Server #1196 is removed.
profiling-server-side-rendering-code.md receives a title rename, prose cleanup, a fix for the long-standing isloate → isolate typo, and a switch from npm install -g speedscope to pnpm dlx speedscope.

Confidence Score: 5/5

Documentation-only PR with no code changes; all internal cross-references and anchors resolve correctly, and the test plan shows link checking, sidebar validation, and llms-full generation all passed.

The new guide introduces accurate technical content (Performance Tracks availability, supportModules/performance API, User Timing marks usage), all relative paths were verified against the real file tree, and the sidebar entry is correctly placed. The only finding is a missing hyperlink in a 'see the React docs' aside — a cosmetic gap with no impact on correctness.

No files require special attention; llms-full.txt is a generated artifact and its large diff reflects a full regeneration that picks up several previously un-indexed pages.

Important Files Changed

Filename	Overview
docs/oss/building-features/performance-tracks-and-profiling.md	New guide introducing React Performance Tracks; decision table, recording steps, interpretation guidance, and User Timing marks example are all technically accurate and correctly cross-referenced.
docs/oss/building-features/node-renderer/debugging.md	Refreshed intro and quick-start procedure; adds a 'Breakpoints vs. profiles' decision section and cross-links to the new profiling guide and SSR profiling page; removes stale GitHub issue link (#1196).
docs/pro/profiling-server-side-rendering-code.md	Title renamed from 'In RORP' to 'Code'; prose cleanup throughout; fixes 'isloate' typo to 'isolate'; replaces npm install -g speedscope with pnpm dlx speedscope; adds back-links to the new performance-tracks guide.
docs/sidebars.ts	Adds building-features/performance-tracks-and-profiling to the 'Development & Ops' category, correctly placed between debugging and web-vitals-and-rum.
llms-full.txt	Regenerated artifact; includes the new performance-tracks-and-profiling page and catches up several previously un-indexed pages (React Compiler, View Transitions, Tailwind flag); no manual edits required.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Slow behavior observed] --> B{Where is it slow?}
    B -->|Browser: click, nav, hydration| C[Chrome DevTools Performance\n+ React Performance Tracks]
    B -->|Specific component re-renders too often| D[React Components track\n+ React DevTools Profiler]
    B -->|Node Renderer CPU / SSR latency| E[Profiling Server-Side\nRendering Code]
    B -->|Need breakpoints / request-by-request| F[Node Renderer Debugging\n--inspect]
    B -->|Production SSR spans / errors| G[Error Reporting & Tracing\n+ OpenTelemetry]
    B -->|Renderer memory growth| H[Memory Leaks guide\nheap snapshots]
    E --> I{Also slow in browser?}
    I -->|Yes| C
    C --> J[Correlate browser + renderer traces\nby timestamp and component name]
    E --> J

_{Reviews (1): Last reviewed commit: "Docs: add SSR profiling guide" | Re-trigger Greptile}

coderabbitai

Actionable comments posted: 1

🤖 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.

Inline comments:
In `@docs/pro/profiling-server-side-rendering-code.md`:
- Line 34: The docs currently use pnpm-specific commands ("pnpm run
node-renderer:debug" and "pnpm dlx speedscope ...") which makes the guide
package-manager-specific; update the examples to be package-manager-neutral by
adding npm and yarn equivalents (e.g., npm run node-renderer:debug and yarn run
node-renderer:debug) and alternatives for running speedscope (npx speedscope ...
and yarn dlx speedscope ...), or explicitly state that pnpm is required; apply
the same change to the other occurrences referenced around the document (lines
~136-180) so all examples are consistent.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 5a24226d-39ce-4796-b0a8-46b189a4f36d

📥 Commits

Reviewing files that changed from the base of the PR and between 4d22315 and e1ccdab.

📒 Files selected for processing (5)

docs/oss/building-features/node-renderer/debugging.md
docs/oss/building-features/performance-tracks-and-profiling.md
docs/pro/profiling-server-side-rendering-code.md
docs/sidebars.ts
llms-full.txt

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6ca5848e86

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

claude · 2026-06-12T08:54:53Z

Code Review — PR #3961: Docs: add React Performance Tracks profiling guide

Overall: Solid documentation PR, ready to merge with one minor inconsistency to resolve.

Overview

This PR adds a new decision-guide-style profiling page, refreshes the Node renderer debugging page with a cleaner --inspect quickstart, and updates the Pro SSR profiling page with cross-links and modernized tooling. All changed files are documentation only.

What works well

All cross-references are valid. Every linked file exists on disk, and the critical anchors (#observability-with-opentelemetry, #runtime-globals-for-ssr-and-rsc, #2-take-v8-heap-snapshots) resolve to real headings in the current source.
Technical claims are accurate. node-renderer:debug script exists in react_on_rails_pro/spec/dummy/package.json with the exact --inspect incantation documented. The claim that performance is available when supportModules: true is validated by js-configuration.md lines 37–38.
Decision table in the new guide is well structured. Symptom-first rows covering browser, component, SSR, breakpoints, production, and memory make it easy to pick the right tool without reading everything.
Sidebar placement is correct. performance-tracks-and-profiling sits between debugging and web-vitals-and-rum in the "Development & Ops" category — a logical sequence from code → profile → field metrics.
llms-full.txt regeneration is clean. The generator validates all 72 docs URLs and passes --check.

Minor issue: `isolate.log` vs `isolate-0x.log` inconsistency

In docs/pro/profiling-server-side-rendering-code.md:

Lines 128 and 180 document the actual V8 filename pattern as isolate-0x*.log (correct — V8 always uses the 0x hex prefix).
Line 183 (the shell command for the older-version workflow) uses isolate*.log, a broader glob.

The broader glob works, but a reader who just read the filename description above may wonder if they're different patterns. Suggest making line 183 consistent:

# Current
node --prof-process --preprocess -j isolate*.log > profile.v8log.json
# Suggested
node --prof-process --preprocess -j isolate-0x*.log > profile.v8log.json

Nitpick: React 19.2 version phrasing

performance-tracks-and-profiling.md says "Run the app in development with React 19.2 or newer" and the debugging page's intro references "React 19.2 Performance Tracks". The react.dev docs page itself does not hard-code a specific patch version. Consider softening to "React 19" or "React 19.2+" with a note like "(as documented on react.dev)" to avoid confusion if the feature is later backported or the docs URL updates.

Test plan coverage

The PR ran all relevant checks:

generate-llms-full.mjs --check ✅
check-docs-sidebar ✅
format.listDifferent ✅
check-links ✅ (2784 links, 0 errors)
Rubocop ✅

This is comprehensive for a docs-only PR.

Merge readiness

No blocking issues. The isolate*.log inconsistency is worth a one-line fix; everything else is a nitpick or suggestion. The coordination note about #3940 is correctly documented in the PR description — the conflict surface is narrow (one paragraph in debugging.md), and whichever PR lands second will face a trivial textual conflict.

claude · 2026-06-12T09:06:23Z

Code Review

Summary: Documentation-only PR — adds a React Performance Tracks and Profiling guide, refreshes the Node Renderer debugging page and Pro SSR profiling page, wires up sidebar navigation, and regenerates llms-full.txt. All referenced anchors and cross-links resolve to real files/sections. No code or runtime changes.

What's good

Decision table in the new guide cleanly maps symptoms to tools, eliminating common confusion between browser profiling, Node CPU profiling, and breakpoint debugging.
Typo fix isloate-0x*.log → isolate-0x*.log (two locations) is a real correctness improvement.
Glob precision isolate*.log → isolate-0x*.log matches actual V8 profiler output more tightly.
Tooling modernization: replacing npm install -g speedscope with pnpm dlx / npx / yarn dlx avoids polluting global installs.
performance availability claim in the new guide ("available when supportModules: true") is confirmed accurate by js-configuration.md lines 37 and 49.
Removed stale 2017 issue link (Debugging Server Rendering with the Node VM Rendering Server #1196 "Debugging using the Node debugger") and replaced it with inline, actionable steps.
Sidebar placement (debugging → performance profiling → web vitals) follows a natural task-to-scope progression.

One issue to fix

In the Quick start section of debugging.md, the renderer is launched directly via pnpm run node-renderer:debug (after overmind stop) — so it is no longer under Overmind control. Step 4 says "restart just the renderer" without saying how. overmind restart node-renderer won't work here since the process is no longer tracked by Overmind. See inline comment.

Minor nits (non-blocking)

Line 97 of the new guide — "when your app supports that React line" — reads awkwardly. "if your app is already on React 19.2" might be cleaner.
The #profiling-the-pro-node-renderer internal anchor referenced in the high-loads section requires Docusaurus to generate the slug correctly from the new heading. The test plan confirms check-docs-sidebar and link-check both passed, so this is already validated.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 43245f28c6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

claude · 2026-06-13T09:37:15Z

Code Review — PR #3961: Add React Performance Tracks Profiling Guide

Overall: Looks good, one functional inconsistency worth fixing.

This is a well-structured docs PR. The new decision-table guide fills a real gap, cross-linking between all three pages is thorough, and the content is accurate.

What works well

New decision table in performance-tracks-and-profiling.md is a clean, scannable entry point. The symptom-based approach is exactly how developers think.
Navigation headers added to debugging.md and profiling-server-side-rendering-code.md disambiguate scope at a glance — no reading required to find out you're on the wrong page.
Removed stale content: dropping the "Debugging using the Node debugger" section (which linked to a 2018 GitHub issue) is the right call.
Typo fix: isloate-0x*.log → isolate-0x*.log (two places) is a real user-facing fix.
Glob fix: isolate*.log → isolate-0x*.log tightens the pattern to match actual Node profiler output.
speedscope modernization: replacing npm install -g speedscope with pnpm dlx/npx/yarn dlx avoids global install pollution and works across package managers.
User Timing example with the ror:ssr: prefix convention is a concrete, copy-pasteable pattern.
Sidebar placement (between debugging and web-vitals-and-rum) is logical.

Issue: step 2 becomes unreachable after the new quick-start flow

The quick-start in debugging.md now instructs:

overmind stop node-renderer
pnpm run node-renderer:debug

After overmind stop, the renderer is no longer under Overmind's supervision. But the numbered steps that immediately follow say:

Use overmind to isolate renderer logs: overmind connect node-renderer (Ctrl-B to detach).

overmind connect attaches to a process managed by Overmind. Once the user has stopped Overmind's copy and started the renderer manually, overmind connect node-renderer either fails or attaches to a dead entry. The logs are already in the terminal running pnpm run node-renderer:debug — no overmind connect needed on that path.

See inline comment for a suggested fix.

Minor: step 4 omits the restart command for the manual path

Step 4 says "restart just the renderer" without saying how. For the user on the pnpm run node-renderer:debug path that means Ctrl-C and re-run; for the Overmind path it means overmind restart node-renderer. A short parenthetical would prevent confusion.

Coordination note

The PR description correctly flags a potential conflict with #3940 on debugging.md. Whichever lands second should verify the overmind connect step hasn't been re-introduced during conflict resolution.

coderabbitai

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/oss/building-features/node-renderer/debugging.md (1)
40-44: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Make the install step package-manager-agnostic.

This snippet is pnpm-only, but the docs guideline says end-user docs under docs/ should show npm, yarn, and pnpm for installation instructions. Add the equivalent npm/yarn commands here, or mark this page as internal-only if that’s the intent.

As per coding guidelines, end-user docs under docs/ should keep installation instructions package-manager-agnostic (npm, yarn, and pnpm).
🤖 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 `@docs/oss/building-features/node-renderer/debugging.md` around lines 40 - 44,
Update the install step so it's package-manager-agnostic: replace the single
pnpm commands with equivalent three-line blocks showing npm, yarn, and pnpm
(e.g., npm: "npm install" / "npm run build"; yarn: "yarn" / "yarn build"; pnpm:
"pnpm install" / "pnpm run build"), or if the page is intended to be
internal-only, add an explicit note marking it internal instead of showing
end-user install instructions.
Source: Coding guidelines

🤖 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.

Outside diff comments:
In `@docs/oss/building-features/node-renderer/debugging.md`:
- Around line 40-44: Update the install step so it's package-manager-agnostic:
replace the single pnpm commands with equivalent three-line blocks showing npm,
yarn, and pnpm (e.g., npm: "npm install" / "npm run build"; yarn: "yarn" / "yarn
build"; pnpm: "pnpm install" / "pnpm run build"), or if the page is intended to
be internal-only, add an explicit note marking it internal instead of showing
end-user install instructions.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 19162a51-22d1-43fa-82f7-77d48907b468

📥 Commits

Reviewing files that changed from the base of the PR and between 48f53c2 and 43245f2.

📒 Files selected for processing (5)

docs/oss/building-features/node-renderer/debugging.md
docs/oss/building-features/performance-tracks-and-profiling.md
docs/pro/profiling-server-side-rendering-code.md
docs/sidebars.ts
llms-full.txt

✅ Files skipped from review due to trivial changes (2)

docs/sidebars.ts
docs/pro/profiling-server-side-rendering-code.md

🚧 Files skipped from review as they are similar to previous changes (1)

llms-full.txt

claude · 2026-06-13T09:47:49Z

Code Review

Overall: Strong documentation PR. Ready to merge with minor nits.

What this does

Adds a new React Performance Tracks and Profiling guide, refreshes the Node Renderer debugging and Pro SSR profiling pages, and wires everything together with cross-links and a decision table. All verified CI commands pass per the test plan.

Strengths

Decision table in the new guide is well-structured and gives readers an immediate on-ramp regardless of their symptom.
Cross-linking between the three pages (debugging ↔ profiling ↔ new guide) is thorough and consistent.
Typo fix: isloate-0x*.log → isolate-0x*.log corrected in two places in the Pro profiling guide — this would have caused users to miss their V8 log files.
Glob precision: isolate*.log → isolate-0x*.log in the older-versions ExecJS section — more precise, less likely to accidentally match unrelated files.
Tooling modernisation: replacing npm install -g speedscope with pnpm dlx / npx / yarn dlx avoids polluting the global npm prefix.
Removing the stale Node debugger stub: the removed section only pointed to a GitHub issue from 2017; the new quick-start replaces it with concrete steps.
ror:ssr: namespace convention in the User Timing code snippet is a sensible, readable prefix.

Minor nits (non-blocking)

### Breakpoints vs. profiles placement — placed as a ### sub-section under ## Debugging the Node Renderer but it functions as a page-level navigation guide. Promoting it to ## and moving it just below the intro paragraph would make it easier to discover (it would appear in the right-nav TOC at the top level). Not a blocker.
React 19.2 caveat in the recording steps — Step 1 says "Run the app in development with React 19.2 or newer when your app supports that React line." Readers on React 18 may not know whether they get any Performance Tracks benefit. A one-liner clarifying that the Scheduler track existed before 19.2 (via react-dom/profiling) while the Components track requires React DevTools ≥ 5.x would help. Non-blocking.
User Timing availability note — "In the Pro Node Renderer VM, performance is available when supportModules: true; otherwise inject it with additionalContext" is correct and links to the right place. Adding "(Node.js global)" after the first mention would help readers unfamiliar with the VM context understand why availability depends on config.

No security, runtime, or API-surface concerns

Documentation-only change. The code snippet added is illustrative User Timing instrumentation; it introduces no runtime paths, no dependencies, and no new configuration options.

…batch * origin/main: (42 commits) Docs: add OSS flagship demo to examples gallery (closes #3876) (#3959) Docs: rewrite RSC CSS guide with FOUC pipeline and per-approach sections (#3992) Docs: add 21 animated SVG diagrams for React Server Components (#3806) Fix Rspack generator: missing @rspack/dev-server and wrong ReactRefreshPlugin import (#3926) Docs: add React Performance Tracks profiling guide (#3961) Add cross-agent coordination backend workflow (#3977) Validate llms sidebar coverage and hosted pointers (#3960) Harden +ci command workflow: resilient reactions and github-script v9 (#3978) Modernize internal dev_tests ESLint template (#3962) Fix precompile hook crash under non-UTF-8 locale (C/POSIX) (#3949) Regenerate llms-full.txt to clear drift-guard failure on main (#3968) Bump version to 17.0.0.rc.3 Regenerate llms-full.txt (stale drift-guard fix) (#3967) Update CHANGELOG.md for 17.0.0.rc.3 (#3966) Docs: fix Node Renderer Kubernetes probes (#3930) Docs: modernize the getting-started tutorial (#3931) Docs: record decided Server Functions stance in RSC mutations section (#3957) Generate llms-full.txt from the published docs + CI drift guard (#3903) Docs: add fast-images recipe with Rails primitives; reconcile images.md (#3955) Docs: add Web Vitals / first-party RUM guide (#3954) ... # Conflicts: # .agents/skills/plan-pr-batch/SKILL.md

…error-callbacks * origin/main: Docs: add OSS flagship demo to examples gallery (closes #3876) (#3959) Docs: rewrite RSC CSS guide with FOUC pipeline and per-approach sections (#3992) Docs: add 21 animated SVG diagrams for React Server Components (#3806) Fix Rspack generator: missing @rspack/dev-server and wrong ReactRefreshPlugin import (#3926) Docs: add React Performance Tracks profiling guide (#3961) Add cross-agent coordination backend workflow (#3977) Validate llms sidebar coverage and hosted pointers (#3960) Harden +ci command workflow: resilient reactions and github-script v9 (#3978) Modernize internal dev_tests ESLint template (#3962) # Conflicts: # .lychee.toml # CHANGELOG.md # docs/sidebars.ts # llms-full.txt

…t192-phase1 * origin/main: (43 commits) Split llms-full.txt into OSS and Pro tiers to clear the 2048 KiB gate (#4021) Codify maintainer attention contract (#3987) Docs: correct vm.Script caching analysis caveats (#3997) CI: handle unavailable PR head repo for +ci-run-full (#3986) Fix Pro dummy lockfile drift and rich text demo (#3989) Add FOUC integration tests for generated CSS (#4005) Make per-PR benchmarks opt-in and trim per-route warm-up (#4012) (#4013) Treat docs-internal/ tree as documentation in CI change detection (#4016) Add issue triage prompt skill (#3983) Point coordination docs at agent-coord bootstrap (#4008) Docs: backfill async RSC manifest changelog entry (#3993) Migrate conductor.json to .conductor/settings.toml (#4007) Bump react-hooks lint to v6 and document RSC compiler boundary (#3963) Docs: add OSS flagship demo to examples gallery (closes #3876) (#3959) Docs: rewrite RSC CSS guide with FOUC pipeline and per-approach sections (#3992) Docs: add 21 animated SVG diagrams for React Server Components (#3806) Fix Rspack generator: missing @rspack/dev-server and wrong ReactRefreshPlugin import (#3926) Docs: add React Performance Tracks profiling guide (#3961) Add cross-agent coordination backend workflow (#3977) Validate llms sidebar coverage and hosted pointers (#3960) ...

…acks (#3893) (#4113) ## 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: ```js 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 #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: #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. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit cd2fe40. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>   ## 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.  --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

claude Bot reviewed Jun 12, 2026

View reviewed changes

Comment thread docs/pro/profiling-server-side-rendering-code.md

claude Bot reviewed Jun 12, 2026

View reviewed changes

Comment thread docs/pro/profiling-server-side-rendering-code.md

claude Bot reviewed Jun 12, 2026

View reviewed changes

Comment thread docs/oss/building-features/performance-tracks-and-profiling.md Outdated

greptile-apps Bot reviewed Jun 12, 2026

View reviewed changes

Comment thread docs/oss/building-features/performance-tracks-and-profiling.md Outdated

coderabbitai Bot requested changes Jun 12, 2026

View reviewed changes

Comment thread docs/pro/profiling-server-side-rendering-code.md Outdated

coderabbitai Bot approved these changes Jun 12, 2026

View reviewed changes

chatgpt-codex-connector Bot reviewed Jun 12, 2026

View reviewed changes

Comment thread docs/oss/building-features/performance-tracks-and-profiling.md Outdated

claude Bot reviewed Jun 12, 2026

View reviewed changes

Comment thread docs/pro/profiling-server-side-rendering-code.md Outdated

justin808 force-pushed the jg-codex/3893-ssr-profiling-docs-v2 branch from 6556a39 to 48f53c2 Compare June 12, 2026 09:03

claude Bot reviewed Jun 12, 2026

View reviewed changes

Comment thread docs/oss/building-features/node-renderer/debugging.md Outdated

justin808 added 3 commits June 12, 2026 23:30

Docs: add SSR profiling guide

1794cb0

Address profiling docs review

3b6d3c9

Refine profiling docs caveats

43245f2

justin808 force-pushed the jg-codex/3893-ssr-profiling-docs-v2 branch from 48f53c2 to 43245f2 Compare June 13, 2026 09:30

chatgpt-codex-connector Bot reviewed Jun 13, 2026

View reviewed changes

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

claude Bot reviewed Jun 13, 2026

View reviewed changes

Comment thread docs/oss/building-features/node-renderer/debugging.md Outdated

coderabbitai Bot reviewed Jun 13, 2026

View reviewed changes

Clarify node renderer debug logs

e35d684

claude Bot reviewed Jun 13, 2026

View reviewed changes

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

claude Bot reviewed Jun 13, 2026

View reviewed changes

Comment thread docs/oss/building-features/performance-tracks-and-profiling.md

claude Bot reviewed Jun 13, 2026

View reviewed changes

Comment thread docs/oss/building-features/performance-tracks-and-profiling.md

justin808 merged commit 81ef2fa into main Jun 13, 2026
32 checks passed

justin808 deleted the jg-codex/3893-ssr-profiling-docs-v2 branch June 13, 2026 10:02

This was referenced Jun 14, 2026

Release gate: react_on_rails 17.0.0 #3823

Open

Post-rc.3 catch-up audit before final release go/no-go #4011

Closed

coderabbitai Bot mentioned this pull request Jun 20, 2026

docs: paired ShakaPerf A/B methodology for RSC perf regressions (#4137) #4142

Merged

Uh oh!

Uh oh!

Conversation

justin808 commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Coordination

Test plan

Summary by CodeRabbit

Agent Merge Confidence

Uh oh!

coderabbitai Bot commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Uh oh!

claude Bot commented Jun 12, 2026

Code Review: Docs — React Performance Tracks and Profiling Guide

What works well

Minor issues (see inline comments)

llms-full.txt

Uh oh!

Uh oh!

Uh oh!

Uh oh!

greptile-apps Bot commented Jun 12, 2026

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Flowchart

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

claude Bot commented Jun 12, 2026

Code Review — PR #3961: Docs: add React Performance Tracks profiling guide

Overview

What works well

Minor issue: isolate*.log vs isolate-0x*.log inconsistency

Nitpick: React 19.2 version phrasing

Test plan coverage

Merge readiness

Uh oh!

Uh oh!

claude Bot commented Jun 12, 2026

Code Review

What's good

One issue to fix

Minor nits (non-blocking)

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

claude Bot commented Jun 13, 2026

Code Review — PR #3961: Add React Performance Tracks Profiling Guide

What works well

Issue: step 2 becomes unreachable after the new quick-start flow

Minor: step 4 omits the restart command for the manual path

Coordination note

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

claude Bot commented Jun 13, 2026

Code Review

justin808 commented Jun 12, 2026 •

edited

Loading

coderabbitai Bot commented Jun 12, 2026 •

edited

Loading

`llms-full.txt`

Minor issue: `isolate.log` vs `isolate-0x.log` inconsistency