Add common mistakes sections to RSC migration guides

[justin808]

Summary

Strengthens the 6-part RSC migration guide series with practical "Common Mistakes" sections and diagnostic tools based on real-world migration patterns:

• migrating-to-rsc.md: New "Migration Readiness Checklist" with infrastructure prerequisites and a table of the 7 most common pre-migration mistakes (missing routes, wrong versions, bundle confusion, etc.)
• rsc-preparing-app.md: New "Common Setup Mistakes" section (5 mistakes) covering wrong react-on-rails-rsc version, missing dev watchers, .server.jsx confusion, webpack mutation safety, and missing react-server condition
• rsc-context-and-state.md: New "Common Mistakes" section (4 mistakes) covering provider placement too high, I18n translation bloat, Redux in Server Components, and QueryClient re-creation
• rsc-data-fetching.md: New "Common Mistakes" section (5 mistakes) covering sequential controller queries, Server Actions misuse, missing CSRF tokens, missing streaming setup, and ActiveRecord over-serialization
• rsc-third-party-libs.md: New "Common Mistakes" section (4 mistakes) covering barrel file 'use client', library compatibility auditing, import granularity, and CSS-in-JS migration planning
• rsc-troubleshooting.md: New "Diagnostic Quick-Reference" table mapping 10 common symptoms to their causes and relevant guide sections

All sections include concrete before/after code examples showing the wrong approach and the fix.

Closes #2769

Test plan

• Verify all internal cross-references between guides resolve correctly
• Verify markdown renders properly on GitHub
• Review code examples for accuracy against current React on Rails Pro API

🤖 Generated with Claude Code

---

Note

Low Risk
Low risk documentation-only change; main risk is incorrect guidance or broken internal anchors/links in the RSC migration docs.

Overview
Strengthens the OSS RSC migration guide series by adding migration readiness/setup checklists and multiple "Common Mistakes" sections across the component audit, setup, context/state, data fetching, and third-party library guides.

Adds a diagnostic quick-reference table to rsc-troubleshooting.md that maps common symptoms (build/runtime/perf issues) to likely causes and the relevant troubleshooting sections, with concrete before/after examples throughout.

^{Written by Cursor Bugbot for commit 896a788. This will update automatically on new commits. Configure here.}

Summary by CodeRabbit

• Documentation
  • Expanded RSC migration guides with new "Common Mistakes" sections covering setup, data fetching, state/context, and third-party library pitfalls.
  • Added a "Migration Readiness Checklist" with infrastructure and build verification steps to confirm RSC readiness.
  • Added a "Diagnostic Quick-Reference" mapping symptoms to troubleshooting sections for faster issue resolution.

[coderabbitai]

Walkthrough

Updated six RSC migration guide documents by adding "Common Mistakes," "Common Setup Mistakes," "Migration Readiness Checklist," and "Diagnostic Quick-Reference" sections that document real-world client migration pitfalls across infrastructure setup, component patterns, state management, data fetching, and third-party library integration.

Changes

Cohort / File(s)

Summary

RSC Migration Guides – Common Mistakes & Checklist docs/oss/migrating/migrating-to-rsc.md, docs/oss/migrating/rsc-context-and-state.md, docs/oss/migrating/rsc-data-fetching.md, docs/oss/migrating/rsc-preparing-app.md, docs/oss/migrating/rsc-third-party-libs.md, docs/oss/migrating/rsc-troubleshooting.md

Added Migration Readiness Checklist and Diagnostic Quick-Reference; inserted "Common Mistakes" guidance across guides covering: React/version requirements, NodeRenderer and RSC manifests, webpack/RSC bundle/watch process, mounting rsc_payload_route, Procfile.dev watcher, proper 'use client' placement and barrel-import pitfalls, Context/Redux and QueryClient patterns, server data-fetching anti-patterns (sequential AR queries, CSRF token omission, over-serialization), streaming/loading state guidance, and CSS-in-JS/third-party library compatibility notes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 With whiskers twitching, I hop through the logs,
Where clients once stumbled through RSC fogs—
Now checklists and warnings light up the migration way,
Common mistakes caught before they delay! ✨

🚥 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 'Add common mistakes sections to RSC migration guides' directly and accurately describes the primary change—adding new 'Common Mistakes' and diagnostic sections across six migration guide documents.
Linked Issues check	✅ Passed	The PR comprehensively addresses all coding objectives from #2769: documented top client mistakes across five migration guide sections, added 'Common Mistakes' callouts with before/after examples, created a diagnostic quick-reference, and categorized errors by migration phase.
Out of Scope Changes check	✅ Passed	All changes are scoped to documentation updates for RSC migration guides. No code changes, executable logic, or unrelated documentation modifications are present—all additions directly support the issue's objectives.
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 jg/2769-rsc-migration-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

