Walkthrough

Documentation-only revisions clarifying component registration detection (parameter-count and .renderFunction), enumerating render-function/renderer-function return shapes and compatibility, deprecating legacy redirectLocation/routeError, documenting forced prerender behavior for react_component_hash/stream_react_component, noting registerServerComponent signature differences, and adding React Router <Navigate> SSR guidance.

Changes

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 I hopped through docs with nimble feet,

Marked old redirects as legacy and neat.
Prerender forced, signatures split in two,
<Navigate> on server? It renders null—who knew.
A tiny rabbit hop to make things true.

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 help to get the list of available commands and usage tips.}

Review Summary

Good overall: most documented behaviors are verified against source (component detection by parameter count, react_component_hash forcing prerender: true, ExecJS async silently returning '{}', server render result key detection, and clientProps merge/error behavior all confirmed accurate). The compatibility matrix and legacy callouts are helpful additions.

Two factual inaccuracies need fixing before merge:

1. stream_react_component and immediate_hydration

Both docs/oss/api-reference/view-helpers-api.md (line 163) and docs/oss/core-concepts/render-functions.md (line 258) claim:

stream_react_component always forces prerender: true and immediate_hydration: true

This is wrong. The Pro helper source (react_on_rails_pro_helper.rb) shows:

if options.key?(:immediate_hydration)
  ReactOnRails::Helper.warn_removed_immediate_hydration_option("stream_react_component")
  options.delete(:immediate_hydration)
end

immediate_hydration is a removed option — it gets deleted with a deprecation warning. The docs should say it is no longer supported, not that it is forced to true.

2. registerServerComponent client bundle signature

docs/pro/react-server-components/inside-client-components.md (line 69) documents the client signature as:

registerServerComponent({ rscPayloadGenerationUrlPath: '...' }, 'Name1', 'Name2')

The actual TypeScript signature in packages/react-on-rails-pro/src/registerServerComponent/client.tsx is:

const registerServerComponent = (...componentNames: string[]) => {

No options object is accepted. The rscPayloadGenerationUrlPath appears only in the JSDoc as an explanation of URL construction internals. Correct usage is just registerServerComponent('Name1', 'Name2').

Greptile Summary

This PR comprehensively improves the render-function and view-helper API documentation by adding legacy markers for redirectLocation/routeError, a new compatibility matrix, prerender-forcing behavior for react_component_hash and stream_react_component, a <Navigate> SSR behavior section, and a registerServerComponent signature callout. All behavioral claims were verified against source code (isRenderFunction.ts, isServerRenderResult.ts, helper.rb). One P2 inaccuracy exists in the new compatibility matrix: the Render function → Promise (any) row marks react_component_hash as supported, but only promises resolving to a server-side hash (Return Type 6) are valid — promises of React components or plain strings would cause a runtime error.

Confidence Score: 5/5

Safe to merge — documentation-only changes with one minor matrix inaccuracy that doesn't affect runtime behavior

All behavioral claims were verified against the source code. The single P2 finding (compatibility matrix overstating Promise support for react_component_hash) is a documentation nuance that doesn't cause silent failures — developers would get a visible runtime error. No executable code changed.

docs/oss/core-concepts/render-functions.md — the compatibility matrix row for Promise types

Important Files Changed

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Render Function return value] --> B{isServerRenderHash?}
    B -- "has renderedHtml / redirectLocation / routeError / error key" --> C[Server Render Hash path]
    B -- "no match" --> D{isPromise?}
    D -- yes --> E[Promise path\nPro Node renderer only]
    D -- no --> F[React Component path\ncreateReactOutput]

    C --> G{renderedHtml type?}
    G -- "string" --> H[react_component ✅]
    G -- "ReactElement" --> I[react_component prerender ✅]
    G -- "{ componentHtml, ...keys }" --> J[react_component_hash ✅]

    E --> K{resolves to?}
    K -- "string / React component" --> H
    K -- "{ componentHtml, ...keys }" --> J
    K -- "Promise of React component" --> H

    F --> L[react_component ✅\nstream_react_component ✅]

_{Reviews (1): Last reviewed commit: "docs: fix render function/helper API doc..." | Re-trigger Greptile}

Review feedback addressed (ed159a9)

Three factual inaccuracies fixed, verified against source code:

1. stream_react_component and immediate_hydration — The docs incorrectly said immediate_hydration: true is forced. The Pro helper source (react_on_rails_pro_helper.rb:131-133) shows the option is warned and deleted. Fixed in both view-helpers-api.md and render-functions.md.

2. registerServerComponent client signature — Docs showed an options object as the first argument. The actual client source (client.tsx:51) accepts only (...componentNames: string[]). Fixed in inside-client-components.md.

3. Promise "(any)" overstated for react_component_hash — Changed to "Promise (compatible return shape)" with a note that react_component_hash requires the promise to resolve to a hash with componentHtml.

