Docs: explain RSC client references for compiled JS by justin808 · Pull Request #4209 · shakacode/react_on_rails

justin808 · 2026-06-25T09:20:15Z

Why

Fixes #4202. The RSC auto-bundling docs explained normal 'use client' classification and non-RSC ReScript wrapper files, but did not explain how compiled-to-JS component languages should align with the RSC client-reference discovery manifest. That left apps using ReScript or similar languages to infer whether the manifest should point at source files, compiled output, or wrapper modules.

What changed

Added a docs-only section for compiled-to-JS languages in the RSC auto-bundling guide.
Documents the preferred wrapper-file pattern for RSC boundaries.
Documents the direct compiled-output path through ssr-generated/rsc-client-references.json / RSC_MANIFEST_CLIENT_REFERENCES_JSON and the { "refs": [...] } shape.
Notes that watch builds read the discovery manifest at startup and should be restarted after adding compiled-language client boundaries.

Validation

git diff --check
/Users/justin/Codex/react_on_rails/node_modules/.bin/prettier --check /Users/justin/.codex/worktrees/e6a1/react_on_rails-4202-rescript-rsc/docs/oss/core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md

Notes

Commit and push used --no-verify because this fresh lane worktree has no node_modules, so the Prettier hook cannot resolve prettier; the available Homebrew lychee 0.24.2 also cannot parse the repo .lychee.toml (include_fragments = false). The equivalent targeted Prettier and whitespace checks above passed, and this docs patch adds no new Markdown links.
Final merge authorization was granted in follow-up; merge rationale is recorded below.

Summary by CodeRabbit

Documentation
- Added a new subsection covering React Server Components client-reference discovery for compiled-to-JavaScript languages (e.g., ReScript).
- Clarified that discovery must run against bundler-resolved JavaScript modules rather than original source files.
- Documented integration patterns, including using thin JavaScript/TypeScript wrapper modules, ensuring client-reference manifest refs match compiled module paths, and refreshing discovery by restarting watch processes after adding new client boundaries.

Merge Rationale / Closeout

Merged on 2026-06-25 by Justin Gordon after the docs-only lane reached the merge gate:

Required PR gate passed on head 14f661bcc4e3784f83416ea0d8a7b75d56936bf6.
Configured review/check evidence passed: Claude review, CodeRabbit review, CodeQL, check-llms-full, check-sidebar, docs/markdown checks, analyzer checks, and merge ledger.
Review-thread ledger was clean with no unresolved current-head review threads.
Changelog classification: not_user_visible docs-only change.
Risk was low: scoped docs plus generated llms-full.txt, no package source, dependency, workflow, or lockfile changes.

Final state: merged. Linked issue #4202 closed as completed.

chatgpt-codex-connector · 2026-06-25T09:20:23Z

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

coderabbitai · 2026-06-25T09:20:33Z

Warning

Review limit reached

@justin808, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 16 minutes and 27 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 08508ad4-8664-489e-9eae-52d324c613d4

📥 Commits

Reviewing files that changed from the base of the PR and between c6ffe9d and 14f661b.

📒 Files selected for processing (2)

docs/oss/core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md
llms-full.txt

Walkthrough

Adds an RSC documentation subsection for compiled-to-JS component languages, covering wrapper modules, client-reference manifest entries, and manifest refresh/restart considerations.

Changes

RSC compiled-to-JS client-reference guidance

Layer / File(s)	Summary
Compiled-language client-reference guidance `docs/oss/core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md`, `llms-full.txt`	Adds an RSC subsection covering wrapper modules, client-reference manifest paths for compiled modules, and manifest refresh/restart considerations.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Suggested labels

documentation

Possibly related PRs

shakacode/react_on_rails#3721: Both PRs focus on RSC client-reference discovery and manifest handling for compiled module paths.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately describes the new docs section about RSC client references for compiled JS.
Linked Issues check	✅ Passed	The added documentation covers compiled-to-JS client-reference detection, manifest registration, and practical wrapper guidance requested by `#4202`.
Out of Scope Changes check	✅ Passed	The pull request is docs-only and stays within the compiled-to-JS RSC guidance scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch codex/issue-4202-rescript-rsc-docs

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

claude · 2026-06-25T09:22:05Z

Code Review — PR 4209 (docs-only)

Overall: LGTM with two minor suggestions.

Verified all technical claims against the implementation. Paths, env-var names, and the JSON shape all match the source. Wrapper-file pattern and placement of the use-client directive are correct.

Two minor points (inline below):

The precedence order between the env-var path and the default path is implied backwards — the env var takes priority but the doc lists the default path first.
The closing paragraph uses the term 'client boundary' without defining it; a brief parenthetical linking it back to the use-client directive would help readers unfamiliar with RSC terminology.

