Docs: Clarify .client/.server suffixes vs 'use client' RSC directive#2406
Docs: Clarify .client/.server suffixes vs 'use client' RSC directive#2406AbanoubGhadban merged 11 commits intomasterfrom
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughDocumentation updates across multiple files clarify that file suffix-based bundling ( Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
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 |
AbanoubGhadban
requested review from
alexeyr-ci2,
ihabadham and
justin808
and removed request for
justin808
Greptile OverviewGreptile SummaryClarifies the distinction between Major changes:
Issues found:
Confidence Score: 4/5
Important Files Changed
Last reviewed commit: c138ab3 |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| A React on Rails auto-bundling feature that controls which **webpack bundle** imports a file. This exists independently of React Server Components and is used with or without RSC: | ||
|
|
||
| - `Component.client.jsx` → client bundle only (browser) | ||
| - `Component.server.jsx` → server bundle only (Node.js SSR). Must have a paired `.client.` file. |
There was a problem hiding this comment.
Inconsistent with glossary: the glossary correctly states .server.jsx goes into "server and the RSC bundle" (line 17 of react_on_rails_pro/docs/react-server-components/glossary.md), but here it says "server bundle only". When RSC is enabled, .server.jsx files are included in both bundles.
| - `Component.server.jsx` → server bundle only (Node.js SSR). Must have a paired `.client.` file. | |
| - `Component.server.jsx` → server bundle (and RSC bundle when RSC enabled). Must have a paired `.client.` file. |
There was a problem hiding this comment.
Fixed — updated to "server bundle (and RSC bundle when RSC enabled)" to match the glossary. Also updated the table rows for consistency.
There was a problem hiding this comment.
Good catch — fixed. .server.jsx now correctly says "server bundle (and RSC bundle when RSC enabled)" in both the bullet point and the table.
| A React on Rails auto-bundling feature that controls which webpack bundle imports a file. This exists independently of React Server Components and is used with or without RSC: | ||
|
|
||
| - `Component.client.jsx` → imported only in the **client bundle** (browser) | ||
| - `Component.server.jsx` → imported only in the **server bundle** (Node.js SSR) |
There was a problem hiding this comment.
Same inconsistency: should clarify that .server.jsx files go into server bundle AND RSC bundle (when RSC is enabled), not just "server bundle"
| - `Component.server.jsx` → imported only in the **server bundle** (Node.js SSR) | |
| - `Component.server.jsx` → imported only in the **server bundle** (and RSC bundle when RSC enabled) |
There was a problem hiding this comment.
Fixed — same correction applied here.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @.claude/docs/project-architecture.md:
- Around line 108-114: The documentation block contains fragile, stale
line-number references that will drift; remove all the approximate line
references and leave only the stable method identifiers (e.g.,
common_component_to_path, client_component_to_path, server_component_to_path,
client_entrypoint?, pack_file_contents) and brief descriptions so readers can
grep by name instead of relying on line numbers.
🧹 Nitpick comments (1)
react_on_rails_pro/docs/react-server-components/glossary.md (1)
12-12: Heading level is higher than preceding glossary entry.The first entry "RSC (React Server Component)" at line 3 uses
###(H3), but this new section uses##(H2). This is intentional for visual prominence as a callout, but it breaks the glossary's heading hierarchy — a reader might expect entries to be at consistent levels under the H1 title.
| the exception silently stops working. CI guards (`script/check-react-major-version.mjs`) | ||
| will catch version mismatches. | ||
|
|
||
| ## File Suffixes vs. RSC Directive (Important Distinction) |
There was a problem hiding this comment.
| ## File Suffixes vs. RSC Directive (Important Distinction) | |
| ## `.client` and `.server` File Suffixes vs. RSC Directive (Important Distinction) |
There was a problem hiding this comment.
Applied, thanks!
There was a problem hiding this comment.
Applied, thanks!
| - **Registration**: Components with `'use client'` are registered via `ReactOnRails.register()`. Components without it are registered via `registerServerComponent()`. | ||
| - **RSC bundling**: The RSC webpack loader uses this directive to decide whether a component is included in the RSC bundle or replaced with a client reference in that bundle. | ||
|
|
||
| Checked by `client_entrypoint?` in `packs_generator.rb`. |
There was a problem hiding this comment.
It'''s a cross-reference to the implementation — helps agents (and developers) know which method in packs_generator.rb handles the '\''use client'\'' detection. Reworded it to read more clearly as a full sentence instead of a terse note.
There was a problem hiding this comment.
It's a cross-reference to the implementation — helps agents (and developers) know which method in packs_generator.rb handles the 'use client' detection. Reworded it to read more clearly as a full sentence.
|
|
||
| ### How They Interact | ||
|
|
||
| These are orthogonal. The suffix controls which bundle, the directive controls RSC registration: |
There was a problem hiding this comment.
| These are orthogonal. The suffix controls which bundle, the directive controls RSC registration: | |
| These are orthogonal concerns. The file suffix controls which bundle, and the directive controls RSC registration: |
There was a problem hiding this comment.
Applied, thanks!
There was a problem hiding this comment.
Applied, thanks!
| - Each component gets its own webpack bundle for optimal code splitting | ||
| - No manual `ReactOnRails.register()` calls needed | ||
| - Supports separate `.client.jsx` and `.server.jsx` files for different rendering logic | ||
| - Supports separate `.client.jsx` and `.server.jsx` files for different rendering logic (these control **bundle placement**, not [React Server Components](../../react_on_rails_pro/docs/react-server-components/glossary.md)) |
There was a problem hiding this comment.
| - Supports separate `.client.jsx` and `.server.jsx` files for different rendering logic (these control **bundle placement**, not [React Server Components](../../react_on_rails_pro/docs/react-server-components/glossary.md)) | |
| - Supports separate `.client.jsx` and `.server.jsx` files for different rendering logic (these control **client versus server bundle placement**, not [React Server Components](../../react_on_rails_pro/docs/react-server-components/glossary.md)) |
There was a problem hiding this comment.
Applied, thanks!
|
Heads-up for merge sequencing with the docs cleanup work: I opened #2414 to move internal-only docs out of published trees:
Since #2406 already edits
That keeps agent guidance consistent immediately after the docs move. |
|
Thanks for the heads-up on #2414. Happy to rebase after it merges and update the |
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
.claude/docs/project-architecture.md (1)
97-105: Consider scoping the "Registered as" column to RSC-enabled modeThe table is conceptually correct, but the "Registered as" column only reflects RSC-enabled behavior (i.e.,
registerServerComponent()is called instead ofReactOnRails.register()for components without'use client'). In non-RSC configurations the'use client'directive has no effect on registration — all components go throughReactOnRails.register(). A reader who skims the table without reading the preceding RSC-Classification prose (lines 86–90) could wrongly conclude, for example, thatFoo.client.jsxwithout'use client'is always registered as a "Server component".Adding a brief scope note to the table makes this self-contained:
✏️ Proposed clarification
-### How They Interact +### How They Interact (RSC-enabled mode) These are orthogonal concerns. The file suffix controls which bundle, and the directive controls RSC registration: +> **Note**: The "Registered as" column applies only when RSC support is enabled (Pro feature). +> Without RSC, all components are registered via `ReactOnRails.register()` regardless of the `'use client'` directive. + | File | `'use client'`? | Goes into | Registered as |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.claude/docs/project-architecture.md around lines 97 - 105, Add a short scope note above or below the table clarifying that the "Registered as" column reflects RSC-enabled mode only: in RSC-enabled builds components without the 'use client' directive are registered via registerServerComponent(), whereas in non-RSC configurations all files (e.g., Foo.jsx, Foo.client.jsx, Foo.server.jsx) are registered with ReactOnRails.register() and the 'use client' directive does not affect registration; update the table caption or add a one-line footnote to that effect so readers don’t misinterpret the entries.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.claude/docs/project-architecture.md:
- Line 112: Edit the documentation text for the symbol
`server_component_to_path` to fix the grammar: change the phrase "requires
paired `.client.`" to "requires a paired `.client.`" so the line reads
"`server_component_to_path` — finds `.server.` files (requires a paired
`.client.`)"; no code changes required, just update the doc string/text entry
where `server_component_to_path` is documented.
---
Nitpick comments:
In @.claude/docs/project-architecture.md:
- Around line 97-105: Add a short scope note above or below the table clarifying
that the "Registered as" column reflects RSC-enabled mode only: in RSC-enabled
builds components without the 'use client' directive are registered via
registerServerComponent(), whereas in non-RSC configurations all files (e.g.,
Foo.jsx, Foo.client.jsx, Foo.server.jsx) are registered with
ReactOnRails.register() and the 'use client' directive does not affect
registration; update the table caption or add a one-line footnote to that effect
so readers don’t misinterpret the entries.
PR Review: Docs — Clarify
|
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
PR Review: Docs — Clarify
|
Review: Docs clarification for
|
| - Improved initial page load | ||
| - Better SEO | ||
|
|
||
| ## Important: `.client.` / `.server.` File Suffixes Are Unrelated |
There was a problem hiding this comment.
The new ## Important: section (H2) is inserted after the existing ### RSC (React Server Component) entry (H3). This inverts the expected heading hierarchy — a callout uses a higher-level heading than the preceding glossary entries.
Two clean options:
- Change this heading to
###so it matches the other entries, e.g.:### Note: `.client.` / `.server.` File Suffixes Are Unrelated to RSC - Promote the existing
### RSCentry to##so the glossary has consistent H2 top-level entries.
The content itself is correct and well-placed; it's purely a heading-level issue.
There was a problem hiding this comment.
Added an HTML comment explaining the intentional H2 heading. The callout must visually stand out above the H3 glossary entries to prevent the exact confusion this PR addresses.
| > [!IMPORTANT] | ||
| > **Not related to React Server Components.** The `.client.` and `.server.` file suffixes control **which webpack bundle** imports the file (client bundle vs. server bundle for SSR) — a React on Rails auto-bundling concept that predates React Server Components. If you are using React Server Components (Pro feature), RSC classification is controlled separately by the `'use client'` directive; a `.server.jsx` file is NOT automatically a React Server Component. See the [RSC glossary](../../react_on_rails_pro/docs/react-server-components/glossary.md) for details. | ||
|
|
||
| > Example (dummy app): paired files such as [`ReduxApp.client.jsx`](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails/spec/dummy/client/app/startup/ReduxApp.client.jsx) and [`ReduxApp.server.jsx`](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails/spec/dummy/client/app/startup/ReduxApp.server.jsx), and [`RouterApp.client.jsx`](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails/spec/dummy/client/app/startup/RouterApp.client.jsx) and [`RouterApp.server.jsx`](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails/spec/dummy/client/app/startup/RouterApp.server.jsx). |
There was a problem hiding this comment.
Two consecutive blockquote blocks separated by a blank line (lines 497–498 = the [!IMPORTANT] block; line 500 = the > Example block). No markdownlint config is present in the repo so this won't fail CI, but it can trigger MD028 in external tools. Merging the blank line with a bare > continuation keeps both visually separate while avoiding the issue:
| > [!IMPORTANT] | |
| > **Not related to React Server Components.** The `.client.` and `.server.` file suffixes control **which webpack bundle** imports the file (client bundle vs. server bundle for SSR) — a React on Rails auto-bundling concept that predates React Server Components. If you are using React Server Components (Pro feature), RSC classification is controlled separately by the `'use client'` directive; a `.server.jsx` file is NOT automatically a React Server Component. See the [RSC glossary](../../react_on_rails_pro/docs/react-server-components/glossary.md) for details. | |
| > Example (dummy app): paired files such as [`ReduxApp.client.jsx`](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails/spec/dummy/client/app/startup/ReduxApp.client.jsx) and [`ReduxApp.server.jsx`](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails/spec/dummy/client/app/startup/ReduxApp.server.jsx), and [`RouterApp.client.jsx`](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails/spec/dummy/client/app/startup/RouterApp.client.jsx) and [`RouterApp.server.jsx`](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails/spec/dummy/client/app/startup/RouterApp.server.jsx). | |
| > [!IMPORTANT] | |
| > **Not related to React Server Components.** The `.client.` and `.server.` file suffixes control **which webpack bundle** imports the file (client bundle vs. server bundle for SSR) — a React on Rails auto-bundling concept that predates React Server Components. If you are using React Server Components (Pro feature), RSC classification is controlled separately by the `'use client'` directive; a `.server.jsx` file is NOT automatically a React Server Component. See the [RSC glossary](../../react_on_rails_pro/docs/react-server-components/glossary.md) for details. | |
| > | |
| > Example (dummy app): paired files such as [`ReduxApp.client.jsx`](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails/spec/dummy/client/app/startup/ReduxApp.client.jsx) and [`ReduxApp.server.jsx`](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails/spec/dummy/client/app/startup/ReduxApp.server.jsx), and [`RouterApp.client.jsx`](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails/spec/dummy/client/app/startup/RouterApp.client.jsx) and [`RouterApp.server.jsx`](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails/spec/dummy/client/app/startup/RouterApp.server.jsx). |
There was a problem hiding this comment.
Fixed — added an HTML comment between the two blockquotes to avoid MD028.
…ading intent comment - Add note that "Registered as" column applies only in RSC-enabled mode - Separate consecutive blockquotes with HTML comment to avoid MD028 - Add comment explaining intentional H2 heading in glossary Co-Authored-By: Claude Opus 4.6 <[email protected]>
Review: Docs — Clarify .client/.server suffixes vs 'use client' RSC directiveThis is a well-targeted PR. The confusion between A few issues to address before merging: 1. Heading hierarchy break in
|
| - Better SEO | ||
|
|
||
| <!-- H2 is intentional here: this callout must stand out above the H3 glossary entries to prevent confusion --> | ||
| ## Important: `.client.` / `.server.` File Suffixes Are Unrelated |
There was a problem hiding this comment.
The heading level here creates a non-monotonic structure: the document goes # React Server Components Glossary (H1) → ### RSC (React Server Component) (H3, skipping H2) → ## Important: … (H2, coming after an H3). MD001 will flag this, and navigation tools/screen readers will present a confusing outline.
Two options:
- Fix the existing hierarchy: change
### RSC (React Server Component)to## RSC (React Server Component)— then this H2 fits naturally before the## Types of Componentssection. - Keep H3 entries as-is, use a callout instead: replace the
##heading with a[!IMPORTANT]or[!WARNING]callout block, which provides visual standout without affecting heading structure.
| ## Important: `.client.` / `.server.` File Suffixes Are Unrelated | |
| > [!IMPORTANT] | |
| > **`.client.` / `.server.` File Suffixes Are Unrelated to React Server Components** |
| A React on Rails auto-bundling feature that controls which webpack bundle imports a file. This exists independently of React Server Components and is used with or without RSC: | ||
|
|
||
| - `Component.client.jsx` → imported only in the **client bundle** (browser) | ||
| - `Component.server.jsx` → imported only in the **server bundle** (and RSC bundle when RSC enabled) |
There was a problem hiding this comment.
Missing pairing constraint. server_component_to_path calls raise_missing_client_component for every .server.jsx that has no matching .client.jsx, so a standalone .server.jsx is a hard error at pack-generation time. An agent reading only this bullet will generate invalid scaffolding.
| - `Component.server.jsx` → imported only in the **server bundle** (and RSC bundle when RSC enabled) | |
| - `Component.server.jsx` → imported only in the **server bundle** (and RSC bundle when RSC enabled). **Must be paired with a `Component.client.jsx` file** — a `.server.jsx` without a matching `.client.jsx` raises an error during pack generation. |
| | `Foo.server.jsx` | Yes | Server bundle (+ RSC bundle) | Client component | | ||
| | `Foo.server.jsx` | No | Server bundle (+ RSC bundle) | Server component | |
There was a problem hiding this comment.
The table presents Foo.server.jsx rows as standalone valid configurations, but server_component_to_path enforces that every .server.jsx must have a paired .client.jsx — omitting the pair raises raise_missing_client_component at pack generation time. Foo.client.jsx has no such pairing requirement.
Consider adding a footnote or a ‡ marker on both Foo.server.jsx rows with a note like: "‡ Requires a paired Foo.client.jsx; a .server.jsx without a matching .client.jsx raises an error." This is important context for agents using this table when scaffolding components.
Pre-existing formatting issues unrelated to this PR's changes. Co-Authored-By: Claude Opus 4.6 <[email protected]>
size-limit report 📦
|
PR Review: Docs - Clarify .client/.server suffixes vs 'use client' RSC directiveThe documentation intent here is solid and addresses a real source of confusion. A few issues worth addressing: Heading hierarchy regression in
|
| collectStreamData(stream1), | ||
| collectStreamData(stream2), | ||
| ]); | ||
| const [data1, data2] = await Promise.all([collectStreamData(stream1), collectStreamData(stream2)]); |
There was a problem hiding this comment.
This formatting change (collapsing to one line) is not related to the docs clarification goal of this PR. While 105 chars is within the printWidth: 110 Prettier config and the format is valid, mixing formatting churn into a docs PR complicates review. Consider moving this to a separate formatting commit or PR.
## Summary - move internal-only docs from published paths into `internal/` - relocate: - `docs/contributor-info/` -> `internal/contributor-info/` - `docs/planning/` -> `internal/planning/` - `react_on_rails_pro/docs/contributors-info/` -> `internal/react_on_rails_pro/contributors-info/` - update contributor/doc index links to new internal paths - add `internal/README.md` documenting placement rules ## Why - keeps user-facing docs clean and publishable - prevents internal process docs from being mixed with end-user docs - reduces confusion for contributors and AI agents ## Scope - docs path relocations via `git mv` - link updates in: - `CONTRIBUTING.md` - `react_on_rails_pro/CONTRIBUTING.md` - `SUMMARY.md` - `docs/misc/doctrine.md` - `internal/react_on_rails_pro/contributors-info/releasing.md` ## Notes - intentionally did **not** edit `AGENTS.md` in this PR to avoid overlap with open PR #2406 - follow-up PR can update AGENTS path guidance once #2406 is settled ## Verification - `git mv` preserves history for moved docs - no runtime code changes <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Reorganized internal contributor documentation structure for clearer separation of user-facing vs internal docs. * Updated multiple documentation links to point to the new internal documentation paths. * Added an internal README describing internal docs layout and publishing rules. <!-- end of auto-generated comment: release notes by coderabbit.ai --> <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Docs-only changes that primarily update file paths and links; no runtime or build logic is affected. > > **Overview** > Moves contributor/process documentation references from the published `docs/` tree to the new `internal/` docs area, updating cross-links in `CONTRIBUTING.md`, `SUMMARY.md`, and `react_on_rails_pro/CONTRIBUTING.md` (including CI optimization and release docs). > > Adds `internal/README.md` to define what belongs in `internal/` vs user-facing docs, and adjusts remaining internal doc links (e.g., Pro releasing doc now points at `internal/contributor-info/releasing.md`). > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit eef5d85. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY --> --------- Co-authored-by: Claude Opus 4.6 <[email protected]>
Server components exist only in the RSC bundle and do not need separate file variants. Added this clarification to all files that explain the suffix vs RSC directive distinction. Co-Authored-By: Claude Opus 4.6 <[email protected]>
|
This PR addresses a real and important confusion between two independent naming systems. The overall direction is correct and coverage across docs, Claude instructions, and Ruby code is thorough. A few issues worth addressing before merge. Internal contradiction across the PR Multiple files contain two statements that contradict each other. Statement A (appears verbatim 5+ times, e.g. AGENTS.md:176, project-architecture.md:80, glossary.md:20):
Statement B (e.g. AGENTS.md:191, project-architecture.md:108):
If server components only exist in the RSC bundle, then a Suggested fix: choose one of:
Unrelated formatting changes
Repeated boilerplate Statement A appears word-for-word in 5 files ( |
| - `Component.server.jsx` → imported only in the **server bundle** (and RSC bundle when RSC enabled) | ||
| - `Component.jsx` (no suffix) → imported in **both** bundles | ||
|
|
||
| This controls where the source file is loaded, nothing more. A `.server.jsx` file is NOT a React Server Component — it is simply a file that webpack includes in the server bundle (and the RSC bundle when RSC is enabled). These suffixes only make sense for client components, as server components exist only in the RSC bundle. |
There was a problem hiding this comment.
This statement — "These suffixes only make sense for client components, as server components exist only in the RSC bundle" — directly contradicts line 191 below, which says "A .client.jsx file can be a React Server Component (if it lacks 'use client')".
If server components only exist in the RSC bundle, then a .client.jsx file (whose content ends up in the client bundle) cannot be a server component. One of these two claims must be removed or qualified. Recommend keeping the more precise statement at line 191 and dropping this blanket assertion.
| | `Foo.jsx` | Yes | Both bundles | Client component | | ||
| | `Foo.jsx` | No | Both bundles | Server component | | ||
| | `Foo.client.jsx` | Yes | Client bundle | Client component | | ||
| | `Foo.client.jsx` | No | Client bundle | Server component | |
There was a problem hiding this comment.
This row (Foo.client.jsx | No | Client bundle | Server component) is in tension with the statement on line 80 that "These suffixes only make sense for client components, as server components exist only in the RSC bundle." If that assertion is correct, then this combination — a server component routed to the client bundle — should not be a valid configuration, and including it in the table without a warning may mislead readers.
Consider either:
- Marking these mismatched rows with a
⚠️ or "not recommended" label - Or removing them from the table and only showing the practical cases (matched
'use client'status)
| - `Component.client.jsx` → only imported in the client (browser) bundle | ||
| - `Component.server.jsx` → only imported in the server and the RSC bundle | ||
|
|
||
| A `.server.jsx` file is NOT a React Server Component. A `.client.jsx` file is NOT necessarily a React Client Component. The RSC classification is determined solely by the `'use client'` directive, regardless of file suffix. These suffixes only make sense for client components, as server components exist only in the RSC bundle. See the [auto-bundling docs](../../../docs/core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md#server-rendering-and-client-rendering-components) for details on file suffixes. |
There was a problem hiding this comment.
The phrase "These suffixes only make sense for client components, as server components exist only in the RSC bundle" appears verbatim in at least 5 places across this PR (here, AGENTS.md, project-architecture.md, packs_generator.rb, and the auto-bundling doc). Since the glossary is the canonical reference for RSC terminology, this is the right home for the authoritative definition. The other locations should simply link here rather than duplicating the text — duplication creates maintenance risk if the semantics change.
## Summary - move internal-only docs from published paths into `internal/` - relocate: - `docs/contributor-info/` -> `internal/contributor-info/` - `docs/planning/` -> `internal/planning/` - `react_on_rails_pro/docs/contributors-info/` -> `internal/react_on_rails_pro/contributors-info/` - update contributor/doc index links to new internal paths - add `internal/README.md` documenting placement rules ## Why - keeps user-facing docs clean and publishable - prevents internal process docs from being mixed with end-user docs - reduces confusion for contributors and AI agents ## Scope - docs path relocations via `git mv` - link updates in: - `CONTRIBUTING.md` - `react_on_rails_pro/CONTRIBUTING.md` - `SUMMARY.md` - `docs/misc/doctrine.md` - `internal/react_on_rails_pro/contributors-info/releasing.md` ## Notes - intentionally did **not** edit `AGENTS.md` in this PR to avoid overlap with open PR #2406 - follow-up PR can update AGENTS path guidance once #2406 is settled ## Verification - `git mv` preserves history for moved docs - no runtime code changes <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Reorganized internal contributor documentation structure for clearer separation of user-facing vs internal docs. * Updated multiple documentation links to point to the new internal documentation paths. * Added an internal README describing internal docs layout and publishing rules. <!-- end of auto-generated comment: release notes by coderabbit.ai --> <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Docs-only changes that primarily update file paths and links; no runtime or build logic is affected. > > **Overview** > Moves contributor/process documentation references from the published `docs/` tree to the new `internal/` docs area, updating cross-links in `CONTRIBUTING.md`, `SUMMARY.md`, and `react_on_rails_pro/CONTRIBUTING.md` (including CI optimization and release docs). > > Adds `internal/README.md` to define what belongs in `internal/` vs user-facing docs, and adjusts remaining internal doc links (e.g., Pro releasing doc now points at `internal/contributor-info/releasing.md`). > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit eef5d85. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY --> --------- Co-authored-by: Claude Opus 4.6 <[email protected]>
…upport * origin/master: (38 commits) fix: use env-var-driven ports in Procfile templates to support multiple worktrees (#2539) Fix prettier formatting in auto-bundling doc Docs: Clarify .client/.server suffixes vs use client RSC directive (#2406) Warn against using .server/.client variants with RSC features Docs: move internal-only docs out of published docs trees (#2414) Fix crash when HTTPX::ErrorResponse is returned in get_form_body_for_file (#2532) Skip flaky external URLs in lychee checks (#2547) Update mise docs: prefer shell-level shims over conductor-exec (#2537) Document compression middleware compatibility with streaming SSR (#2544) Fix duplicate node-renderer message reporting in render failures (#2531) Fix private_output_path not configured on fresh Shakapacker installs (#2289) Bump the npm-security group across 1 directory with 3 updates (#2387) docs: use https links (#2518) Consolidate changelog to keep only rc6 prerelease (#2533) Fix CSS module class name divergence with rspack SSR (#2489) Bump version to 16.4.0.rc.6 Add BugBot license scanning config (#2515) Fix buildVM promise cleanup ordering (#2483) (#2484) Fix streaming SSR hangs and silent error absorption in RSC payload injection (#2407) Ensure lefthook uses mise tools in non-interactive shells (#2512) ... # Conflicts: # CHANGELOG.md
## Summary - Add changelog entries for 6 user-visible PRs merged since v16.4.0.rc.6 that were missing from `[Unreleased]` - Update existing #2561 entry to include #2568 contributor credit ### New entries added | Section | PR | Description | |---|---|---| | Added | #2539 | Environment-variable-driven ports in Procfile templates | | Fixed | #2417 | Rspack generator config path fix | | Fixed | #2419 | Precompile hook load-based execution fix | | Fixed | #2577 | `create-react-on-rails-app` validation improvements | | Pro Fixed | #2416 | StreamResponse status fallback fix | | Pro Fixed | #2566 | Empty-string license plan mismatch fix | ### Skipped PRs (not user-visible) Docs (#2406, #2414, #2479, #2494, #2518, #2537, #2544), CI/internal (#2533, #2547, #2555, #2557, #2558, #2564), dependabot (#2387, #2541), dev dependencies (#2559, #2569, #2573). ## Test plan - [ ] Verify changelog formatting matches existing entries - [ ] Verify all user-visible PRs since v16.4.0.rc.6 are covered 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Documentation-only changelog updates with no runtime or build behavior changes. > > **Overview** > Updates `CHANGELOG.md`’s **[Unreleased]** section to include previously missing user-facing entries: Procfile templates now support env-driven ports, several generator/`bin/dev` precompile-hook and rspack-path fixes are documented, and `create-react-on-rails-app` validation improvements are noted. > > Also adds two Pro fix entries (StreamResponse status fallback and license plan empty-string validation) and updates the existing `bin/dev` precompile-hook entry to credit an additional PR/contributor. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit e75d2b5. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY --> Co-authored-by: Claude Opus 4.6 <[email protected]>
2 participants
Clarify across docs and code that
.client./.server.file suffixes (bundle placement) and'use client'directive (RSC classification) are independent concepts. The main goal is avoiding LLM misconception about auto-bundling postfixes and React Server Components — LLMs consistently confuse.server.jsxfiles with React Server Components.Also documents that
.server/.clientsuffixes only make sense for client components, as server components exist only in the RSC bundle.We initially attempted a programmatic fix in shakacode/react_on_rails_rsc#25 but closed it as unnecessary — updating docs to flag the antipattern is sufficient.
Closes #2405
🤖 Generated with Claude Code
Summary by CodeRabbit