Declined: Streaming Promise support claim (item 4) — needs full pipeline verification, deferred to follow-up.
Skipped: MD028 blank blockquote nit (between two separate blockquotes, not inside one).

All 8 review threads resolved with replies.

Review: docs/fix render function/helper API documentation

Overall this is a high-quality documentation PR — the compatibility matrix, clientProps merge clarifications, stream_react_component / react_component_hash behavior notes, and async+ExecJS gotcha are all accurate (verified against source). The registerServerComponent signature warning is a genuinely useful addition for Pro users. A few things warrant attention:

1. "Legacy (React Router v3/v4)" framing for redirectLocation/routeError is inaccurate

The PR labels these as deprecated legacy features, but they are actively handled in the current codebase with no deprecation markers:

• serverRenderReactComponent.ts destructures and processes both fields in processServerRenderHash (lines 27–52)
• types/index.ts defines them on ServerRenderResult without any @deprecated JSDoc tag (lines 129–130)
• isServerRenderResult.ts explicitly checks for redirectLocation and routeError as primary server-render-hash detection keys

A developer writing a custom render function against React Router v6 (or any router) can still return these fields and they will be handled correctly. The PR correctly describes their limitations (no actual server-side redirect, routeError only triggers raise_on_prerender_error), but calling them a "Legacy feature from React Router v3/v4" overstates their obsolescence and may break working code for users who read this as "stop using this."

Suggestion: Keep the limitations section, but reframe from [!WARNING] / "Legacy" to a [!NOTE] explaining the limitations and pointing to Rails controller redirects as the preferred approach for auth/SEO — without declaring the feature deprecated when the code does not.

2. .renderFunction = true description is slightly misleading in the new JSDoc

The rewritten register() JSDoc says:

* - 2 params (or `.renderFunction = true`): Render-Function ...

This implies .renderFunction = true is an alias specifically for 2-param functions. In reality, the check in isRenderFunction.ts evaluates .renderFunction before the parameter-length check — a 1-param function with .renderFunction = true is also treated as a render function (skipping the railsContext parameter entirely). This pattern is already documented in render-functions.md and is common enough that the JSDoc should mention it clearly.

3. Minor: Compatibility matrix ❌ for react_component + { renderedHtml: { componentHtml, ... } }

The table shows ❌ for this combination, but react_component doesn't error on it — it silently renders the whole object as JSON text (garbled output). The ❌ implies a hard failure; a note clarifying "works but produces unexpected output" would help users diagnose the actual symptom.

4. Minor: using-react-on-rails.md example fix is good but the custom keys look prescriptive