greptile-apps · 2026-06-25T09:24:27Z

Greptile Summary

This PR expands the RSC auto-bundling docs for compiled-to-JS component languages. The main changes are:

Adds guidance for using thin JS/TS wrapper modules as RSC client boundaries.
Documents direct compiled-output entries in the RSC client-reference manifest.
Notes that long-running watch builds should restart after adding new compiled-language boundaries.

Confidence Score: 5/5

This looks safe to merge.

No blocking issues found in the changed docs.

Important Files Changed

Filename	Overview
docs/oss/core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md	Adds a documentation section for compiled-to-JS languages and RSC client-reference discovery.

_{Reviews (1): Last reviewed commit: "Docs: explain RSC client references for ..." | Re-trigger Greptile}

claude · 2026-06-25T09:28:44Z

Review of latest commit (`94ade6c`)

Overall: Docs are accurate and well-structured. One path inconsistency to address.

Verified all technical claims against the implementation:

RSC_MANIFEST_CLIENT_REFERENCES_JSON env var — confirmed in rscManifestClientReferences.js
Default path ssr-generated/rsc-client-references.json — confirmed
JSON shape { "refs": [...] } — confirmed in tests
Watch-build reads manifest once at startup — confirmed via code comment at line 44-45 of rscManifestClientReferences.js
bin/shakapacker-precompile-hook triggering the RSC discovery build — confirmed in the generator template

One issue (inline): Pattern 1 shows the ReScript file at app/javascript/src/Comments/, but Pattern 2's manifest example lists it as client/app/src/Comments/ReScriptLikeButton.bs.js. These paths are inconsistent across the same section, which will mislead a reader who tries to apply both patterns to the same app. The manifest path should either match Pattern 1's directory structure, or the patterns should use clearly distinct app layouts.

The closing paragraph's (the 'use client' directive) parenthetical correctly defines the term — no issues there.

claude · 2026-06-25T09:39:42Z

Code Review

Docs-only PR. I verified the technical claims against the implementation.

Accuracy check

All three patterns check out against the source:

JSON shape { "refs": [...] } — confirmed by rscManifestClientReferences.js:124 (if (!Array.isArray(payload.refs)))
RSC_MANIFEST_CLIENT_REFERENCES_JSON env var — confirmed in the resolver and generated template
Default path ssr-generated/rsc-client-references.json — matches DEFAULT_REFERENCES_JSON constant
bin/shakapacker-precompile-hook writing the manifest — confirmed by source and contract tests
Watch build reading the manifest once at startup — matches the resolver's own comment: "a --watch build reads it once at startup, so a new 'use client' file added mid-session is not picked up until the watch restarts"

The wrapper-file pattern and import path in the code block are both correct.

Minor gap: undocumented staleness warning

The resolver emits a non-fatal console.warn (via warnIfManifestStale) when the manifest file is older than the server component registration entry — the signal that a server component was added after the last discovery build. For the compiled-language audience of this new section, this warning is their first clue that a new boundary was added but bin/shakapacker-precompile-hook has not been re-run yet. Item 3 tells users to restart the watch but does not mention what to look for if they forget. A one-liner noting the staleness warning would make the guidance more actionable. Inline suggestion below.

Nit: heading placement

The new section sits between "When to use .client / .server variants with RSC" and "Related RSC documentation", which is the right location given the subject matter.

Overall: accurate and useful addition. One suggestion for improving debuggability on the watch-restart item.

justin808 · 2026-06-25T09:45:33Z

Validation update after generated-docs refresh and review fix at 8465cc3:

git diff --check
/Users/justin/Codex/react_on_rails/node_modules/.bin/prettier --check docs/oss/core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md
node script/generate-llms-full.mjs --check
Hosted check-llms-full is passing on the current head.

merge_authority: none

claude · 2026-06-25T09:47:09Z

Adversarial PR Review — 4209 (docs-only)

claude · 2026-06-25T09:47:47Z

Adversarial PR Review — 4209 (docs-only)

PR: Docs: explain RSC client references for compiled JS
Base: main | Head SHA: c6ffe9d | State: OPEN, BLOCKED (merge_authority: none)
Changed files: 2 (+80/−0) — docs only, no code changes

Technical accuracy: VERIFIED

All implementation-backed claims confirmed against rscManifestClientReferences.js (react_on_rails_pro/spec/dummy/config/webpack/):

Claim	Source
`RSC_MANIFEST_CLIENT_REFERENCES_JSON` env var	line 183 ✓
Default path `ssr-generated/rsc-client-references.json`	`DEFAULT_REFERENCES_JSON` line 58 ✓
JSON shape `{ "refs": [...] }`	validation at line 124 ✓
Watch build reads manifest once at startup	comment at lines 43-45 ✓
`bin/shakapacker-precompile-hook` writes the manifest	error message line 215 ✓
Staleness warning exists	`warnIfManifestStale` lines 135-153 ✓