• X
• Mastodon
• Reddit
• LinkedIn

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

[greptile-apps]

Greptile Summary

This PR strengthens the 6-part RSC migration guide series by adding practical "Common Mistakes" sections and a new diagnostic quick-reference table, all grounded in real-world migration patterns. The additions are generally high quality — the before/after code examples are concrete and actionable, all internal cross-references and anchor links were verified correct, and the new content is well-integrated with the existing guide structure.

Key changes:

• migrating-to-rsc.md: New "Migration Readiness Checklist" with 7 infrastructure items and a table of the 7 most common pre-migration mistakes
• rsc-preparing-app.md: New "Common Setup Mistakes" section (5 mistakes) inserted before the Verification Checklist
• rsc-context-and-state.md: New "Common Mistakes" section (4 mistakes) — contains one factual inaccuracy about RSC mechanics (see inline comment on Mistake 1)
• rsc-data-fetching.md: New "Common Mistakes" section (5 mistakes) — the "GOOD" code example for Mistake 2 is incomplete
• rsc-third-party-libs.md: New "Common Mistakes" section (4 mistakes) — the granular import claim may mislead readers unfamiliar with modern tree-shaking
• rsc-troubleshooting.md: New "Diagnostic Quick-Reference" table mapping 10 symptoms to causes and guide sections; all anchors verified

Concerns:

• The explanation for Mistake 1 in rsc-context-and-state.md states that passing children from a Server Component into a Client Component provider "forces every child to be a Client Component." This is factually incorrect per the RSC spec — children passed as props from a Server Component remain Server Components even when their parent is a Client Component. This is worth correcting before merge to avoid propagating a misunderstanding of RSC fundamentals.

Confidence Score: 3/5

• Safe to merge after fixing the RSC provider mechanics inaccuracy in rsc-context-and-state.md Mistake 1, which teaches an incorrect mental model
• The PR is high quality overall — accurate cross-references, practical examples, and well-structured additions. However, Mistake 1 in rsc-context-and-state.md contains a factual error about RSC fundamentals (claiming that children passed from a Server Component to a Client Component provider become Client Components, which contradicts the RSC spec). This kind of documentation error can propagate incorrect understanding of RSC architecture to developers following the guide. The two P2 comments are non-blocking. Score reflects one concrete, impactful inaccuracy that should be corrected before this is published.
• docs/oss/migrating/rsc-context-and-state.md (Mistake 1 explanation is factually incorrect about RSC mechanics)

Important Files Changed

Filename	Overview
docs/oss/migrating/rsc-context-and-state.md	Adds "Common Mistakes" section (4 mistakes); Mistake 1 contains a factual inaccuracy about RSC provider mechanics — children passed from a Server Component to a Client Component provider are NOT converted to Client Components in RSC
docs/oss/migrating/rsc-data-fetching.md	Adds 5 common mistakes covering sequential queries, Server Actions misuse, CSRF tokens, streaming setup, and over-serialization; the GOOD example for Mistake 2 (Server Actions) is incomplete — createUser is defined but not exported or wired to a component
docs/oss/migrating/rsc-third-party-libs.md	Adds 4 common mistakes for third-party library usage; the granular import example overstates the cost for modern tree-shaking bundlers without qualifying it as an RSC-specific concern
docs/oss/migrating/rsc-troubleshooting.md	Adds a "Diagnostic Quick-Reference" table at the top of the file; all 10 internal anchor links and cross-file links verified correct
docs/oss/migrating/migrating-to-rsc.md	Adds a "Migration Readiness Checklist" with infrastructure prerequisites and a 7-row common mistakes table; all cross-references to rsc-preparing-app.md anchors verified correct
docs/oss/migrating/rsc-preparing-app.md	Adds a "Common Setup Mistakes" section (5 mistakes) covering version, watcher, .server.jsx confusion, webpack mutation safety, and react-server condition; content is accurate and consistent with the step-by-step guide above it

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Developer hits RSC issue] --> B{Diagnostic Quick-Reference\nrsc-troubleshooting.md}

    B --> C[Build error: functions/classes\nacross boundary]
    B --> D[Build error: hooks in\nServer Component]
    B --> E[Unexpectedly large\nJS chunks]
    B --> F[Component stays\nClient Component]
    B --> G[Hydration mismatch\nwarnings]
    B --> H[Node renderer VM\nerrors]
    B --> I[SSR hangs/timeouts]
    B --> J[Rails boot version\nmismatch]
    B --> K[422 on form submit]
    B --> L[Blank page until\nall data loads]

    C --> M[Serialization Boundary Issues\nrsc-troubleshooting.md]
    D --> N[Error Message Catalog\nrsc-troubleshooting.md]
    E --> O[Chunk Contamination\nrsc-troubleshooting.md]
    F --> P[Accidental Client Components\nrsc-troubleshooting.md]
    G --> Q[Hydration Mismatches\nrsc-troubleshooting.md]
    H --> R[Node Renderer VM Context\nrsc-troubleshooting.md]
    I --> S[Stream Backpressure Deadlock\nrsc-troubleshooting.md]
    J --> T[Gem/npm Version Mismatch\nrsc-troubleshooting.md]
    K --> U[Mutations Guide\nrsc-data-fetching.md]
    L --> V[Performance Pitfalls\nrsc-troubleshooting.md]

    subgraph Pre-Migration Checklists
        W[Migration Readiness Checklist\nmigrating-to-rsc.md]
        X[Common Setup Mistakes\nrsc-preparing-app.md]
        Y[Common Mistakes: Context\nrsc-context-and-state.md]
        Z[Common Mistakes: Data Fetching\nrsc-data-fetching.md]
        AA[Common Mistakes: 3rd Party Libs\nrsc-third-party-libs.md]
    end

