Docs: record RSC Rspack client refs investigation

[ihabadham]

Summary

• Adds an internal investigation record for RORP RSC + Rspack client-reference manifest generation.
• Captures the path from the initial RSCRspackPlugin work through the lazyCompilation fix.
• Records why addInclude-only client inclusion is not yet a final architecture and what remains open for Rspack/Shakapacker follow-up.

Rationale

Fresh RSC + Rspack apps now work in normal bin/dev, but the longer-term client-reference inclusion design is still unresolved. This document preserves the investigation context so future work starts from the known constraints instead of rediscovering them.

Related: #3488, #3553, #4200, #4227, #4243.

Testing

• git diff --check
• pnpm exec prettier --check internal/analysis/rsc-rspack-client-reference-inclusion-investigation-record-2026-06-27.md
• pre-commit hook
• pre-push hook

Changelog

• Not needed: internal analysis documentation only.

Review updates

• Addressed reviewed wording/accuracy notes for Hichee evidence framing, addInclude server-entry constraints, server parity qualification, test provenance caveat, and reference completeness.

[coderabbitai]

Walkthrough

Adds a new internal decision record documenting the history of React Server Components + Rspack client-reference manifest generation, the lazyCompilation failure mode and shipped mitigation, addInclude implementation outcomes, Rspack public API blockers, current decisions, open questions, and upstream references.

Changes

RSC Rspack Client-Reference Inclusion Decision Record

Layer / File(s)	Summary
Header, status, and RSC client manifest model internal/analysis/rsc-rspack-client-reference-inclusion-decision-record-2026-06-27.md	Document header states internal purpose and current shipped status; manifest model section defines the client-reference JSON shape and how chunks: [] vs populated chunks affect Flight's async splitting.
Mechanism timeline and lazyCompilation failure internal/analysis/rsc-rspack-client-reference-inclusion-decision-record-2026-06-27.md	Traces the full mechanism evolution from the initial addInclude-based RSCRspackPlugin through injection-loader stabilization and graph-derived refs, culminating in the lazyCompilation lazy-proxy failure mode and the shipped mitigation of disabling top-level lazyCompilation.
addInclude variants, API blocker, and comparison table internal/analysis/rsc-rspack-client-reference-inclusion-decision-record-2026-06-27.md	Documents three compilation.addInclude implementation test shapes and their chunk/manifest outcomes, records the Rspack JavaScript API blocker for async dependency block mutation, notes the native Rspack RSC direction, and provides a mechanism comparison table with the lazy-trigger 404 topology.
Decisions, open questions, and references internal/analysis/rsc-rspack-client-reference-inclusion-decision-record-2026-06-27.md	Lists the explicit decisions, open questions with next actions, and structured upstream reference links.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• RFC: Derive RSC client references from the actual RSC graph #3553: The record covers RSC client-reference discovery and graph-derived refs, which matches the issue’s objective.

Suggested labels

documentation, P3

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
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.
Title check	✅ Passed	The title clearly matches the change: adding documentation for the RSC Rspack client-reference investigation.

✨ 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 ihabadham/docs/rsc-rspack-client-reference-inclusion-record

---

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

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[greptile-apps]

Greptile Summary

This PR adds an internal decision record for RSC and Rspack client-reference handling. The main changes are:

• A new maintainer-facing history of the Rspack client-manifest work.
• Notes on the lazyCompilation failure and current generated-config fix.
• Comparison of addInclude, injection-loader, and native Rspack RSC paths.
• Follow-up questions for Rspack, Shakapacker, and future RORP architecture work.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed documentation.
• The change does not modify runtime code, build configuration, public APIs, or security-sensitive behavior.

Important Files Changed

Filename	Overview
internal/analysis/rsc-rspack-client-reference-inclusion-decision-record-2026-06-27.md	Adds a new internal decision record for RSC + Rspack client-reference manifest generation and related follow-up work.

_{Reviews (1): Last reviewed commit: "docs: record RSC Rspack client refs deci..." | Re-trigger Greptile}

[claude]

Review: RSC Rspack client-reference inclusion decision record