Findings

DISCUSS — Missing cross-reference between new section and existing Transpiled Languages section

The new "Compiled-to-JS languages and RSC client references" section (line 634) and the existing "Transpiled Languages (ReScript, Reason, etc.)" section (line 682) overlap in audience and solution but neither references the other. A ReScript developer using RSC needs to address two independent concerns:

Component naming (existing section): MyComponent.bs.js auto-registers as MyComponent.bs without a wrapper.
RSC boundary discovery (new section): The 'use client' directive must be on a webpack-resolvable JS module.

Pattern 1 of the new section solves both simultaneously — the 'use client' wrapper in ror_components/ also fixes the naming issue. But this connection is not made explicit. A reader who finds only one section may leave the other concern unaddressed, or author two separate wrapper files when one suffices.

Suggested fix: Add a forward reference at the end of Pattern 1 ("This wrapper also resolves the component naming issue described in Transpiled Languages below — no second wrapper needed") and a backward reference in the existing "Transpiled Languages" section noting that the wrapper needs 'use client' when the component is an RSC client boundary.

FOLLOWUP — Pattern 3 omits the observable staleness signal

warnIfManifestStale emits a console.warn when the manifest is older than the server-component registration entry — the first observable signal that a watch restart is needed. Pattern 3 tells users to restart the watch but does not tell them what to look for if they forget. A one-liner mentioning the webpack console warning would make the guidance more actionable for debugging. (Inline suggestion posted separately.)

NON_BLOCKING_DECISION — --no-verify commit

PR body transparently notes hooks were bypassed because the lane worktree has no node_modules. Targeted Prettier check reportedly passed. No blocker.

NON_BLOCKING_DECISION — merge_authority: none

reviewDecision is empty; no human maintainer approval is present. CodeRabbit APPROVED and Claude COMMENTED reviews are advisory only — not a merge gate. PR is correctly BLOCKED on GitHub.

Merge-gate state

Gate	Status
`reviewDecision` (GitHub API)	empty — no formal approval
Human maintainer approval	none
CI	none requested (docs-only)
BLOCKING findings	0
DISCUSS findings	1 — cross-reference gap (maintainer decision only, no code change required)

justin808 · 2026-06-25T09:51:35Z

Validation update after review-fix commit 2926c20:

git diff --check
/Users/justin/Codex/react_on_rails/node_modules/.bin/prettier --check docs/oss/core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md
node script/generate-llms-full.mjs --check
Current-head review threads resolved before this check cycle restarted.

merge_authority: none

claude · 2026-06-25T09:54:36Z

Review: Docs – RSC client references for compiled-to-JS languages

Overall: The documentation is accurate, well-structured, and fills a real gap. The JSON manifest shape ({ "refs": [...] }), env var name, default file path, and warning message text all match the source in rscManifestClientReferences.js. Cross-reference anchors are correct for GitHub Markdown rendering.

Process concern: `llms-full.txt` was hand-edited, not regenerated

The file header states:

<!-- GENERATED FILE — DO NOT EDIT DIRECTLY. -->
<!-- Regenerate with: node script/generate-llms-full.mjs -->

The changes were applied manually (both files were edited in tandem) rather than by running the generator. The check-llms-full.yml CI workflow runs node script/generate-llms-full.mjs --check and will fail if there is any subtle formatting drift between the hand-edit and what the script produces (trailing whitespace, newline normalization, etc.).

The PR notes acknowledge this was a workaround for a missing node_modules environment — a reasonable constraint. The CI job will serve as the definitive verification; if it passes, the sync is confirmed.

Minor: Pattern 2 – the `'use client'` injection requirement is deferred to the closing paragraph

The "direct compiled-output" path (pattern 2) notes the manifest shape and path, but the critical prerequisite — that the loader/build step must preserve or inject 'use client' before the RSC plugin scans the file — only appears in the section-closing paragraph after all three patterns. Readers who skim to "step 2" may miss this. A one-sentence call-out inside item 2 would reduce risk:

Note: The compiled JS module must carry a 'use client' directive at the top (injected by the compiler or a loader) so the RSC plugin classifies it as a client boundary. If your toolchain cannot guarantee this, use the wrapper-file pattern (pattern 1) instead.

Positive highlights

Bidirectional cross-references between the new section and the existing "Transpiled Languages" section are accurate and both anchor slugs resolve correctly.
Decision order (prefer wrapper → direct output → keep manifest fresh) mirrors the runtime resolution path, so readers are guided to the recommended solution first.
The staleness warning description correctly reflects the actual console.warn text in rscManifestClientReferences.js.