Loading

_{Reviews (1): Last reviewed commit: "Add common mistakes and diagnostic secti..." | Re-trigger Greptile}

[claude]

Overall a high-quality docs PR. Inline comments posted on two specific issues in the new Common Mistakes sections. Summary of all findings:

Needs fix (inline comments posted):

• rsc-data-fetching.md line 772: The Server Actions BAD example uses db.users.create() (Prisma/Drizzle syntax) which does not exist on the Node renderer. This misleads readers into thinking a JS ORM is available.
• rsc-context-and-state.md line 454: I18n.t('.') does not reliably return the entire translation tree -- it attempts to look up the literal key .. The intent of the warning is correct but the BAD example code should use an API that actually exhibits the described behavior.

Pre-existing content to consider improving (not part of this diff):

• rsc-data-fetching.md ChatWindow example: The WebSocket URL wss://api.example.com/... implies readers need a separate WebSocket server. ActionCable is the Rails-native alternative and worth mentioning.
• rsc-third-party-libs.md barrel file section: The direct import example lucide-react/dist/esm/icons/alert uses an internal path that has changed across library versions -- worth noting it is illustrative.

Verified correct in the new sections:

• The 'use client' on both .client.jsx and .server.jsx guidance is accurate and non-obvious
• useState(() => new QueryClient()) stability pattern is correct
• Thread-based parallel controller queries pattern is valid and practical
• react-on-rails-rsc 19.0.4+ version pin rationale is accurate
• Missing RSC bundle watcher in Procfile.dev is a real footgun -- good call including it
• All diagnostic table anchor links resolve to existing sections

[claude]

test comment

[claude]

Review: Add common mistakes sections to RSC migration guides

This is a valuable addition to the RSC migration series. The "Common Mistakes" sections are exactly the kind of practical knowledge that saves hours of debugging. The before/after code examples are clear, and the Diagnostic Quick-Reference table in the troubleshooting guide is particularly useful.

A few issues worth addressing (also posted as inline comments):

Bug: Procfile.dev snippet inconsistency. The checklist in migrating-to-rsc.md shows RSC_BUNDLE_ONLY=yes bin/shakapacker --watch without HMR=true, but the actual Procfile.dev examples in rsc-preparing-app.md (lines 338-340 and 558) consistently include HMR=true RSC_BUNDLE_ONLY=yes bin/shakapacker --watch. A user following only the checklist gets a different dev setup than someone following Step 4.

Misleading: Server Actions "may appear to work in development". rsc-data-fetching.md Mistake 2 says using 'use server' may appear to work in development but will fail in production. This implies it is a production-only problem. In reality, Server Actions are entirely unsupported in both environments since the Node renderer has no database connection or ORM access anywhere. Saying it "appears to work" may send users down a debugging path in dev when the real answer is simply that the feature is unsupported.

Ambiguous: Redux fix in Context and State Mistake 3. The fix says to use a Client Component provider wrapper that reads the store and passes data via children. A 'use client' component that reads from the Redux store cannot pass that store data to Server Component children — Server Components are rendered on the server before client components run. The children-as-props pattern works for providers (wrapping children in <Provider store={store}>) but not for components that read store state and forward it. The clearest options are: keep these components as Client Components, or pass the initial value from Rails as a prop.

[claude]

The '...' string literal is not valid JavaScript/webpack config and may confuse readers who copy it verbatim. Consider using real condition names or a comment placeholder:

Suggested change

	**Fix:** Add `conditionNames: ['react-server', '...']` to the RSC bundle's `resolve` config.
	**Fix:** Add `conditionNames: ['react-server', 'require', 'node', 'default']` (or whichever conditions your targets need) to the RSC bundle's `resolve` config.

[claude]

