Summary
Gather real-world feedback on mistakes and pain points clients encounter while migrating to React Server Components, then fold that knowledge back into the existing migration guide series.
Motivation
We have a comprehensive 6-part RSC migration guide (docs/oss/migrating/migrating-to-rsc.md → rsc-troubleshooting.md), but it was written largely from first-principles knowledge. Now that clients are actually going through the migration, we should capture the patterns of mistakes they hit in practice — some of which we may not have anticipated — and strengthen the docs accordingly.
Proposed Work
1. Collect data on common client mistakes
- Review support channels, Slack threads, and client conversations for recurring RSC migration issues
- Categorize mistakes by migration phase (infrastructure setup, component restructuring, state management, data fetching, third-party libs)
- Identify which mistakes are React on Rails-specific vs. general RSC pitfalls
2. Prioritize by frequency and severity
- Rank issues by how often they come up and how much time they cost to debug
- Flag any that cause production incidents vs. development-time confusion
3. Update the migration guide
Depending on findings, potential updates include:
rsc-preparing-app.md — add common setup mistakes (e.g., missing route mounting, incorrect webpack config)rsc-component-patterns.md — add "don't do this" examples for 'use client' boundary placementrsc-context-and-state.md — add pitfalls around Context/Redux that clients actually hitrsc-data-fetching.md — clarify migration paths from patterns clients actually use (not just React Query/SWR)rsc-third-party-libs.md — update compatibility matrix based on what clients are actually usingrsc-troubleshooting.md — add new error messages and debugging scenarios from real migrations
4. Consider adding
- A "Common Mistakes" callout box at the top of each guide section
- A quick-reference checklist for migration readiness
- Links to real anonymized before/after examples where applicable
Acceptance Criteria
Summary
Gather real-world feedback on mistakes and pain points clients encounter while migrating to React Server Components, then fold that knowledge back into the existing migration guide series.
Motivation
We have a comprehensive 6-part RSC migration guide (
docs/oss/migrating/migrating-to-rsc.md→rsc-troubleshooting.md), but it was written largely from first-principles knowledge. Now that clients are actually going through the migration, we should capture the patterns of mistakes they hit in practice — some of which we may not have anticipated — and strengthen the docs accordingly.Proposed Work
1. Collect data on common client mistakes
2. Prioritize by frequency and severity
3. Update the migration guide
Depending on findings, potential updates include:
rsc-preparing-app.md— add common setup mistakes (e.g., missing route mounting, incorrect webpack config)rsc-component-patterns.md— add "don't do this" examples for'use client'boundary placementrsc-context-and-state.md— add pitfalls around Context/Redux that clients actually hitrsc-data-fetching.md— clarify migration paths from patterns clients actually use (not just React Query/SWR)rsc-third-party-libs.md— update compatibility matrix based on what clients are actually usingrsc-troubleshooting.md— add new error messages and debugging scenarios from real migrations4. Consider adding
Acceptance Criteria