The original had redirectLocation and error nested inside renderedHtml (which was wrong — they're top-level fields). The fix to title/metaTags is correct. Consider a brief comment that these are developer-defined custom keys, not framework-reserved names, so readers understand the pattern is open-ended:

renderedHtml: {
  componentHtml, // required — the main HTML string
  title,         // example custom key (any name works here)
  metaTags,      // example custom key (any name works here)
},

Review feedback addressed (3c427ba)

I (Claude Code) addressed all 6 remaining review comments:

Accuracy fixes:

1. javascript-api.md:30 — Fixed .renderFunction = true wording to clarify it works for any param count, not just 2-param functions (matches isRenderFunction.ts check order)
2. react-router.md:188 — Removed unverifiable claim that <Navigate> "logs a warning in development mode" during SSR. Updated to explain the actual mechanism (useEffect doesn't fire on server)
3. render-functions.md:241-244 — Added note below compatibility matrix: "❌ means silently produces incorrect output, not that it throws an error" with specific failure mode examples

Framing & detail improvements:
4. render-functions.md:127 — Changed [!WARNING] + "Legacy feature" to [!NOTE] + "have significant limitations", since these fields are still actively processed without @deprecated markers
5. render-functions.md:166 — Expanded error key description to explain downstream consequence: value is treated as exception descriptor that can trigger raise_on_prerender_error
6. create-without-ssr.md:346 — Fixed outdated client registerServerComponent example from ({ rscPayloadGenerationUrlPath }, name) to (name) to match actual API at packages/react-on-rails-pro/src/registerServerComponent/client.tsx

Review: docs: fix render function/helper API documentation

Overall this is a high-quality, well-researched documentation PR. I verified all the behavioral claims (parameter-count detection, prerender forcing, async/ExecJS behavior, error-key detection, clientProps merge, renderer-function error, registerServerComponent signatures) against the source code — they are all accurate.

One inaccuracy found

Compatibility matrix footnote (render-functions.md, line 255) — see inline comment.

The note claims ❌ combinations "silently produce incorrect output," giving react_component + hash → "JSON-stringifies the object" and react_component_hash + plain component → "returns empty/wrong values." The actual behavior in both cases is a hard raise ReactOnRails::Error, not a silent failure. The note should say these combinations raise at runtime so readers know they'll get a clear error, not mysterious wrong output.

Everything else looks correct

• Parameter-count detection (0-1 / 2+ / 3) matches isRenderFunction.ts and ComponentRegistry.ts
• react_component_hash forcing prerender: true confirmed at helper.rb:151
• stream_react_component forcing prerender: true and dropping immediate_hydration with a warning confirmed in the Pro helper
• Async + ExecJS returning '{}' confirmed at serverRenderReactComponent.ts:71-76
• error key in isServerRenderHash confirmed at isServerRenderResult.ts:12
• registerServerComponent client signature (...componentNames: string[]) confirmed in client.tsx:51
• clientProps merge with symbol/string key coexistence confirmed in helper.rb:680-705
• Renderer functions throwing during server render confirmed in serverRenderUtils.ts:32-34

The create-without-ssr.md fix for registerServerComponent('ReactServerComponentPage') (removing the stale object argument) is correct per the current client bundle signature.

Review feedback addressed (2bef3c5)

I (Claude Code) addressed 2 remaining review comments, both verified against source:

1. Promise streaming matrix entry (render-functions.md:252) — Changed stream_react_component + Promise from ❌ to ✅. Verified in streamingUtils.ts:234-245: the streaming code explicitly handles Promises that resolve to React elements (rejects hash shapes). Test suite confirms with asyncRenderFunction cases.

2. ❌ footnote accuracy (render-functions.md:255) — The footnote incorrectly claimed ❌ means "silently produces incorrect output." Verified in helper.rb:104-110 and helper.rb:170-177: both mismatched combinations raise ReactOnRails::Error with descriptive messages. Updated footnote to reflect the actual error-raising behavior.

Review: docs: fix render function/helper API documentation

Overall this is a high-quality documentation PR that fills genuine gaps. I verified all the core technical claims against the source code — component detection logic, prerender forcing, ExecJS async behavior, clientProps merge, server render hash detection, and registerServerComponent signatures all check out. The compatibility matrix is accurate, and the legacy deprecation framing for redirectLocation/routeError is correct and helpful.

A couple of issues worth addressing before merge (see inline comments):

1. Compatibility matrix footnote overstates the error type. The note says "❌ means the combination raises a ReactOnRails::Error at runtime" — but this is only accurate for the Ruby-side mismatches (react_component + hash, react_component_hash + string). For the renderer-function rows (where the error originates in JS from validateComponent) and the stream_react_component rows (Pro Node renderer errors), the propagated exception would be ReactOnRails::PrerenderError (if raise_on_prerender_error is enabled) or an error comment embedded in the HTML — not ReactOnRails::Error.

2. react_component_hash also warns about immediate_hydration (verified at helper.rb:146-149) but the updated view-helpers-api.md docs for react_component_hash don't mention it. The PR adds this note only for stream_react_component.

Review feedback addressed (489d433)

All 4 unresolved review threads have been addressed and resolved:

1. error key behavior (render-functions.md:166) — Corrected: error is only used for server-render-hash detection, not as an exception descriptor. Only routeError sets the error flag.
2. ❌ matrix footnote (render-functions.md:255) — Rewrote to distinguish Ruby-side ReactOnRails::Error, JS-side ReactOnRails::PrerenderError, and embedded error HTML output.
3. immediate_hydration deprecation (view-helpers-api.md:60) — Added point 5 documenting that immediate_hydration is no longer supported for react_component_hash.

Review

Verified all major behavioral claims against source code. The changes are well-researched and address real documentation gaps. A few issues to address before merging:

Must Fix

javascript-api.md lines 29–33 — parameter detection description is inaccurate (see inline comment)

The description implies "2 params → Render-Function" and "3 params → Renderer function" are mutually exclusive categories. They aren't:

• The detection code uses component.length >= 2 (not exactly 2), so 4+-param functions are also render functions.
• Renderer functions are a subset of render functions (isRenderer = renderFunction && component.length === 3), not a separate category.

This section will confuse anyone trying to understand why their 4-parameter function is or isn't detected correctly.

Suggestions

Async vs sync hash structure inconsistency — The sync return-type-4 example wraps the hash in renderedHtml: { componentHtml, ... }, but the async return-type-6 example returns a flat { componentHtml, ... }. The compatibility matrix note ("must resolve to hash with componentHtml") implies the flat structure is correct for the async Pro Node renderer path, but the asymmetry is unexplained. A brief note would prevent confusion.

Error message strings — The compatibility matrix footnote paraphrases two runtime error messages slightly. Worth tightening them to the verbatim strings so readers can grep for them when debugging (see inline comment on line 255 of render-functions.md).

Verified Accurate

The following claims were verified against source code and are correct:

Overall this is a solid improvement to some of the most confusing parts of the API documentation.