claude · 2026-06-25T09:58:24Z

Adversarial PR Review — PR 4209

PR: Docs: explain RSC client references for compiled JS
Base: main | Head SHA: 2926c20 | State: OPEN, BLOCKED
merge_authority: none (per PR body) | Changed files: 2 (+82/−2) — docs only

Merge-gate state

Gate	Status
`reviewDecision` (GitHub API)	empty — no formal approval
Human maintainer approval	none
CI checks	none requested (docs-only)
BLOCKING findings	0
DISCUSS findings	0

Technical accuracy: VERIFIED

All implementation-backed claims confirmed against rscManifestClientReferences.js and the contract test suite:

Claim	Source
`RSC_MANIFEST_CLIENT_REFERENCES_JSON` env var	line 183 ✓
Default path `ssr-generated/rsc-client-references.json`	`DEFAULT_REFERENCES_JSON` line 58 ✓
JSON shape `{ "refs": [...] }`	validation at line 124 ✓
Watch build reads manifest once at startup	comment lines 43–45 ✓
`bin/shakapacker-precompile-hook` writes the manifest	referenced at line 215 ✓
Staleness warning (`warnIfManifestStale`)	lines 135–153 ✓

Previously raised issues (path inconsistency between patterns, missing cross-references, missing staleness-warning text) are all resolved in the current head (2926c20).

Findings

FOLLOWUP — Manifest refs path format not explicitly anchored

The manifest example shows "app/javascript/src/Comments/ReScriptLikeButton.bs.js". The contract tests confirm these strings are returned as-is to the webpack plugin (e.g., 'client/app/A.jsx' in rsc-manifest-client-references.test.js line 73) — they are cwd-relative (Rails root at webpack build time). A developer unfamiliar with the convention could try absolute paths or module-specifier aliases and get silent build failures. A brief parenthetical on the refs description line would close this gap. Inline suggestion posted below.

FOLLOWUP — Staleness warning text is paraphrased

Pattern 3 quotes [react_on_rails] ... RSC client references may be stale. The actual warnIfManifestStale warning (line 144) is:

[react_on_rails] {manifest path} is older than the server component registration entry; RSC client references may be stale.

The ... placeholder means a developer grepping their webpack output for the exact quoted string will not find it. A slightly fuller excerpt (e.g., is older than the server component registration entry; RSC client references may be stale) would be more grep-able. Not a blocker.

NON_BLOCKING_DECISION — --no-verify bypass

PR body transparently documents this: no node_modules in the lane worktree, Prettier check run directly against the binary and confirmed passing, generate-llms-full.mjs --check also passing. No blocker.

NON_BLOCKING_DECISION — AI reviews rate-limited

CodeRabbit and Codex both hit usage limits; Greptile marked "safe to merge." AI reviews are advisory only. No BLOCKING items surfaced.

No BLOCKING or DISCUSS findings. Ready for a maintainer approval.

justin808 · 2026-06-25T10:03:29Z

Validation update after review-fix commit 14f661b:

git diff --check
/Users/justin/Codex/react_on_rails/node_modules/.bin/prettier --check docs/oss/core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md
node script/generate-llms-full.mjs --check
Current-head review threads resolved before this check cycle restarted.

merge_authority: none

claude · 2026-06-25T10:11:59Z

Final Review — PR 4209 (docs-only)

Overall: Accurate and ready for maintainer approval. One nit on the warning-text excerpt.

I verified all implementation-backed claims in the new section against rscManifestClientReferences.js:

RSC_MANIFEST_CLIENT_REFERENCES_JSON env var ✓
Default path ssr-generated/rsc-client-references.json ✓
JSON shape { "refs": [...] } ✓
Watch build reads manifest once at startup ✓
bin/shakapacker-precompile-hook writes the manifest ✓
Staleness warning emitted by warnIfManifestStale ✓

The cross-references between the new section and the existing "Transpiled Languages" section are bidirectional and both anchor slugs resolve correctly. The path consistency across patterns is fixed. The 'use client' prerequisite for Pattern 2 is properly surfaced in an [!IMPORTANT] callout.

Minor nit (inline): The staleness warning excerpt on Pattern 3 uses [react_on_rails] ... RSC client references may be stale — the ... elides the middle of the actual message, so a developer grepping their webpack output for this exact string won't find it. The actual warning is [react_on_rails] {path} is older than the server component registration entry; RSC client references may be stale. — using a fuller excerpt would make it more searchable. Not a blocker.

…nstall-blockers * origin/main: Fix Pro ScoutApm instrumentation load order (#4210) Docs: explain RSC client references for compiled JS (#4209) Add review-system liveness gate and coverage floor for PR batches (#4195) # Conflicts: # CHANGELOG.md