Docs: Add RSC landing, ExecJS limitations, debugging, and benchmarks pages#2785
Docs: Add RSC landing, ExecJS limitations, debugging, and benchmarks pages#2785
Conversation
|
Note Reviews pausedIt 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 Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughAdds four new documentation pages (ExecJS limitations, debugging workflow, performance benchmarks, Pro React Server Components landing) and small cross-reference updates across existing docs; all edits are documentation-only and focus on SSR constraints, debugging flags, performance comparisons, and RSC guidance. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/oss/building-features/debugging.md`:
- Around line 78-80: Add a fenced code language identifier to the markdown
snippet that shows the hydration warning so markdownlint MD040 is satisfied:
update the code block that currently starts with ``` followed by the warning
text `Warning: Text content did not match. Server: "March 21" Client: "March
22"` to use ```text (i.e., add "text" after the opening backticks) so the fenced
block is explicitly language-specified.
In `@docs/oss/core-concepts/execjs-limitations.md`:
- Around line 19-22: Several fenced code blocks containing plain error messages
(for example the blocks starting with "ReferenceError: setTimeout is not
defined", "ReferenceError: window is not defined", and "ReferenceError:
TextEncoder is not defined") lack a language tag and trigger markdownlint MD040;
update each of those triple-backtick fences to include a language specifier (use
"text") so they become ```text ... ``` to satisfy markdownlint and preserve the
exact block content in execjs-limitations.md (locate these by searching for the
shown error strings and update the surrounding ``` fences).
🪄 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: 1fa81e17-cae6-4dad-a34c-381350259383
📒 Files selected for processing (8)
docs/oss/building-features/debugging.mddocs/oss/core-concepts/client-vs-server-rendering.mddocs/oss/core-concepts/execjs-limitations.mddocs/oss/core-concepts/performance-benchmarks.mddocs/oss/core-concepts/react-server-rendering.mddocs/oss/deployment/troubleshooting.mddocs/oss/getting-started/oss-vs-pro.mddocs/pro/react-server-components/index.md
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e6981f980a
ℹ️ 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".
Greptile SummaryThis PR adds four new documentation pages (RSC landing, ExecJS Limitations, Debugging Guide, Performance Benchmarks) and adds cross-reference links from four existing docs. All internal links resolve to existing files, and the new pages are well-structured with appropriate code examples and formatting consistent with the rest of the docs. Key findings:
Confidence Score: 4/5
Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[New RSC Landing Page\ndocs/pro/react-server-components/index.md] --> B[Tutorial Series]
A --> C[Migration Guide\ndocs/oss/migrating/]
A --> D[Deep Dives\nhow-rsc-works, rendering-flow, etc.]
E[New ExecJS Limitations Page\ndocs/oss/core-concepts/execjs-limitations.md] --> F[Debugging Guide\ndocs/oss/building-features/debugging.md]
E --> G[Configuration Reference\ndocs/oss/configuration/README.md]
E --> H[Node Renderer Basics\nbuilding-features/node-renderer/basics.md]
I[New Performance Benchmarks Page\ndocs/oss/core-concepts/performance-benchmarks.md] --> E
I --> A
J[Updated: client-vs-server-rendering.md] -->|cross-ref| E
K[Updated: react-server-rendering.md] -->|cross-ref| E
L[Updated: troubleshooting.md] -->|cross-ref| F
M[Updated: oss-vs-pro.md] -->|RSC link updated| A
Last reviewed commit: "Add missing docs pag..." |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
|
test comment please ignore |
PR Review: Add RSC landing, ExecJS limitations, debugging, and benchmarks pagesOverall, this is a solid set of docs that fills real gaps. All cross-reference links resolve to existing files, the structure is consistent with existing docs, and the content is clearly written. A few factual issues to address before merging: Critical: Incorrect ExecJS performance claimperformance-benchmarks.md states:
This is factually wrong. Looking at Performance table: misleading architecture descriptionThe table row for "ExecJS (Node.js runtime)" says "Spawns Node.js per eval". ExecJS with the Node.js runtime spawns a persistent Node.js subprocess and communicates via pipes — it does not spawn a new process per eval. Something like "Persistent subprocess via IPC" would be more accurate. Performance table: benchmarks appear reversedThe "Typical speedup" column shows mini_racer as "Baseline" and ExecJS (Node.js runtime) as "~1-2x over mini_racer", implying Node.js runtime is faster. This is typically the opposite: mini_racer embeds V8 directly in the Ruby process (avoiding subprocess IPC overhead) and is generally faster than ExecJS with the Node.js runtime. If there is data supporting this claim, it should be cited; otherwise the comparison should be corrected or removed. Minor: webpack-specific command in debugging.mdThe command Minor: registeredComponents() returns a Map, not a listIn debugging.md: "This returns a list of all components that have been registered" — the actual return type is Map<string, RegisteredComponent> (confirmed in the TypeScript source). Not a blocker, but worth correcting for accuracy. |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/oss/core-concepts/performance-benchmarks.md (1)
18-18: Qualify or source the generalized percentage claims.Line 18 (
10-100x) and Line 33 (40-70%) read as broad guarantees. Please add benchmark context (workload/hardware/app profile) or citations to keep expectations calibrated.Also applies to: 33-33
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/oss/core-concepts/performance-benchmarks.md` at line 18, Update the generalized performance claims in the table and surrounding text (specifically the "10-100x" and "40-70%" entries) to include benchmark context and sources: either replace the raw ranges with qualified phrasing (e.g., "up to 10–100x depending on workload and hardware" or "typical improvements of 40–70% in I/O-bound workloads") and add a short parenthetical describing workload, hardware, and profiler used (or link to a benchmark citation). Ensure the table cells containing "10-100x" and the paragraph mentioning "40-70%" cite the benchmark source or a footnote that links to the benchmark data, and keep the language non-absolute (use "typical", "up to", or "in our tests").
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@docs/oss/core-concepts/performance-benchmarks.md`:
- Line 18: Update the generalized performance claims in the table and
surrounding text (specifically the "10-100x" and "40-70%" entries) to include
benchmark context and sources: either replace the raw ranges with qualified
phrasing (e.g., "up to 10–100x depending on workload and hardware" or "typical
improvements of 40–70% in I/O-bound workloads") and add a short parenthetical
describing workload, hardware, and profiler used (or link to a benchmark
citation). Ensure the table cells containing "10-100x" and the paragraph
mentioning "40-70%" cite the benchmark source or a footnote that links to the
benchmark data, and keep the language non-absolute (use "typical", "up to", or
"in our tests").
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 68e44f00-afe0-41c6-b341-14d12be5f4c6
📒 Files selected for processing (3)
docs/oss/building-features/debugging.mddocs/oss/core-concepts/execjs-limitations.mddocs/oss/core-concepts/performance-benchmarks.md
✅ Files skipped from review due to trivial changes (2)
- docs/oss/core-concepts/execjs-limitations.md
- docs/oss/building-features/debugging.md
Documentation PR ReviewOverall this is a well-structured addition of four documentation pages that fill real gaps (debugging guide, ExecJS limitations, benchmarks, RSC landing page). The cross-referencing is good. A few issues need attention before merging: Factual Issues1. mini_racer vs Node.js runtime performance claim is reversed ( The document states "Node.js generally provides better performance" than mini_racer, but this is backwards. mini_racer runs V8 directly inside the Ruby process (no subprocess or IPC overhead), while the ExecJS Node.js runtime communicates via stdin/stdout IPC with a subprocess. In practice, mini_racer is faster for SSR. This claim is also inconsistent with the table in 2. Selective hydration attribution to React 19 (
Selective hydration was introduced in React 18 alongside 3. Non-existent debugging command ( # Install the binstub (one-time): rake shakapacker:binstubs
bin/shakapacker-config --doctor
Minor Points
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 27856738f4
ℹ️ 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".
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/oss/core-concepts/performance-benchmarks.md (1)
18-18: Qualify or cite broad benchmark ranges to avoid over-claiming.
10-100xand40-70%are impactful numbers; adding a short methodology note or source link would make these claims more durable and defensible.✍️ Suggested wording tweak
-| Typical speedup | Baseline | Comparable | 10-100x over ExecJS | +| Typical speedup | Baseline | Comparable | Often significantly faster (workload-dependent) | ... -For applications with many routes and components, code splitting typically reduces initial bundle size by 40-70%, depending on how much code is shared across routes. +For applications with many routes and components, code splitting can substantially reduce initial bundle size, depending on route structure and shared dependencies. +If available, include measurements from your app (for example, before/after webpack-bundle-analyzer reports).Also applies to: 33-33
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/oss/core-concepts/performance-benchmarks.md` at line 18, The table row showing "10-100x over ExecJS" (and related "40-70%" elsewhere) needs a short methodology note and/or citation added to qualify the claim: update the table cell text to include a parenthetical like "(see methodology footnote)" or add a superscript link marker, then add a brief footnote or endnote below the table that states the benchmark methodology (hardware, workload, dataset, measurement method) and a source link or reference to the test results; ensure the same treatment is applied to the "40-70%" number so both figures are qualified and a reader can verify the origin.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/oss/core-concepts/performance-benchmarks.md`:
- Line 45: The table header row uses unhyphenated compound adjectives; update
phrases like "Full Page Load" to "Full-page Load" and any other occurrences such
as "Server Side" or "Server Side Rendering" to "Server-side" / "Server-side
rendering" for consistent compound-adjective hyphenation (edit the table header
line containing "Rendering Strategy | TTFB | Full Page Load" and the other
matching occurrence).
---
Nitpick comments:
In `@docs/oss/core-concepts/performance-benchmarks.md`:
- Line 18: The table row showing "10-100x over ExecJS" (and related "40-70%"
elsewhere) needs a short methodology note and/or citation added to qualify the
claim: update the table cell text to include a parenthetical like "(see
methodology footnote)" or add a superscript link marker, then add a brief
footnote or endnote below the table that states the benchmark methodology
(hardware, workload, dataset, measurement method) and a source link or reference
to the test results; ensure the same treatment is applied to the "40-70%" number
so both figures are qualified and a reader can verify the origin.
🪄 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: 2329b690-8cc6-48c6-bc1a-f127df5fe26d
📒 Files selected for processing (2)
docs/oss/core-concepts/execjs-limitations.mddocs/oss/core-concepts/performance-benchmarks.md
✅ Files skipped from review due to trivial changes (1)
- docs/oss/core-concepts/execjs-limitations.md
|
Documentation-only PR with no runtime risk. Four issues flagged via inline comments:
|
- Align Node renderer speedup claim to "10-100x" (was "Several times"), matching oss-vs-pro.md and other pages - Add missing clearTimeout to ExecJS unsupported timer list - Fix misleading server-bundle manifest grep in debugging guide (server bundles default to ssr-generated/, not public/packs/) - Fix incorrect ReactOnRails.getComponents() API name in troubleshooting.md (correct: registeredComponents()) - Qualify Node renderer timer/module capabilities with required config (stubTimers defaults on, supportModules defaults off) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Replace unsupported "10-100x over ExecJS" with data-backed "3-10x" range and link to Popmenu case study for evidence - Clarify that node renderer requires separate npm package install, not "included with Pro" Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The selective hydration section described benefits as if they work by default, but React on Rails uses defer scripts by default which defeat selective hydration. Added a note about the required generated_component_packs_loading_strategy = :async configuration. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Fix hardcoded server-bundle.js filename in debugging.md (defaults to "") - Fix DOM id example: use UUID format matching random_dom_id default - Fix doctor task description: runs diagnostics, not config dump - Fix timer error messages: RoR injects stubs, so ReferenceError won't occur - Align SSR speedup claims to data-backed "3-10x" across all pages - Soften unsourced 40-70% bundle reduction claim Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
justin808
force-pushed
the
jg/2781-add-docs-pages
branch
from
1dab611 to
fcbb24a
Compare
|
Overall this is a well-structured documentation addition. The new pages are accurate, well-organized, and cross-referenced properly. A few items to address. Issue 1: Incomplete 10-100x to 3-10x update — two files missed The PR correctly updates the performance claim in several files, but two instances were missed:
Additionally, Issue 2: RSC version constraint will become stale In Minor Notes
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: fcbb24a317
ℹ️ 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".
| In most cases, you should use the `prerender: false` (default behavior) with the provided helper method to render the React component from your Rails views. In some cases, such as when SEO is vital, or many users will not have JavaScript enabled, you can enable server-rendering by passing `prerender: true` to your helper, or you can simply change the default in `config/initializers/react_on_rails`. | ||
|
|
||
| Now the server will interpret your JavaScript. The default is to use [ExecJS](https://github.com/rails/execjs) and pass the resulting HTML to the client. By default, ExecJS uses the Node.js runtime. You can use alternative runtimes as outlined in [ExecJS readme](https://github.com/rails/execjs/blob/master/README.md). | ||
| Now the server will interpret your JavaScript. The default is to use [ExecJS](https://github.com/rails/execjs) and pass the resulting HTML to the client. By default, ExecJS uses the Node.js runtime. You can use alternative runtimes as outlined in [ExecJS readme](https://github.com/rails/execjs/blob/master/README.md). For details on ExecJS constraints with timers, async, and browser APIs, see [ExecJS Limitations](./execjs-limitations.md). |
There was a problem hiding this comment.
Fresh evidence: this commit repeats the same default-runtime claim in a second SSR guide. React on Rails never selects ExecJS.runtime; RubyEmbeddedJavaScript#create_js_context just calls ExecJS.compile, so apps with mini_racer or another installed ExecJS runtime will not be using Node here. That sends readers to the wrong runtime-specific troubleshooting path, especially because the very next note discusses a mini_racer-only TextEncoder failure.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Duplicate of the ExecJS runtime detection comment on execjs-limitations.md. Tracking the broader ExecJS accuracy review in a follow-up issue.
| - **Largest Contentful Paint (LCP):** When the main content becomes visible | ||
| - **Total Blocking Time (TBT):** Time the main thread is blocked during page load | ||
| - **Client bundle size:** Total JavaScript downloaded by the browser | ||
| - **Server render time:** Time spent in the SSR process (logged by React on Rails when `logging_on_server` is enabled) |
There was a problem hiding this comment.
This measurement guidance points readers to a metric React on Rails does not emit. logging_on_server only replays captured console lines to Rails.logger in RubyEmbeddedJavaScript#parse_result_and_replay_console_messages, and the Pro streaming helpers only add disconnect warnings; neither path records per-request render durations. Users following this section will waste time hunting through Rails logs for "server render time" instead of adding their own instrumentation or using the node renderer's timing logs.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Valid point — logging_on_server replays console messages, not render durations. Tracking in a follow-up issue to clarify what metrics are actually available.
Aligns the SSR tip block in react-server-rendering.md with the 3-10x figure used consistently across all other docs pages. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
test |
Documentation GuideReact on Rails is one product with two tiers: open source for Rails + React integration, and Pro when you need higher SSR throughput, deeper RSC support, or maintainer-backed help. Choose the path that matches your appStarting a new Rails + React appAdding React to an existing Rails appAlready using React on Rails OSS?Evaluating Rails + React optionsDive deeper when you need itPro features
Friendly evaluation policy
Need more help? |
CLAUDE.mdTool-specific guidance for Claude Code in this repository. Source of Truth
If this file conflicts with Behavioral Defaults
Git Safety
Claude-Specific WorkflowUse these docs for Claude-oriented operational guidance:
For Pro-package specifics, also read |
AGENTS.mdInstructions for AI coding agents working on the React on Rails codebase. React on Rails is a Ruby gem + npm package that integrates React with Ruby on Rails, providing server-side rendering (SSR) via Node.js or ExecJS. This is a monorepo: the open-source gem lives at Reusable Workflows
Canonical Agent Policy
Other agent-facing docs (for example Commands# Install dependencies
bundle && pnpm install
# Build TypeScript → JavaScript
pnpm run build
# Lint (MANDATORY before every commit)
bundle exec rubocop # Ruby — must pass with zero offenses
pnpm run lint # JS/TS via ESLint
pnpm start format.listDifferent # Check Prettier formatting
rake lint # All linting (Ruby + JS + formatting)
# Auto-fix formatting
rake autofix # Preferred for all formatting
# Run tests
rake run_rspec:gem # Ruby unit tests (gem code)
rake run_rspec:dummy # Ruby integration tests (dummy Rails app)
pnpm run test # JavaScript/TypeScript tests
rake # Full suite (lint + all tests except examples)
# Type checking
pnpm run type-check # TypeScript
bundle exec rake rbs:validate # RBS signatures
# Additional test subsets
rake run_rspec # All Ruby tests
rake all_but_examples # All tests except generated examples
rake run_rspec:shakapacker_examples_basic # Single example test
# Full initial setup
bundle && pnpm install && rake shakapacker_examples:gen_all && rake node_package && rake
# CI/workflow linting
actionlint # GitHub Actions lint
yamllint .github/ # YAML lint (do NOT run RuboCop on .yml files)
# Dependency version updates
rake shakapacker:update_version[9.6.1] # Update shakapacker across the monorepoUpdating ShakapackerUse The task handles Ruby version switching for apps that require a different Ruby version (set Testing
Run specific test files: bundle exec rspec react_on_rails/spec/react_on_rails/path/to/spec.rb
cd react_on_rails/spec/dummy && bundle exec rspec spec/path/to/spec.rbProject Structure
Code StyleRuby (RuboCop)Line length max 120 characters. Run Line length — break long chains: # Bad
content = pack_content.gsub(/import.*from.*['"];/, "").gsub(/ReactOnRails\.register.*/, "")
# Good
content = pack_content.gsub(/import.*from.*['"];/, "")
.gsub(/ReactOnRails\.register.*/, "")Named subjects in RSpec: # Bad
subject { instance.method_name(arg) }
# Good
subject(:method_result) { instance.method_name(arg) }Security violations — scope disable comments tightly: # rubocop:disable Security/Eval
expect { evaluate(sanitized_content) }.not_to raise_error
# rubocop:enable Security/EvalJavaScript/TypeScriptPrettier handles all formatting. Never manually format — run Git WorkflowBranch naming: Commit messages: Explain why, not what. One logical change per commit. PR creation: Use Review WorkflowFor small, focused PRs (roughly 5 files changed or fewer and one clear purpose):
BoundariesAlways
Ask First
Never
Key Concept: File Suffixes vs. RSC DirectiveReact on Rails has two independent systems that both use "client" and "server" terminology. Do not confuse them. 1. Bundle Placement (
|
Code ReviewThis PR adds four documentation pages (debugging guide, ExecJS limitations, performance benchmarks, RSC landing) plus cross-reference updates. Overall the content is accurate and well-structured. A few items worth discussing: All internal links verified - every relative path in the new files resolves to an existing file in the repo. All technical claims verified:
Issues worth addressing:
The async section shows fetch() inside an async component with the comment Never completes in ExecJS. But fetch is itself a browser API that is also unavailable in ExecJS (same as window/document) - it is not merely async. A user might think the fix is to make their fetch call synchronous, when fetch is simply not available at all. The example would be clearer using a plain await somePromise instead, or by adding a note that fetch is doubly unavailable.
The page is titled Performance Benchmarks but contains no actual benchmark numbers - only qualitative descriptors (Baseline, 3-10x over ExecJS), one real-world case study (Popmenu 73%), and a Frigade blog reference. Consider renaming to Performance Characteristics or Performance Overview, or adding a note that the 3-10x figure is an observed range from production deployments rather than a controlled benchmark.
React 19.0.x (19.1.x and later are not yet supported) is a patch-level constraint that will become outdated quickly (19.1.x is already released). The same wording is in docs/oss/api-reference/generator-details.md. Consider linking to the CHANGELOG or a compatibility matrix rather than hardcoding it in the landing page. Minor nits (not blocking):
|
|
|
||
| ```javascript | ||
| // This component will render before data loads | ||
| async function UserProfile({ userId }) { |
There was a problem hiding this comment.
The comment "Never completes in ExecJS" frames this as an async/await problem, but fetch is also a browser API that is unavailable in ExecJS entirely (same as window/document). A user might conclude the fix is to make the fetch synchronous, when fetch doesn't exist at all in ExecJS.
Consider replacing fetch with a plain promise to keep the example focused on the async limitation:
| async function UserProfile({ userId }) { | |
| const data = await loadUserData(userId); // Promise never resolves in ExecJS |
Or add a note: "fetch is also unavailable in ExecJS (it's a browser API) — this example fails for two reasons: fetch is undefined, and even if it weren't, the Promise would never resolve."
| @@ -0,0 +1,127 @@ | |||
| # Performance Benchmarks | |||
There was a problem hiding this comment.
The page title "Performance Benchmarks" sets an expectation of reproducible, controlled benchmark data. However the content only has qualitative comparisons ("3-10x over ExecJS", "Baseline", "Comparable"), one production case study (Popmenu), and an external blog post. There are no actual numbers from a controlled benchmark run.
Consider renaming to "Performance Characteristics" or "Performance Overview" to better match the content, or add a callout noting that figures like "3-10x" are observed ranges from production deployments and not controlled benchmarks.
| # Performance Benchmarks | |
| # Performance Characteristics |
|
|
||
| - React on Rails Pro v4.0.0 or higher | ||
| - React 19.0.x (19.1.x and later are not yet supported) | ||
| - React on Rails v16.0.0 or higher |
There was a problem hiding this comment.
This patch-level version constraint will go stale quickly — React 19.1.x is already released. The same wording also appears in docs/oss/api-reference/generator-details.md. Hardcoding this in the landing page means users will see incorrect requirements after support is extended.
Consider linking to a maintained reference instead, e.g.:
| - React on Rails v16.0.0 or higher | |
| - React 19.0.x or later (see [CHANGELOG](../../../CHANGELOG.md) for current compatibility) |
Or at minimum, make it clear this is a current snapshot: "As of React on Rails Pro v4.0, React 19.0.x is supported; 19.1.x is not yet validated."
## Summary Fixes #2804 Audits and corrects ExecJS technical claims across four docs pages added in #2785: - **Runtime auto-detection**: Corrected "By default, ExecJS uses the Node.js runtime" — ExecJS actually auto-detects via `best_available`, preferring mini_racer and Bun over Node.js - **Node.js process model**: Changed "Persistent subprocess via IPC" to "New process per eval call" — ExecJS's `ExternalRuntime` spawns a fresh Node.js process per evaluation via `IO.popen` - **Timer polyfill behavior**: Corrected debugging page claim that users see `setTimeout is not defined` errors — React on Rails polyfills timers as silent no-ops (or console.error with `trace: true`) - **SSR timing logging**: Removed incorrect claim that `logging_on_server` logs render durations — it actually replays console messages to `Rails.logger` - **pool_size explanation**: Improved accuracy of why `pool_size=1` is required on MRI, citing the actual threading/deadlock cause and linking to #1438 ## Test plan - [ ] Verify all four docs pages render correctly in the documentation site - [ ] Confirm no broken markdown links - [ ] Cross-reference claims against ExecJS source code and React on Rails `RubyEmbeddedJavaScript` 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Docs-only changes; risk is limited to potentially confusing readers if any updated ExecJS/runtime claims are still inaccurate. > > **Overview** > Updates OSS docs to correct several ExecJS-related technical claims across debugging, rendering, limitations, and performance pages. > > Clarifies that ExecJS *auto-selects* the best available runtime (override via `EXECJS_RUNTIME`), explains that timer APIs are stubbed as no-ops during SSR (with `clearInterval` runtime-dependent) and how `trace`/`replay_console`/`logging_on_server` surface warnings, fixes the Node.js runtime process model description, and refines guidance on SSR timing measurement and why MRI requires `server_renderer_pool_size = 1` (deadlock explanation + issue link). > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 5296d8b. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY --> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Clarified ExecJS runtime auto-detection: it now prefers the best available runtime (may choose mini_racer or Bun over Node) and can be overridden via an environment variable. * Clarified SSR timer behavior: common timer functions are stubbed as no-ops, some clear operations may vary by runtime, and trace/logging settings emit warnings that can be replayed to browser devtools and Rails logs. * Updated guidance on renderer/process behavior, server render timing measurement, and server-render pool-size considerations. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary - Stamp `### [16.5.0.rc.0]` version header with today's date - Add 10 new changelog entries for PRs merged since v16.4.0 - Fix incomplete PR 2818 entry (missing author link) ### New entries added **Added:** - `create-react-on-rails-app --pro` support (PR 2818) - Global prerender env override `REACT_ON_RAILS_PRERENDER_OVERRIDE` (PR 2816) - `react_on_rails:sync_versions` rake task (PR 2797) - Pro/RSC setup checks in `react_on_rails:doctor` (PR 2674) **Changed:** - [Pro] Canonical env var for worker count is now `RENDERER_WORKERS_COUNT` (PR 2611) **Improved:** - Smoother `create-react-on-rails-app` and install generator flows (PR 2650) - Pro upgrade hint after install (PR 2642) **Fixed:** - Preserve runtime env vars across `Bundler.with_unbundled_env` (PR 2836) - Fix doctor prerender check and ExecJS display for Pro/RSC apps (PR 2773) - Fix doctor false positives for custom layouts (PR 2612) ### Skipped PRs (not user-visible) Docs-only: #2845, #2842, #2826, #2830, #2820, #2809, #2803, #2785, #2801, #2791, #2789, #2788, #2772, #2778, #2780, #2784, #2671, #2676, #2662, #2657, #2669 CI/internal tooling: #2825, #2817, #2819, #2812, #2815, #2810, #2808, #2807, #2634, #2798, #2761, #2760, #2658, #2639, #2667, #2656 ## Test plan - [x] Verified version header and diff links are correct - [x] Verified all entries follow changelog formatting conventions - [x] Verified file ends with newline - [ ] After merge, run `rake release` to publish 16.5.0.rc.0 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Documentation-only change updating `CHANGELOG.md` with a new `16.5.0.rc.0` section and compare links; no runtime code is modified. > > **Overview** > Adds a new `16.5.0.rc.0` (2026-03-25) section to `CHANGELOG.md`, consolidating recent PR entries under **Added/Changed/Improved/Fixed** and correcting the previously incomplete `--pro` CLI entry author attribution. > > Updates the bottom compare links so `[unreleased]` now compares from `v16.5.0.rc.0` and adds a link definition for `[16.5.0.rc.0]`. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 481a71c. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY --> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit ## Release Notes - v16.5.0.rc.0 * **New Features** * Added sync_versions task for streamlined version management * Expanded doctor checks for Pro and RSC support * **Improvements** * Enhanced generator workflow and Pro upgrade guidance * Improved environment variable handling and preservation * **Bug Fixes** * Fixed detection issues with doctor tools and ExecJS/prerender functionality <!-- end of auto-generated comment: release notes by coderabbit.ai --> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…pages (#2785) - Add RSC landing page (`docs/pro/react-server-components/index.md`) — top-level introduction to React Server Components support, linking to tutorial, migration guide, and deep dives - Add ExecJS Limitations page (`docs/oss/core-concepts/execjs-limitations.md`) — documents timer/async constraints, common errors, workarounds, and migration path to Node renderer - Add Debugging Guide (`docs/oss/building-features/debugging.md`) — SSR debugging workflows, hydration mismatch diagnosis, log locations, and configuration tips - Add Performance Benchmarks page (`docs/oss/core-concepts/performance-benchmarks.md`) — ExecJS vs Node renderer comparison, bundle splitting impact, streaming SSR benefits, and real-world results - Add cross-references from existing docs (client-vs-server-rendering, react-server-rendering, troubleshooting, oss-vs-pro) to the new pages Closes #2781 - [ ] Verify all internal links resolve correctly - [ ] Confirm new pages follow existing doc formatting conventions - [ ] CI passes 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Low risk: documentation-only changes plus minor wording/link updates; main risk is broken or incorrect doc links/claims. > > **Overview** > Adds new documentation pages for **debugging SSR/hydration issues** (including recommended `ReactOnRails.configure` flags), **ExecJS SSR limitations** (timers/async/browser APIs and workarounds), and **SSR performance benchmarks** comparing ExecJS vs the Pro Node renderer. > > Introduces a Pro **React Server Components** landing page that links into tutorials/migration/deep-dives, and updates several existing docs to cross-link to the new pages, fix a component-registration console snippet (`registeredComponents()`), and standardize Node renderer performance claims to *3–10x* with a benchmark reference. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit cb657d0. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY --> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> * **Documentation** * Added a comprehensive debugging guide for SSR, hydration mismatches, log inspection, and debug flags for enhanced server-side diagnostics. * Documented ExecJS runtime limitations (timers, async, browser globals, pool-size caveats) and Node renderer migration guidance. * Added performance benchmarks comparing rendering approaches, streaming SSR, and bundle impacts. * Introduced React Server Components docs for Pro with streaming, integration, and migration guidance. * Minor cross-reference and troubleshooting updates. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary Fixes #2804 Audits and corrects ExecJS technical claims across four docs pages added in #2785: - **Runtime auto-detection**: Corrected "By default, ExecJS uses the Node.js runtime" — ExecJS actually auto-detects via `best_available`, preferring mini_racer and Bun over Node.js - **Node.js process model**: Changed "Persistent subprocess via IPC" to "New process per eval call" — ExecJS's `ExternalRuntime` spawns a fresh Node.js process per evaluation via `IO.popen` - **Timer polyfill behavior**: Corrected debugging page claim that users see `setTimeout is not defined` errors — React on Rails polyfills timers as silent no-ops (or console.error with `trace: true`) - **SSR timing logging**: Removed incorrect claim that `logging_on_server` logs render durations — it actually replays console messages to `Rails.logger` - **pool_size explanation**: Improved accuracy of why `pool_size=1` is required on MRI, citing the actual threading/deadlock cause and linking to #1438 ## Test plan - [ ] Verify all four docs pages render correctly in the documentation site - [ ] Confirm no broken markdown links - [ ] Cross-reference claims against ExecJS source code and React on Rails `RubyEmbeddedJavaScript` 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Docs-only changes; risk is limited to potentially confusing readers if any updated ExecJS/runtime claims are still inaccurate. > > **Overview** > Updates OSS docs to correct several ExecJS-related technical claims across debugging, rendering, limitations, and performance pages. > > Clarifies that ExecJS *auto-selects* the best available runtime (override via `EXECJS_RUNTIME`), explains that timer APIs are stubbed as no-ops during SSR (with `clearInterval` runtime-dependent) and how `trace`/`replay_console`/`logging_on_server` surface warnings, fixes the Node.js runtime process model description, and refines guidance on SSR timing measurement and why MRI requires `server_renderer_pool_size = 1` (deadlock explanation + issue link). > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 5296d8b. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY --> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Clarified ExecJS runtime auto-detection: it now prefers the best available runtime (may choose mini_racer or Bun over Node) and can be overridden via an environment variable. * Clarified SSR timer behavior: common timer functions are stubbed as no-ops, some clear operations may vary by runtime, and trace/logging settings emit warnings that can be replayed to browser devtools and Rails logs. * Updated guidance on renderer/process behavior, server render timing measurement, and server-render pool-size considerations. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…pages (#2785) - Add RSC landing page (`docs/pro/react-server-components/index.md`) — top-level introduction to React Server Components support, linking to tutorial, migration guide, and deep dives - Add ExecJS Limitations page (`docs/oss/core-concepts/execjs-limitations.md`) — documents timer/async constraints, common errors, workarounds, and migration path to Node renderer - Add Debugging Guide (`docs/oss/building-features/debugging.md`) — SSR debugging workflows, hydration mismatch diagnosis, log locations, and configuration tips - Add Performance Benchmarks page (`docs/oss/core-concepts/performance-benchmarks.md`) — ExecJS vs Node renderer comparison, bundle splitting impact, streaming SSR benefits, and real-world results - Add cross-references from existing docs (client-vs-server-rendering, react-server-rendering, troubleshooting, oss-vs-pro) to the new pages Closes #2781 - [ ] Verify all internal links resolve correctly - [ ] Confirm new pages follow existing doc formatting conventions - [ ] CI passes 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Low risk: documentation-only changes plus minor wording/link updates; main risk is broken or incorrect doc links/claims. > > **Overview** > Adds new documentation pages for **debugging SSR/hydration issues** (including recommended `ReactOnRails.configure` flags), **ExecJS SSR limitations** (timers/async/browser APIs and workarounds), and **SSR performance benchmarks** comparing ExecJS vs the Pro Node renderer. > > Introduces a Pro **React Server Components** landing page that links into tutorials/migration/deep-dives, and updates several existing docs to cross-link to the new pages, fix a component-registration console snippet (`registeredComponents()`), and standardize Node renderer performance claims to *3–10x* with a benchmark reference. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit cb657d0. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY --> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> * **Documentation** * Added a comprehensive debugging guide for SSR, hydration mismatches, log inspection, and debug flags for enhanced server-side diagnostics. * Documented ExecJS runtime limitations (timers, async, browser globals, pool-size caveats) and Node renderer migration guidance. * Added performance benchmarks comparing rendering approaches, streaming SSR, and bundle impacts. * Introduced React Server Components docs for Pro with streaming, integration, and migration guidance. * Minor cross-reference and troubleshooting updates. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary Fixes #2804 Audits and corrects ExecJS technical claims across four docs pages added in #2785: - **Runtime auto-detection**: Corrected "By default, ExecJS uses the Node.js runtime" — ExecJS actually auto-detects via `best_available`, preferring mini_racer and Bun over Node.js - **Node.js process model**: Changed "Persistent subprocess via IPC" to "New process per eval call" — ExecJS's `ExternalRuntime` spawns a fresh Node.js process per evaluation via `IO.popen` - **Timer polyfill behavior**: Corrected debugging page claim that users see `setTimeout is not defined` errors — React on Rails polyfills timers as silent no-ops (or console.error with `trace: true`) - **SSR timing logging**: Removed incorrect claim that `logging_on_server` logs render durations — it actually replays console messages to `Rails.logger` - **pool_size explanation**: Improved accuracy of why `pool_size=1` is required on MRI, citing the actual threading/deadlock cause and linking to #1438 ## Test plan - [ ] Verify all four docs pages render correctly in the documentation site - [ ] Confirm no broken markdown links - [ ] Cross-reference claims against ExecJS source code and React on Rails `RubyEmbeddedJavaScript` 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Docs-only changes; risk is limited to potentially confusing readers if any updated ExecJS/runtime claims are still inaccurate. > > **Overview** > Updates OSS docs to correct several ExecJS-related technical claims across debugging, rendering, limitations, and performance pages. > > Clarifies that ExecJS *auto-selects* the best available runtime (override via `EXECJS_RUNTIME`), explains that timer APIs are stubbed as no-ops during SSR (with `clearInterval` runtime-dependent) and how `trace`/`replay_console`/`logging_on_server` surface warnings, fixes the Node.js runtime process model description, and refines guidance on SSR timing measurement and why MRI requires `server_renderer_pool_size = 1` (deadlock explanation + issue link). > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 5296d8b. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY --> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Clarified ExecJS runtime auto-detection: it now prefers the best available runtime (may choose mini_racer or Bun over Node) and can be overridden via an environment variable. * Clarified SSR timer behavior: common timer functions are stubbed as no-ops, some clear operations may vary by runtime, and trace/logging settings emit warnings that can be replayed to browser devtools and Rails logs. * Updated guidance on renderer/process behavior, server render timing measurement, and server-render pool-size considerations. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 participant
Summary
docs/pro/react-server-components/index.md) — top-level introduction to React Server Components support, linking to tutorial, migration guide, and deep divesdocs/oss/core-concepts/execjs-limitations.md) — documents timer/async constraints, common errors, workarounds, and migration path to Node rendererdocs/oss/building-features/debugging.md) — SSR debugging workflows, hydration mismatch diagnosis, log locations, and configuration tipsdocs/oss/core-concepts/performance-benchmarks.md) — ExecJS vs Node renderer comparison, bundle splitting impact, streaming SSR benefits, and real-world resultsCloses #2781
Test plan
🤖 Generated with Claude Code
Note
Low Risk
Low risk: documentation-only changes plus minor wording/link updates; main risk is broken or incorrect doc links/claims.
Overview
Adds new documentation pages for debugging SSR/hydration issues (including recommended
ReactOnRails.configureflags), ExecJS SSR limitations (timers/async/browser APIs and workarounds), and SSR performance benchmarks comparing ExecJS vs the Pro Node renderer.Introduces a Pro React Server Components landing page that links into tutorials/migration/deep-dives, and updates several existing docs to cross-link to the new pages, fix a component-registration console snippet (
registeredComponents()), and standardize Node renderer performance claims to 3–10x with a benchmark reference.Written by Cursor Bugbot for commit cb657d0. This will update automatically on new commits. Configure here.
Summary by CodeRabbit