This PR adds a well-structured internal decision record capturing the investigative history from the first RSCRspackPlugin through the lazyCompilation fix (#4227), along with an evaluation of three addInclude implementation shapes and five architectural decisions. The document will be a valuable reference for future RSC + Rspack work.

Eight findings below — five are ready to fix in this PR, three are minor cleanup. Inline comments on specific lines follow.

Findings

#	Line	Severity	Summary
1	336	Medium	hichee#9508 appears in a section labeled "Public evidence" but is a private repo with no hyperlink — move it to a separate internal note
2	444	Medium	Open question #5 ("link this record from #3488") has no PR checklist item; it will silently go unactioned after merge
3	395	Medium	Decision 4 says "use addInclude into existing server entry" but omits the critical constraint: a new entry name causes Rspack node-target crashes (documented at line 89 in the timeline)
4	350	Low	Mechanism table rates addInclude-into-existing-entry as "Better" for server manifest parity, but Test 2 was a client-bundle test only — no server-side test is documented
5	197	Low	The three addInclude tests have no provenance (no branch, commit, or react_on_rails_rsc version) — results can't be reproduced or invalidated against a future state
6	301	Low	rspack#9661 is cited in the body but absent from the Reference links section (all other five Rspack upstream references appear there)
7	467	Low	react_on_rails_rsc#72 appears only in Reference links, never in the body — no context for why it is listed
8	311	Low	The Rspack native RSC section links to crates/rspack_plugin_rsc without noting it is a Rust-internal crate, not a JS plugin API — a future maintainer could mistake it for a configurable npm package

[coderabbitai]

🧹 Nitpick comments (1)

internal/analysis/rsc-rspack-client-reference-inclusion-decision-record-2026-06-27.md (1)

395-399: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Clarify the fragment "mark exports used in unknown way."

This line reads as an incomplete verb phrase. Consider expanding to "mark exports as used in unknown way" or, if this references a specific Rspack/webpack API (e.g., usedExports: "unknown"), use the exact option name for precision.

🤖 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
`@internal/analysis/rsc-rspack-client-reference-inclusion-decision-record-2026-06-27.md`
around lines 395 - 399, The phrase “mark exports used in unknown way” is
incomplete and should be clarified in the decision record entry under the server
bundle section. Update the wording to either use the exact Rspack/webpack API
term if applicable (for example, the relevant `usedExports` setting) or rewrite
it as a complete verb phrase such as “mark exports as used in an unknown way” so
the intent is precise and readable.

🤖 Prompt for all review comments with AI agents

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

Nitpick comments:
In
`@internal/analysis/rsc-rspack-client-reference-inclusion-decision-record-2026-06-27.md`:
- Around line 395-399: The phrase “mark exports used in unknown way” is
incomplete and should be clarified in the decision record entry under the server
bundle section. Update the wording to either use the exact Rspack/webpack API
term if applicable (for example, the relevant `usedExports` setting) or rewrite
it as a complete verb phrase such as “mark exports as used in an unknown way” so
the intent is precise and readable.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a22e1e25-7769-4540-ba37-843d1bc2e7cc

📥 Commits

Reviewing files that changed from the base of the PR and between ca0b30c and 7f32d28.

📒 Files selected for processing (1)

• internal/analysis/rsc-rspack-client-reference-inclusion-decision-record-2026-06-27.md

[ihabadham]

Address-review summary

Scan scope: full PR history; no prior summary.

Mattered

• Declined Rspack RSC: path to production-ready — pivot to native RSCRspackPlugin #3488 cross-link/checklist request for this PR by user choice; no issue or PR cross-link/comment was added.
• Addressed server addInclude existing-entry constraint in the recommended-direction section.

Optional

• Reframed private Hichee context outside public-evidence wording.
• Qualified addInclude owner-entry server parity as needing retest.
• Added June 2026 local-test caveat for addInclude implementation tests.
• Added missing web-infra-dev/rspack#9661 reference.
• Cited react_on_rails_rsc#72 in the follow-up section.
• Clarified rspack_plugin_rsc is Rust-internal, not a public JS/npm plugin API.

Skipped

• CodeRabbit and Greptile summaries had no actionable comments.

Follow-up issue: None.

Next default scan starts after this comment. Say check all reviews to rescan the full PR.

[claude]

Stale status: #4243 was already resolved by PR #4249.

PR #4249 is already merged and appears in CHANGELOG.md (lines 51–61). It changed the doctor from a false "still enabled" assertion to a softer "could not confirm" warning, covering all the equivalent config variants listed later in this section.

The bullet should either be removed from "Current status" or updated to note the fix shipped:

Suggested change

	- [react_on_rails#4243](https://github.com/shakacode/react_on_rails/issues/4243) tracks a smaller doctor false-warning gap for equivalent custom lazy-compilation configs.
	- ~~[react_on_rails#4243](https://github.com/shakacode/react_on_rails/issues/4243)~~ Doctor false-warning gap for equivalent custom `lazyCompilation` configs was fixed in [react_on_rails#4249](https://github.com/shakacode/react_on_rails/pull/4249): doctor now emits "could not confirm" rather than a false "still enabled" assertion.

[claude]

Wrong issue number. PR #4227 says "Fixes #4226" — not #4200. Issue #4200 was the install/doctor diagnostics gap fixed by PR #4213. The section title and opening sentence should reference #4226 as the tracking issue for the bin/dev failure.

Suggested change

	### 5. `react_on_rails#4226` and `react_on_rails#4227`: normal `bin/dev` failure

[claude]

Test 1 is missing a setup description. Tests 2 and 3 each open with a sentence describing the approach before listing results. Test 1 jumps straight to "Result:" with no config excerpt, no entry name used, and no indication of which file was added via addInclude.

The section header at line 197 explicitly cautions to "rerun them against current react_on_rails_rsc before using any result as design proof" — but Test 1 cannot be reproduced without knowing what was actually tested. Even a short paragraph matching the style of Test 2 ("This approach attached discovered refs to…") would make this reproducible.

[claude]

Private reference used as corroborating evidence without an accessibility note. shakacode/hichee#9508 is cited to support the claim about Hichee's Rspack migration disabling lazyCompilation. Readers without access to that repo will get a 404 (or a permissions error). Since this doc may be linked from public issues (#3488 per the open questions section), worth labelling:

Suggested change

	Internal context: Hichee's Rspack migration also disabled top-level `lazyCompilation` in its Rails/Rspack dev-server wiring; see private PR `shakacode/hichee#9508` for the RSC + Rspack migration context.
	Internal context: Hichee's Rspack migration also disabled top-level `lazyCompilation` in its Rails/Rspack dev-server wiring (private repo — shakacode/hichee, not publicly accessible); see private PR `shakacode/hichee#9508` for the RSC + Rspack migration context.

[claude]

Review: RSC Rspack client-reference inclusion decision record

Well-written and thorough internal decision record. The mechanism comparison table, the three addInclude test cases, and the Rspack public-API gap section are particularly useful for orienting future work. All major technical claims were independently verified as accurate (the chunks: [] description, the addInclude entry-chunk semantics, the Rspack PR #9661 read-side-only API additions, and the injection-loader architecture).

Two confirmed factual errors and two structural gaps worth fixing before merge:

Confirmed errors

Line 21 — Issue #4243 is already resolved
The "Current status" bullet says #4243 "tracks a smaller doctor false-warning gap" as if still open. PR #4249 (already in CHANGELOG.md lines 51-61) shipped the fix: the doctor now emits a "could not confirm" warning instead of a false "still enabled" assertion. The section 6 description of the pattern recognition also reads as a currently-open bug.

Line 141 — Wrong issue number for the bin/dev failure
The section heading and opening sentence say #4200 described the fresh-app bin/dev failure, but PR #4227 explicitly says "Fixes #4226". Issue #4200 was the install/doctor diagnostics gap fixed by #4213. Future readers tracking down the bin/dev failure root cause will land on the wrong issue.

Structural gaps

Line 199 — Test 1 missing setup description
Tests 2 and 3 each describe the approach before listing results. Test 1 jumps straight to "Result:" with no config excerpt or entry name. The section header explicitly says to rerun these tests against current react_on_rails_rsc before using any result as design proof, but Test 1 cannot be reproduced without knowing what was tested.

Line 337 — Private reference lacks accessibility label
shakacode/hichee#9508 is used as supporting evidence but will 404 for anyone without hichee access. Since the open-questions section plans to link this doc from public issue #3488, adding an "internal only, not publicly accessible" note would prevent reader confusion.