Both the BAD and GOOD examples use QueryClient and QueryClientProvider without any import statement. Since the GOOD example is meant to be a copy-paste reference and already includes import { useState } from 'react', it would be more complete to also show the TanStack import:

Suggested change

	// BAD: New QueryClient on every render -- cache is lost
	// BAD: New QueryClient on every render -- cache is lost
	'use client';
	import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
	export default function QueryProvider({ children }) {
	const queryClient = new QueryClient(); // Re-created each render!
	return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
	}

[claude]

The GOOD snippet uses ReactOnRails.authenticityToken() without a visible import. The import is shown in Mistake 2's example (earlier in the file), but Mistake 3's snippet is standalone enough that a reader may copy just this block and hit a ReferenceError. A one-line import at the top of the GOOD block would make it self-contained:

Suggested change

	// GOOD: Include the CSRF token
	// GOOD: Include the CSRF token
	import ReactOnRails from 'react-on-rails';
	await fetch('/api/items', {

[claude]

Solid addition to the RSC migration series. The content is accurate, well-organized, and fills a real gap.

What works well:

• The Migration Readiness Checklist in migrating-to-rsc.md is well-ordered: infrastructure prerequisites first, then a symptom→fix table that maps real errors to remediation steps.
• The Diagnostic Quick-Reference table in rsc-troubleshooting.md maps to real section anchors (spot-checked against headings — all resolve correctly).
• Mistake 2 in rsc-data-fetching.md (Server Actions) was clearly refined across commits — the final wording (unsupported in any environment) is accurate and less ambiguous than earlier drafts.
• Mistake 3 in rsc-third-party-libs.md (barrel imports) correctly scopes the advice to 'use client' boundaries and notes the nuance for non-RSC builds.

Minor issues flagged inline:

1. rsc-preparing-app.md L583 — conditionNames example uses '...' as a string literal, which is not valid JS. Should use real condition names or a comment-style placeholder.
2. rsc-context-and-state.md L486 — QueryClient Mistake 4 uses QueryClient/QueryClientProvider without showing the TanStack import; the GOOD block already includes 'import { useState }' so the pattern is set.
3. rsc-data-fetching.md L822 — Mistake 3 GOOD snippet calls ReactOnRails.authenticityToken() without a visible import; easy to miss if a reader skips directly to this section.

Nit: yarn why react shows the dependency tree but not duplicate versions directly. yarn dedupe --check gives a clearer picture of duplicates. Not a blocker.

[coderabbitai]

🧹 Nitpick comments (1)

docs/oss/migrating/rsc-third-party-libs.md (1)

414-414: Optional: Simplify "Outside of" to "Outside".

The phrase "Outside of" can be simplified to "Outside" for conciseness, though both are grammatically correct and the current version is clear.

✍️ Proposed simplification

-> **Note:** Outside of `'use client'` files, barrel imports are generally fine with modern bundlers. This advice is specific to files that form RSC client boundaries.
+> **Note:** Outside `'use client'` files, barrel imports are generally fine with modern bundlers. This advice is specific to files that form RSC client boundaries.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/oss/migrating/rsc-third-party-libs.md` at line 414, Replace the phrase
"Outside of 'use client' files" with the more concise "Outside 'use client'
files" in the note sentence (the line that begins "**Note:** Outside of 'use
client' files, barrel imports...") so the sentence reads "**Note:** Outside 'use
client' files, barrel imports are generally fine with modern bundlers." Keep the
rest of the sentence unchanged and ensure the quoted token "'use client'"
remains exact.

🤖 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/migrating/rsc-third-party-libs.md`:
- Line 414: Replace the phrase "Outside of 'use client' files" with the more
concise "Outside 'use client' files" in the note sentence (the line that begins
"**Note:** Outside of 'use client' files, barrel imports...") so the sentence
reads "**Note:** Outside 'use client' files, barrel imports are generally fine
with modern bundlers." Keep the rest of the sentence unchanged and ensure the
quoted token "'use client'" remains exact.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 47f40d1b-8ea3-4853-a493-4148a16c6cc1

📥 Commits

Reviewing files that changed from the base of the PR and between 434237a and 896a788.

📒 Files selected for processing (6)

• docs/oss/migrating/migrating-to-rsc.md
• docs/oss/migrating/rsc-context-and-state.md
• docs/oss/migrating/rsc-data-fetching.md
• docs/oss/migrating/rsc-preparing-app.md
• docs/oss/migrating/rsc-third-party-libs.md
• docs/oss/migrating/rsc-troubleshooting.md

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

• docs/oss/migrating/rsc-troubleshooting.md
• docs/oss/migrating/rsc-context-and-state.md
• docs/oss/migrating/migrating-to-rsc.md
• docs/oss/migrating/rsc-preparing-app.md
• docs/oss/migrating/rsc-data-fetching.md