Split docs and migration content into focused update#2896
Split docs and migration content into focused update#2896
Conversation
WalkthroughUpdated React on Rails documentation repository-wide: raised minimum version requirements (Ruby 3.2+, Node 20+), consolidated Pro documentation links from relative internal paths to absolute external URLs ( Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 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 |
coderabbitai
bot
added
review-needed
documentation
docs-cleanup
|
PR Review: Split docs and migration content Good documentation housekeeping overall - the link consolidation toward pro.reactonrails.com is clean and consistent. However, I found several factual issues and one security concern that need attention before merging. Bugs / Incorrect Facts
Security Concern
Quality Issues
|
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| ``` | ||
| 2. Make sure you have **Node.js 18+** and a JavaScript package manager such as **npm**, **pnpm**, **Yarn**, or **bun**. | ||
| 3. Initialize a Node application and install the `react-on-rails-pro-node-renderer` package. | ||
| 2. Make sure you have **Node.js** version **14** or higher and **Yarn** installed. |
There was a problem hiding this comment.
Node.js 14 is end-of-life and contradicts the project's own updated requirement. This PR bumps prerequisites to Node.js 20+ everywhere else.
| 2. Make sure you have **Node.js** version **14** or higher and **Yarn** installed. | |
| 2. Make sure you have **Node.js 20+** and a JavaScript package manager such as **npm**, **pnpm**, **Yarn**, or **bun**. |
|
|
||
| 1. Set `config.server_renderer = "NodeRenderer"` | ||
| 2. Decide whether to enable `config.prerender_caching = true`. The default is `false`; turn it on only if you want Rails cache-backed SSR result caching and your cache is configured for the additional load. | ||
| 2. Leave the default of `config.prerender_caching = true` and ensure your Rails cache is properly configured to handle the additional cache load. |
There was a problem hiding this comment.
This is incorrect — the default for prerender_caching is false, not true. The removed text correctly described it as opt-in. Stating the wrong default here will cause confusion for users who are surprised to find caching is not active.
| 2. Leave the default of `config.prerender_caching = true` and ensure your Rails cache is properly configured to handle the additional cache load. | |
| 2. Optionally enable `config.prerender_caching = true` if you want Rails cache-backed SSR result caching and your cache is configured for the additional load. The default is `false`. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 085e515949
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| # Install nodejs | ||
| echo "install nodejs" | ||
| curl --silent --location https://rpm.nodesource.com/setup_6.x | sudo bash - |
There was a problem hiding this comment.
This new Elastic Beanstalk guide installs Node via setup_6.x, which provisions an end-of-life Node 6 runtime. Users following this document will end up with an unsupported Node version that is incompatible with current React on Rails tooling (the repo docs now require modern Node) and may fail during build/runtime; this should be updated to a current LTS install path.
Useful? React with 👍 / 👎.
| @@ -37,44 +36,4 @@ node packages/create-react-on-rails-app/bin/create-react-on-rails-app.js my-app | |||
| node packages/create-react-on-rails-app/bin/create-react-on-rails-app.js my-rsc-app --rsc --template javascript --package-manager pnpm | |||
There was a problem hiding this comment.
The manual smoke-test commands run bin/create-react-on-rails-app.js, which loads ../lib/index.js (built output), but this updated section no longer tells contributors to rebuild first. When someone is testing local CLI changes from src/, these instructions can run stale lib code and produce misleading smoke-test results; add an explicit build step before the manual commands.
Useful? React with 👍 / 👎.
| React on Rails does not define an `images` alias by default. If you want one, add it explicitly. | ||
| For example, if your images live in `app/javascript/images`, then `"images/foobar.jpg"` can point | ||
| to `app/javascript/images/foobar.jpg` with a custom alias like this: | ||
| **images** is a defined alias, so "images/foobar.jpg" would point to the file at |
There was a problem hiding this comment.
This is incorrect. React on Rails does not define an images alias — this code block below is showing an example of how to add one yourself. Claiming it's "a defined alias" will mislead users into thinking the path just works out of the box.
| **images** is a defined alias, so "images/foobar.jpg" would point to the file at | |
| **images** is not defined as an alias by default. If you want one, add it explicitly. For example, to make `"images/foobar.jpg"` resolve to `/client/app/assets/images/foobar.jpg`: |
| In all other environments (`staging`, `production`, etc.), the renderer will refuse to start without an explicit password. Set `RENDERER_PASSWORD` in your environment or pass `password` in the config object. | ||
| 1. **allWorkersRestartInterval** (default: `env.RENDERER_ALL_WORKERS_RESTART_INTERVAL`) - Interval in minutes between scheduled restarts of all workers. By default restarts are not enabled. If restarts are enabled, `delayBetweenIndividualWorkerRestarts` should also be set. **Recommended for production** — rolling restarts are the primary safety net against memory leaks from application code. See the [Memory Leaks guide](../../../pro/js-memory-leaks.md). | ||
| 1. **delayBetweenIndividualWorkerRestarts** (default: `env.RENDERER_DELAY_BETWEEN_INDIVIDUAL_WORKER_RESTARTS`) - Interval in minutes between individual worker restarts (when cluster restart is triggered). By default restarts are not enabled. If restarts are enabled, `allWorkersRestartInterval` should also be set. Set this high enough so that not all workers are down simultaneously (e.g., if you have 4 workers and set this to 5 minutes, the full restart cycle takes 20 minutes). | ||
| If no password is set, no authentication will be required. |
There was a problem hiding this comment.
The removed text contained an important security contract: in staging/production environments the renderer refuses to start without a password. The new wording ("no authentication will be required") implies the renderer will happily run unauthenticated in production.
Please verify the actual runtime behavior:
- If the code still enforces a password in production, restore the warning.
- If the enforcement was intentionally removed, document the change explicitly and add a security advisory so users know to set
RENDERER_PASSWORDmanually.
| ```js | ||
| const path = require('path'); | ||
| const { reactOnRailsProNodeRenderer } = require('react-on-rails-pro-node-renderer'); | ||
| import path from 'path'; |
There was a problem hiding this comment.
The example switched to ES module syntax (import), but the setup instructions above say to run it with node ./node-renderer.js. Plain Node.js will throw SyntaxError: Cannot use import statement in a module unless:
package.jsoncontains"type": "module", or- the file is renamed to
.mjs
Either add a note about this requirement, or revert to the CommonJS (const { ... } = require(...)) syntax which works without any extra config — especially important for a copy-paste quickstart example.
| Note: if you use the [mini_racer](https://github.com/rubyjs/mini_racer) runtime and run into a `ReferenceError: TextEncoder is not defined` error, see [this comment](https://github.com/shakacode/react_on_rails/issues/1457#issuecomment-1165026717) for a solution. | ||
|
|
||
| If you want to maximize the performance of your server rendering, then you want to use React on Rails Pro which uses NodeJS to do the server rendering. See the [docs for React on Rails Pro](../../pro/home-pro.md). | ||
| If you want to maximize the performance of your server rendering, then you want to use React on Rails Pro which uses NodeJS to do the server rendering. See the [docs for React on Rails Pro](https://github.com/shakacode/react_on_rails/wiki). |
There was a problem hiding this comment.
The GitHub wiki is not the right destination for Pro feature docs — it hasn't been the canonical Pro docs location for some time. This PR standardizes all other Pro links on https://pro.reactonrails.com, so this one should match.
| If you want to maximize the performance of your server rendering, then you want to use React on Rails Pro which uses NodeJS to do the server rendering. See the [docs for React on Rails Pro](https://github.com/shakacode/react_on_rails/wiki). | |
| If you want to maximize the performance of your server rendering, then you want to use React on Rails Pro which uses NodeJS to do the server rendering. See the [docs for React on Rails Pro](https://pro.reactonrails.com). |
| 4. Look for growing `string`, `Object`, and `Array` counts — these typically point to module-level caches. | ||
|
|
||
| See the [Memory Leaks guide](../../../pro/js-memory-leaks.md) for common patterns and fixes. | ||
| 1. cd to the top level of the project. |
There was a problem hiding this comment.
This debugging workflow (yalc, top-level yarn, nps renderer.debug) describes the old monorepo setup and does not match the current repo structure, which uses pnpm workspaces. Contributors following these steps won't get a working environment.
The removed content (using pnpm from react_on_rails_pro/spec/dummy) was accurate. If the Pro package has genuinely moved back to a yarn/yalc workflow, please verify with the current package.json files before finalizing this.
Greptile SummaryThis PR splits a large documentation-and-migration branch into a focused docs-only update across 69 files, covering OSS guides, Pro docs, migration content, the README,
Confidence Score: 3/5Not safe to merge as-is — four P1 issues will actively mislead or break users following the docs. The PR has four P1 findings: a broken internal link, stale pre-release version numbers replacing current stable ones in an actively-read RSC guide, a restored deployment guide that installs an EOL Node.js version that conflicts with the requirements updated in this same PR, and a missing gem-install step in the AI agent guide. Any one of these will result in a broken or misleading experience for users who follow the affected docs. docs/pro/react-server-components/create-without-ssr.md (stale alpha versions), docs/oss/deployment/elastic-beanstalk.md (Node 6 EOL), docs/README.md (broken changelog link), llms.txt (missing bundle add step) Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[User finds React on Rails docs] --> B{OSS or Pro?}
B -->|OSS| C[README.md / docs/README.md]
B -->|Pro| D[docs/pro/react-on-rails-pro.md]
C --> E[docs/oss/getting-started/quick-start.md]
C --> F["docs/README.md Changelog link BROKEN: ./oss/upgrading/changelog.md does not exist"]
D --> G[docs/pro/installation.md]
D --> H["docs/oss/getting-started/pro-quick-start.md - Expanded step-by-step guide"]
H --> I["docs/pro/react-server-components/create-without-ssr.md - Stale alpha versions 15.0.0-alpha.2"]
E --> J["llms.txt AI agent install guide - Missing bundle add step"]
C --> K["docs/oss/deployment/elastic-beanstalk.md - Installs Node.js 6 EOL 2019"]
Reviews (1): Last reviewed commit: "Split docs and migration content into fo..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| - [Deployment and troubleshooting](./oss/deployment/README.md) | ||
| - [Configuration](./oss/configuration/README.md) | ||
| - [Changelog](https://github.com/shakacode/react_on_rails/blob/main/CHANGELOG.md) | ||
| - [Changelog](./oss/upgrading/changelog.md) |
There was a problem hiding this comment.
changelog.md does not exist
The link ./oss/upgrading/changelog.md was added here, but no such file exists in the repository. Listing docs/oss/upgrading/ shows only upgrading-react-on-rails.md and release-notes/ — there is no changelog.md. This will result in a 404 for any user who clicks it.
The previous link pointed to the real file on GitHub:
| - [Changelog](./oss/upgrading/changelog.md) | |
| - [Changelog](https://github.com/shakacode/react_on_rails/blob/main/CHANGELOG.md) |
|
|
||
| Note: These versions are not released yet, they are still in development. But they will have these versions when released. | ||
|
|
||
| ```bash | ||
| # Pick one JS package manager command (Pro includes all base package functionality): | ||
| yarn add --exact [email protected] | ||
| # npm install --save-exact [email protected] | ||
| # pnpm add --save-exact [email protected] | ||
| # bun add --exact [email protected] | ||
|
|
||
| # Then add the Ruby gems: | ||
| bundle add react_on_rails --version "16.4.0" --strict | ||
| bundle add react_on_rails_pro --version "16.4.0" --strict | ||
| yarn add [email protected] [email protected] | ||
| bundle add [email protected] [email protected] | ||
| ``` |
There was a problem hiding this comment.
This diff replaces the current stable 16.4.0 install commands with very old pre-release versions (15.0.0-alpha.2 / 4.0.0) and even adds a note saying "these versions are not released yet, they are still in development." This will mislead users into attempting to install non-existent or incorrectly versioned packages.
The note and the alpha version numbers should be removed and the instructions should use the current stable version (or a ~> / ^ range). For example, the previous content used:
yarn add --exact [email protected]
bundle add react_on_rails --version "16.4.0" --strict
bundle add react_on_rails_pro --version "16.4.0" --strictThis needs to be corrected before merging to avoid breaking RSC setup instructions for all readers.
| # install yarn | ||
| wget https://dl.yarnpkg.com/rpm/yarn.repo -O /etc/yum.repos.d/yarn.repo; | ||
| yum -y install yarn; |
There was a problem hiding this comment.
This script uses https://rpm.nodesource.com/setup_6.x to install Node.js 6. Node 6 reached end-of-life in April 2019. React on Rails now requires Node.js ≥ 20 (updated in README.md and AGENTS_USER_GUIDE.md in this same PR), so this guide will cause deployment failures for any user who follows it.
Additionally, this file was deliberately archived in the previous version of docs/oss/deployment/README.md with a link to the git history rather than being re-published as live documentation.
If this file is being restored, the Node version must be updated to at least 20.x, and the setup_6.x URL should be replaced accordingly.
| ```bash | ||
| bundle add react_on_rails --strict | ||
| bundle exec rails generate react_on_rails:install | ||
| rails generate react_on_rails:install | ||
| ``` |
There was a problem hiding this comment.
bundle add step for base gem installation
The base installation snippet was changed from:
bundle add react_on_rails --strict
bundle exec rails generate react_on_rails:installto just:
rails generate react_on_rails:installThe generator will fail immediately if react_on_rails is not in the Gemfile yet. Without the bundle add step, an agent or developer following this file will hit an unresolvable error at generator time. The bundle add step (or equivalent Gemfile edit + bundle install) must be preserved so the gem is available before the generator runs.
| - **Starting a new Pro app from scratch?** Use [Pro Installation](../../pro/installation.md#fresh-installation). | ||
| - **Upgrading an existing React on Rails app?** Use [Upgrading from React on Rails to React on Rails Pro](../../pro/upgrading-to-pro.md). | ||
| - **Still deciding between OSS and Pro?** Review [React on Rails: OSS vs Pro Feature Comparison](./oss-vs-pro.md). | ||
| **Prerequisites:** Ruby 3.0+, Rails 7.0+, Node.js 18+, npm/yarn/pnpm |
There was a problem hiding this comment.
This line still lists "Ruby 3.0+, Rails 7.0+, Node.js 18+" as prerequisites, but within this same PR README.md was updated to "Ruby >= 3.2 (CI tested: 3.2 - 3.4)" and AGENTS_USER_GUIDE.md was updated to "Ruby 3.2+" / "Node.js 20+". The guide should reflect the same minimums.
| **Prerequisites:** Ruby 3.0+, Rails 7.0+, Node.js 18+, npm/yarn/pnpm | |
| **Prerequisites:** Ruby 3.2+, Rails 7.0+, Node.js 20+, npm/yarn/pnpm |
| yarn outdated | ||
| ``` | ||
|
|
There was a problem hiding this comment.
cd client may not match all app layouts
The previous version of this doc explicitly noted: "In current React on Rails apps, that is usually the app root rather than a client/ subdirectory." The new version hardcodes cd client in every example, which will confuse users whose package.json lives at the Rails root (the now-default layout). Consider adding a note that the directory depends on the project's layout, or defaulting to the root.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 19
🧹 Nitpick comments (9)
docs/oss/building-features/how-to-conditionally-server-render-based-on-device-type.md (1)
30-30: Use the canonical docs URL here for consistency.This line still points to a repo blob while the nearby line already uses the canonical docs site. Consider switching both to
https://reactonrails.com/docs/configuration/to avoid split-link maintenance.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/oss/building-features/how-to-conditionally-server-render-based-on-device-type.md` at line 30, Replace the repository blob URL 'https://github.com/shakacode/react_on_rails/blob/main/docs/configuration/README.md' in this file with the canonical docs URL 'https://reactonrails.com/docs/configuration/' so the link matches the nearby canonical link and avoids split-link maintenance; update any identical occurrences in the same file to the canonical URL to keep links consistent.docs/oss/migrating/rsc-preparing-app.md (1)
507-507: Prefer explicit field whitelisting in theas_jsonexample.Using
include: [:specs, :reviews]as-is can normalize over-serialization in migration docs. Consider showing a narrowedonly:shape to model safer payload boundaries.Also applies to: 517-517
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/oss/migrating/rsc-preparing-app.md` at line 507, The example uses product.as_json(include: [:specs, :reviews]) which encourages broad serialization; change it to explicitly whitelist fields (e.g., use product.as_json(only: [...], include: { specs: { only: [...] }, reviews: { only: [...] } })) so the props payload is limited and predictable; update the props line (props: { product: ... }) to use as_json with only: and nested include-only shapes instead of a bare include: list for both occurrences.docs/oss/building-features/node-renderer/debugging.md (1)
17-24: Add npm/pnpm alternatives (or explicitly label this as repo-maintainer-only workflow).The checklist is currently Yarn-only. In end-user docs under
docs/, command guidance should be package-manager-agnostic unless this section is clearly scoped to internal maintainers.Based on learnings: In all end-user documentation under docs/, ensure package-manager-agnostic installation instructions include npm, yarn, and pnpm.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/oss/building-features/node-renderer/debugging.md` around lines 17 - 24, The steps in debugging.md are yarn-specific; update the instructions to be package-manager-agnostic by adding equivalent npm and pnpm command alternatives for each yarn command (e.g., for `yarn` add `npm install`/`pnpm install`, for `yarn build:dev` add `npm run build:dev`/`pnpm run build:dev`, for `yarn start` add `npm start`/`pnpm start`) and mention the same environment variable usage (`RENDERER_LOG_LEVEL=debug`) works with Windows-compatible syntax when needed; alternatively, if this workflow is intended only for repo maintainers, explicitly label the file as maintainer-only and keep the yarn examples but add a short note referencing the nps task `nps renderer.debug` and the `spec/dummy/package.json` script `"node-renderer-debug"` so readers know where to find the exact commands.docs/oss/deployment/server-rendering-tips.md (1)
17-17: Use a direct Pro docs target instead of a generic wiki landing page.Line 17 currently routes to a broad wiki URL, which makes users hunt for the right page. Prefer a direct Node renderer/Pro overview URL to keep this tip actionable.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/oss/deployment/server-rendering-tips.md` at line 17, Replace the generic wiki link in the sentence "You can enable Node.js server rendering via [React on Rails Pro]" with a direct React on Rails Pro documentation URL that specifically covers the Node renderer or the Pro overview (i.e., point the link target to the React on Rails Pro Node renderer/Pro overview doc in the react_on_rails docs rather than the wiki landing page) so users land directly on the actionable Pro documentation.docs/pro/react-server-components/create-without-ssr.md (1)
16-23: Add npm and pnpm alternatives for these install commands.The changed install section only shows Yarn commands. End-user docs in
docs/should provide npm, yarn, and pnpm options.Suggested doc fix
```bash - yarn add --exact [email protected] + yarn add --exact [email protected] + # or + npm install --save-exact [email protected] + # or + pnpm add --exact [email protected] bundle add [email protected] [email protected]- yarn add [email protected] [email protected] [email protected] + yarn add [email protected] [email protected] [email protected] + # or + npm install [email protected] [email protected] [email protected] + # or + pnpm add [email protected] [email protected] [email protected]</details> Based on learnings: End-user documentation under `docs/` should include npm, yarn, and pnpm instructions. <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/pro/react-server-components/create-without-ssr.mdaround lines 16 - 23,
Update the install commands in
docs/pro/react-server-components/create-without-ssr.md so that the existing Yarn
lines (e.g., "yarn add [email protected] [email protected]"
and "yarn add [email protected] [email protected] [email protected]") are
followed by equivalent npm and pnpm alternatives (use --save-exact or --save
where appropriate for npm and --exact for pnpm) so users see three options
(yarn, npm, pnpm) for each installation step.</details> </blockquote></details> <details> <summary>docs/oss/getting-started/pro-quick-start.md (1)</summary><blockquote> `43-50`: **Add package-manager-agnostic installation instructions.** Lines 43-50 show only Yarn commands for initializing and installing Shakapacker: ```bash yarn init yarn add react-on-rails-pro-node-rendererBased on learnings, "In all end-user documentation under docs/, ensure package-manager-agnostic installation instructions include npm, yarn, and pnpm. Reserve the pnpm-only policy for internal development files."
Please add npm and pnpm alternatives:
📦 Suggested package-manager-agnostic instructions
## Step 3: Install Shakapacker ```bash rails shakapacker:install-## Step 4: Commit (required by generator)
+## Step 4: Init node application (if needed)
+
+If you don't have a package.json yet:
+
+bash +# npm +npm init -y + +# yarn +yarn init -y + +# pnpm +pnpm init +
+
+## Step 5: Commit (required by generator)And update subsequent step numbers accordingly. </details> Based on learnings: In all end-user documentation under docs/, ensure package-manager-agnostic installation instructions include npm, yarn, and pnpm. <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/oss/getting-started/pro-quick-start.mdaround lines 43 - 50, Update the
docs fragment that currently shows only Yarn commands under the heading "## Step
4: Commit (required by generator)" by replacing that heading with "## Step 4:
Init node application (if needed)" and adding package-manager-agnostic init
commands for npm and pnpm alongside the existing yarn init (npm init -y, yarn
init -y, pnpm init). Insert a brief conditional note "If you don't have a
package.json yet:" above the three init commands, then renumber the subsequent
heading ("## Step 5: Commit (required by generator)") and any following step
references accordingly to reflect the new step ordering; target the block
containing the yarn init/yarn add lines and the heading text to make these
edits.</details> </blockquote></details> <details> <summary>docs/oss/building-features/node-renderer/basics.md (1)</summary><blockquote> `46-51`: **Restore package-manager-agnostic installation instructions.** Lines 46-51 now show only Yarn commands, removing the previous npm/pnpm/bun options: ```bash yarn init yarn add react-on-rails-pro-node-rendererThis violates the established documentation guideline. Based on learnings: "In all end-user documentation under docs/, ensure package-manager-agnostic installation instructions include npm, yarn, and pnpm. Reserve the pnpm-only policy for internal development files."
Please restore package-manager-agnostic instructions:
📦 Suggested package-manager-agnostic instructions
-2. Make sure you have **Node.js** version **14** or higher and **Yarn** installed. -3. Init node application and install the `react-on-rails-pro-node-renderer` package. +2. Make sure you have **Node.js** version **14** or higher and a package manager (**npm**, **yarn**, or **pnpm**) installed. +3. Init node application and install the `react-on-rails-pro-node-renderer` package: + ```sh + # npm + npm init -y + npm install --save-exact react-on-rails-pro-node-renderer + + # yarn yarn init yarn add react-on-rails-pro-node-renderer + + # pnpm + pnpm init + pnpm add --save-exact react-on-rails-pro-node-renderer ```Based on learnings: In all end-user documentation under docs/, ensure package-manager-agnostic installation instructions include npm, yarn, and pnpm.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/oss/building-features/node-renderer/basics.md` around lines 46 - 51, The docs currently show only Yarn commands for installing react-on-rails-pro-node-renderer; restore package-manager-agnostic installation instructions by replacing the single Yarn block with three subsections (npm, yarn, pnpm) that include the suggested commands: npm init -y and npm install --save-exact react-on-rails-pro-node-renderer, yarn init and yarn add react-on-rails-pro-node-renderer, and pnpm init and pnpm add --save-exact react-on-rails-pro-node-renderer so the documentation once again covers npm, yarn, and pnpm for the package installation step.docs/pro/react-on-rails-pro.md (1)
19-19: Consider adding H2 heading before H3 for proper markdown structure.Line 19 uses an H3 heading (
###) directly after the H1 page title, skipping the H2 level:# React on Rails Pro ← H1 ... ### Pro: Docs ← H3 (skips H2)While this works visually, it violates markdown heading hierarchy best practices. Consider either:
- Change
### Pro: Docsto## Pro: Docs(making all subsections H2), or- Add an H2 section wrapper like
## Featuresbefore the H3 subsections♻️ Option 1: Promote all subsections to H2
-### Pro: Docs +## Pro: Docs -### Pro: React Server Components +## Pro: React Server Components -### Pro: Fragment Caching +## Pro: Fragment Caching -### Pro: Integration with Node.js for Server Rendering +## Pro: Integration with Node.js for Server Rendering🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/pro/react-on-rails-pro.md` at line 19, The document currently uses an H3 heading "### Pro: Docs" directly under the H1 title; update the markdown to restore proper heading hierarchy by either changing that heading text "### Pro: Docs" to an H2 ("## Pro: Docs") or by adding an H2 wrapper (for example add "## Features" or similar above the existing H3 and keep the "### Pro: Docs" as a subsection); locate the heading string "Pro: Docs" in the file and apply one of these two fixes consistently for other subsections if present.docs/oss/building-features/node-renderer/js-configuration.md (1)
97-97: Prefer package-manager-agnostic run instructions in end-user docs.Line 97 currently documents only
yarn start. Please include npm and pnpm equivalents too.Suggested doc wording
-`yarn start` will run the renderer. +Run the renderer with your package manager: + +- `yarn start` +- `pnpm start` +- `npm run start`Based on learnings: In all end-user documentation under docs/, ensure package-manager-agnostic installation instructions include npm, yarn, and pnpm.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/oss/building-features/node-renderer/js-configuration.md` at line 97, The docs currently only show "yarn start"; update the end-user instruction to be package-manager-agnostic by adding the npm and pnpm equivalents alongside the existing yarn command (e.g., include "npm run start" and "pnpm start") so users of any package manager can follow the same step; locate the string "yarn start" in js-configuration.md and replace or expand it to list all three commands.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@AGENTS_USER_GUIDE.md`:
- Around line 35-36: The docs currently list strict prerequisites "ruby -v #
Should be 3.2+" and "node -v # Should be 20+" which use CI-floor minimums;
update these validator-floor minimums to "Ruby >= 3.0" and "Node >= 18" instead
(replace the version comments next to the "ruby -v" and "node -v" lines
accordingly) so the AGENTS_USER_GUIDE reflects supported floors rather than
CI-tested floors.
In `@docs/oss/api-reference/generator-details.md`:
- Around line 212-214: The current install note ("Add `gem 'react_on_rails_pro',
'>= 16.3.0'` ... Contact [email protected] for a license") implies a paid
license is required to run locally; update the wording to clarify that adding
the gem is optional for Pro features but a production license
(REACT_ON_RAILS_PRO_LICENSE) is only required for production deployments —
evaluation, development, testing and CI do not require a paid key — and keep the
contact ([email protected]) as the channel for obtaining a production license
or questions; reference the Gemfile gem declaration (`gem 'react_on_rails_pro',
'>= 16.3.0'`) and the environment variable name (`REACT_ON_RAILS_PRO_LICENSE`)
so the change is applied to the same explanatory bullet points.
In `@docs/oss/building-features/i18n.md`:
- Line 139: The docs line currently instructs adding dependencies to
"client/package.json", which is too specific; update the phrase in
docs/oss/building-features/i18n.md (the line containing "Add `react-intl` &
`intl` to `client/package.json`") to the more general wording "Add `react-intl`
& `intl` to your `package.json`" so the guidance applies to both modern
(root-level package.json) and legacy (client/) project structures.
In `@docs/oss/building-features/images.md`:
- Around line 37-44: The documentation wrongly asserts that the "images" alias
exists by default; update the text around the resolve.alias snippet to state
that this is an example showing how to add an alias (not a built-in), e.g.
explain that users must add the resolve.alias entry (images ->
join(process.cwd(), 'app','assets','images')) to their webpack config if they
want to import "images/..." paths, or remove the claim entirely so it no longer
implies a default alias exists. Ensure you reference the resolve: { alias: {
images: join(process.cwd(), 'app', 'assets', 'images') } } example and clarify
it is optional user configuration.
In `@docs/oss/building-features/node-renderer/js-configuration.md`:
- Around line 65-71: The snippet uses ESM imports but still references __dirname
(used in serverBundleCachePath via path.resolve), which is undefined in ES
modules; update the example to derive __dirname from import.meta.url (e.g.,
using fileURLToPath(import.meta.url) and path.dirname) or use new URL-based
dirname resolution so serverBundleCachePath is computed from a valid directory
value when using the reactOnRailsProNodeRenderer example and path.resolve.
In `@docs/oss/core-concepts/react-server-rendering.md`:
- Line 15: Replace the GitHub wiki link used in the sentence referencing React
on Rails Pro — specifically change the URL string
"https://github.com/shakacode/react_on_rails/wiki" to the canonical Pro docs URL
"https://pro.reactonrails.com" in the
docs/oss/core-concepts/react-server-rendering.md content so the Pro destination
is standardized across the docs.
In `@docs/oss/deployment/elastic-beanstalk.md`:
- Around line 28-29: The docs currently instruct installing Node 6 via the curl
pipe and yum commands shown (curl --silent --location
https://rpm.nodesource.com/setup_6.x | sudo bash - and yum -y install nodejs);
replace these with a modern Node 18+ installation method (e.g., use NodeSource
setup_18.x or recommend nvm/official distro packages) and update the yum
installation step accordingly so the guide installs a supported Node version
compatible with React on Rails rather than EOL Node 6.
In `@docs/oss/deployment/README.md`:
- Line 3: Replace the awkward sentence "Shakapacker puts the necessary
precompile steps automatically in the rake precompile step." with a tighter
phrasing such as "Shakapacker automatically runs the required precompile steps
during `rake precompile`." Update the README sentence accordingly to improve
clarity and tone.
In `@docs/oss/deployment/troubleshooting.md`:
- Around line 41-44: Update the Node.js version guidance and broaden
package-manager instructions: change the "Install Node.js 20+" line to note the
minimum supported version 18+ and add the CI-tested range (e.g., "Node.js 18+
(CI-tested: 18–20)"). Replace the Yarn-only install lines ("Install Yarn: npm
install -g yarn" / "Or use system package manager: brew install node yarn") with
package-manager-agnostic options that include npm and pnpm alternatives (e.g.,
npm global install and pnpm global install or recommend using corepack), and
apply the same edits to the second occurrence referenced in the comment (the
block at lines 53–56).
In `@docs/oss/getting-started/tutorial.md`:
- Line 98: The docs use the command "git commit -am" which skips untracked files
and can prevent generated files from being included; update the tutorial step to
explicitly stage files first (e.g., run "git add ." or explicitly list generated
files) before committing, and replace the "git commit -am \"Initial commit\""
line with the two-step staging + commit sequence so fresh app flows include
generated/untracked files.
In `@docs/oss/misc/style.md`:
- Line 25: Update the JSDoc link anchor so it points to the current official
site: replace the outdated and insecure URL "http://usejsdoc.org/" with
"https://jsdoc.app/" in the markdown link entry (the line containing
"[JSDoc](http://usejsdoc.org/)") so the link uses the correct HTTPS domain.
In `@docs/oss/misc/updating-dependencies.md`:
- Around line 13-71: The docs currently show only Yarn commands under the
"Node/Yarn" section; update the user-facing guide to be package-manager-agnostic
by adding npm and pnpm equivalents alongside each Yarn command. For "Checking
for Outdated Packages" add "npm outdated" and "pnpm outdated"; for the
npm-check-updates flow (ncu -u -a) show using npx/npm-run (npx npm-check-updates
-u or npx ncu -u -a) and then npm install and pnpm install as alternatives to
"yarn"; for the "yarn upgrade" and "yarn upgrade [package]" lines add "npm
update" / "npm update [package]" and "pnpm update" / "pnpm update [package]";
for "yarn add" and dev deps add "npm install <pkg>@<version> --save" and "npm
install --save-dev <pkg>@<version>" plus "pnpm add <pkg>@<version>" and "pnpm
add -D <pkg>@<version>" so all examples (headings/commands in this file) show
equivalent commands for npm, yarn, and pnpm.
In `@docs/pro/home-pro.md`:
- Line 3: Update the opening sentence in docs/pro/home-pro.md so it doesn't
undersell React 19: replace the explicit "Now supports React 18" phrasing with a
version-consistent statement (e.g., "Now supports React 18 and 19" or "Now
supports React 18/19") to match later references to React 18/19 and the rest of
the page; ensure the linked CHANGELOG and loadable-components instructions
remain unchanged.
In `@docs/pro/installation.md`:
- Line 101: Update the prerequisite sentence in docs/pro/installation.md to
state that react_on_rails must match the react_on_rails_pro version (not just be
≥16.0.0); reference that the gemspec uses s.add_runtime_dependency
"react_on_rails", ReactOnRails::VERSION (in react_on_rails_pro.gemspec) which
enforces an exact-version match, so clarify the docs to require the same version
(e.g., "react_on_rails must be the same version as react_on_rails_pro, such as
16.4.0").
In `@docs/pro/js-memory-leaks.md`:
- Around line 12-19: Move the useStaticRendering(true) call out of the App
component and invoke it once at module scope before the App component is defined
and before any observer components are imported or rendered; specifically, place
useStaticRendering(true) right after the import of useStaticRendering from
"mobx-react" (so it runs once on module load), and remove the call from inside
the App function to prevent it running on every render.
In `@docs/pro/react-server-components/create-without-ssr.md`:
- Around line 16-17: Remove installation of the base package and install only
the Pro package with an exact/pinned version: replace the yarn command to
install only react-on-rails-pro using the --exact flag (e.g., yarn add --exact
[email protected]) and replace the Bundler line to add only
react_on_rails_pro with a pinned version (e.g., bundle add react_on_rails_pro
--version '=4.0.0' or equivalent), removing react-on-rails from both commands.
In `@docs/pro/react-server-components/purpose-and-benefits.md`:
- Around line 153-173: The snippet is incomplete and mixes module formats:
ensure imports/definitions for serverWebpackConfig, extractLoader, and rules are
present and the module syntax matches the .mjs extension; specifically, replace
any CommonJS require() with ES module imports for serverWebpackConfig and other
helpers, define rules as rscConfig.module.rules (or const rules =
rscConfig.module?.rules || []), and add an extractLoader helper function (e.g.,
function extractLoader(rule, name){ return Array.isArray(rule.use) ?
rule.use.find(l=> (l.loader||'').includes(name)) : null }) so the logic that
finds babel-loader and pushes the react-on-rails-rsc/WebpackLoader operates
correctly; also keep rscConfig.entry assignment unchanged to map 'rsc-bundle' to
rscConfig.entry['server-bundle'].
In `@llms.txt`:
- Line 24: The docs show the generator command "rails generate
react_on_rails:install" but don't state whether the react_on_rails gem must be
added first, causing inconsistency with the Pro sections; update the
installation instructions to either add a preceding step to run "bundle add
react_on_rails" (or ensure Gemfile has gem 'react_on_rails') before the "rails
generate react_on_rails:install" line, or insert a short clarifying note stating
that the generator will install the gem automatically—make the choice consistent
with the Pro instructions and mention "rails generate react_on_rails:install"
and the "react_on_rails" gem explicitly.
In `@README.md`:
- Around line 203-204: Update the documented minimum runtime versions in the
README where it currently reads "Ruby >= 3.2" and "Node.js >= 20" to match the
package/runtime validator floors ("Ruby >= 3.0" and "Node.js >= 18"); keep the
CI-tested ranges (e.g., "CI tested: 3.2 - 3.4" and "CI tested: 20 - 22") as
separate notes rather than changing the minimums so documentation reflects
supported floors used by runtime/package validators.
---
Nitpick comments:
In
`@docs/oss/building-features/how-to-conditionally-server-render-based-on-device-type.md`:
- Line 30: Replace the repository blob URL
'https://github.com/shakacode/react_on_rails/blob/main/docs/configuration/README.md'
in this file with the canonical docs URL
'https://reactonrails.com/docs/configuration/' so the link matches the nearby
canonical link and avoids split-link maintenance; update any identical
occurrences in the same file to the canonical URL to keep links consistent.
In `@docs/oss/building-features/node-renderer/basics.md`:
- Around line 46-51: The docs currently show only Yarn commands for installing
react-on-rails-pro-node-renderer; restore package-manager-agnostic installation
instructions by replacing the single Yarn block with three subsections (npm,
yarn, pnpm) that include the suggested commands: npm init -y and npm install
--save-exact react-on-rails-pro-node-renderer, yarn init and yarn add
react-on-rails-pro-node-renderer, and pnpm init and pnpm add --save-exact
react-on-rails-pro-node-renderer so the documentation once again covers npm,
yarn, and pnpm for the package installation step.
In `@docs/oss/building-features/node-renderer/debugging.md`:
- Around line 17-24: The steps in debugging.md are yarn-specific; update the
instructions to be package-manager-agnostic by adding equivalent npm and pnpm
command alternatives for each yarn command (e.g., for `yarn` add `npm
install`/`pnpm install`, for `yarn build:dev` add `npm run build:dev`/`pnpm run
build:dev`, for `yarn start` add `npm start`/`pnpm start`) and mention the same
environment variable usage (`RENDERER_LOG_LEVEL=debug`) works with
Windows-compatible syntax when needed; alternatively, if this workflow is
intended only for repo maintainers, explicitly label the file as maintainer-only
and keep the yarn examples but add a short note referencing the nps task `nps
renderer.debug` and the `spec/dummy/package.json` script `"node-renderer-debug"`
so readers know where to find the exact commands.
In `@docs/oss/building-features/node-renderer/js-configuration.md`:
- Line 97: The docs currently only show "yarn start"; update the end-user
instruction to be package-manager-agnostic by adding the npm and pnpm
equivalents alongside the existing yarn command (e.g., include "npm run start"
and "pnpm start") so users of any package manager can follow the same step;
locate the string "yarn start" in js-configuration.md and replace or expand it
to list all three commands.
In `@docs/oss/deployment/server-rendering-tips.md`:
- Line 17: Replace the generic wiki link in the sentence "You can enable Node.js
server rendering via [React on Rails Pro]" with a direct React on Rails Pro
documentation URL that specifically covers the Node renderer or the Pro overview
(i.e., point the link target to the React on Rails Pro Node renderer/Pro
overview doc in the react_on_rails docs rather than the wiki landing page) so
users land directly on the actionable Pro documentation.
In `@docs/oss/getting-started/pro-quick-start.md`:
- Around line 43-50: Update the docs fragment that currently shows only Yarn
commands under the heading "## Step 4: Commit (required by generator)" by
replacing that heading with "## Step 4: Init node application (if needed)" and
adding package-manager-agnostic init commands for npm and pnpm alongside the
existing yarn init (npm init -y, yarn init -y, pnpm init). Insert a brief
conditional note "If you don't have a package.json yet:" above the three init
commands, then renumber the subsequent heading ("## Step 5: Commit (required by
generator)") and any following step references accordingly to reflect the new
step ordering; target the block containing the yarn init/yarn add lines and the
heading text to make these edits.
In `@docs/oss/migrating/rsc-preparing-app.md`:
- Line 507: The example uses product.as_json(include: [:specs, :reviews]) which
encourages broad serialization; change it to explicitly whitelist fields (e.g.,
use product.as_json(only: [...], include: { specs: { only: [...] }, reviews: {
only: [...] } })) so the props payload is limited and predictable; update the
props line (props: { product: ... }) to use as_json with only: and nested
include-only shapes instead of a bare include: list for both occurrences.
In `@docs/pro/react-on-rails-pro.md`:
- Line 19: The document currently uses an H3 heading "### Pro: Docs" directly
under the H1 title; update the markdown to restore proper heading hierarchy by
either changing that heading text "### Pro: Docs" to an H2 ("## Pro: Docs") or
by adding an H2 wrapper (for example add "## Features" or similar above the
existing H3 and keep the "### Pro: Docs" as a subsection); locate the heading
string "Pro: Docs" in the file and apply one of these two fixes consistently for
other subsections if present.
In `@docs/pro/react-server-components/create-without-ssr.md`:
- Around line 16-23: Update the install commands in
docs/pro/react-server-components/create-without-ssr.md so that the existing Yarn
lines (e.g., "yarn add [email protected] [email protected]"
and "yarn add [email protected] [email protected] [email protected]") are
followed by equivalent npm and pnpm alternatives (use --save-exact or --save
where appropriate for npm and --exact for pnpm) so users see three options
(yarn, npm, pnpm) for each installation step.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: cdb7e3d4-4cf1-43c1-9c54-6b3773fa71c2
📒 Files selected for processing (69)
AGENTS_USER_GUIDE.mdREADME.mddocs/README.mddocs/oss/api-reference/generator-details.mddocs/oss/api-reference/redux-store-api.mddocs/oss/api-reference/ruby-api-pro.mddocs/oss/api-reference/view-helpers-api.mddocs/oss/building-features/bundle-caching.mddocs/oss/building-features/caching.mddocs/oss/building-features/code-splitting.mddocs/oss/building-features/extensible-precompile-pattern.mddocs/oss/building-features/how-to-conditionally-server-render-based-on-device-type.mddocs/oss/building-features/i18n.mddocs/oss/building-features/images.mddocs/oss/building-features/node-renderer/basics.mddocs/oss/building-features/node-renderer/debugging.mddocs/oss/building-features/node-renderer/error-reporting-and-tracing.mddocs/oss/building-features/node-renderer/heroku.mddocs/oss/building-features/node-renderer/js-configuration.mddocs/oss/building-features/node-renderer/troubleshooting.mddocs/oss/building-features/rails-webpacker-react-integration-options.mddocs/oss/building-features/testing-configuration.mddocs/oss/building-features/turbolinks.mddocs/oss/configuration/README.mddocs/oss/configuration/configuration-pro.mddocs/oss/core-concepts/client-vs-server-rendering.mddocs/oss/core-concepts/how-react-on-rails-works.mddocs/oss/core-concepts/react-server-rendering.mddocs/oss/core-concepts/render-functions-and-railscontext.mddocs/oss/deployment/README.mddocs/oss/deployment/capistrano-deployment.mddocs/oss/deployment/elastic-beanstalk.mddocs/oss/deployment/server-rendering-tips.mddocs/oss/deployment/troubleshooting-build-errors.mddocs/oss/deployment/troubleshooting.mddocs/oss/getting-started/common-issues.mddocs/oss/getting-started/comparing-react-on-rails-to-alternatives.mddocs/oss/getting-started/comparison-with-alternatives.mddocs/oss/getting-started/create-react-on-rails-app.mddocs/oss/getting-started/installation-into-an-existing-rails-app.mddocs/oss/getting-started/oss-vs-pro.mddocs/oss/getting-started/pro-quick-start.mddocs/oss/getting-started/quick-start.mddocs/oss/getting-started/tutorial.mddocs/oss/introduction.mddocs/oss/migrating/migrating-to-rsc.mddocs/oss/migrating/rsc-component-patterns.mddocs/oss/migrating/rsc-context-and-state.mddocs/oss/migrating/rsc-data-fetching.mddocs/oss/migrating/rsc-preparing-app.mddocs/oss/migrating/rsc-third-party-libs.mddocs/oss/migrating/rsc-troubleshooting.mddocs/oss/misc/style.mddocs/oss/misc/updating-dependencies.mddocs/oss/upgrading/release-notes/16.1.0.mddocs/oss/upgrading/release-notes/16.2.0.mddocs/oss/upgrading/upgrading-react-on-rails.mddocs/pro/home-pro.mddocs/pro/installation.mddocs/pro/js-memory-leaks.mddocs/pro/profiling-server-side-rendering-code.mddocs/pro/react-on-rails-pro.mddocs/pro/react-server-components/create-without-ssr.mddocs/pro/react-server-components/purpose-and-benefits.mddocs/pro/react-server-components/tutorial.mddocs/pro/troubleshooting.mddocs/pro/updating.mdinternal/contributor-info/create-react-on-rails-app-smoke-testing.mdllms.txt
💤 Files with no reviewable changes (3)
- docs/pro/react-server-components/tutorial.md
- docs/oss/core-concepts/render-functions-and-railscontext.md
- docs/oss/migrating/rsc-third-party-libs.md
| ruby -v # Should be 3.2+ | ||
| node -v # Should be 20+ |
There was a problem hiding this comment.
Use validator-floor minimums here, not CI-floor minimums.
Line 35 and Line 36 currently encode Ruby 3.2+ and Node 20+ as strict prerequisites, which can cause agents to recommend unnecessary upgrades for environments that are still supported.
Suggested doc fix
- ruby -v # Should be 3.2+
- node -v # Should be 20+
+ ruby -v # Should be 3.0+ (CI tested: 3.2 - 3.4)
+ node -v # Should be 18+ (CI tested: 20 - 22)Based on learnings: In README and related docs, Ruby >= 3.0 and Node >= 18 are intentional support floors, with CI-tested ranges documented separately.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@AGENTS_USER_GUIDE.md` around lines 35 - 36, The docs currently list strict
prerequisites "ruby -v # Should be 3.2+" and "node -v # Should be 20+"
which use CI-floor minimums; update these validator-floor minimums to "Ruby >=
3.0" and "Node >= 18" instead (replace the version comments next to the "ruby
-v" and "node -v" lines accordingly) so the AGENTS_USER_GUIDE reflects supported
floors rather than CI-tested floors.
| - Add `gem 'react_on_rails_pro', '>= 16.3.0'` to your Gemfile and run `bundle install` | ||
| - Contact [[email protected]](mailto:[email protected]) for a license | ||
|
|
There was a problem hiding this comment.
Clarify license wording so install prerequisites don’t imply a paid key is required for local usage.
Line 213 reads like a prerequisite for setup, but Pro evaluation/development/testing/CI flows do not require a production paid license.
Based on learnings: In React on Rails Pro, a license is NOT required for evaluation, development, testing, or CI; only production requires REACT_ON_RAILS_PRO_LICENSE.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/oss/api-reference/generator-details.md` around lines 212 - 214, The
current install note ("Add `gem 'react_on_rails_pro', '>= 16.3.0'` ... Contact
[email protected] for a license") implies a paid license is required to run
locally; update the wording to clarify that adding the gem is optional for Pro
features but a production license (REACT_ON_RAILS_PRO_LICENSE) is only required
for production deployments — evaluation, development, testing and CI do not
require a paid key — and keep the contact ([email protected]) as the channel
for obtaining a production license or questions; reference the Gemfile gem
declaration (`gem 'react_on_rails_pro', '>= 16.3.0'`) and the environment
variable name (`REACT_ON_RAILS_PRO_LICENSE`) so the change is applied to the
same explanatory bullet points.
| 2. Add `react-intl` & `intl` to your root `package.json`, and remember to run `bundle install` | ||
| and your package manager's install command (e.g., `npm install`, `yarn install`, or | ||
| `pnpm install`). The minimum supported versions are: | ||
| 2. Add `react-intl` & `intl` to `client/package.json`, and remember to run `bundle install` and your package manager's install command (e.g., `npm install`, `yarn install`, or `pnpm install`). The minimum supported versions are: |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check where package.json files exist in React on Rails example projects
# Check the spec dummy app structure
echo "=== Spec dummy app package.json locations ==="
fd -t f "package.json" react_on_rails/spec/dummy/ 2>/dev/null | head -10
# Check React on Rails tutorial structure
echo -e "\n=== Common React on Rails project structures in docs ==="
rg -n "package\.json" docs/oss/ -C2 | grep -E "(client/|root)" | head -20Repository: shakacode/react_on_rails
Length of output: 1297
🏁 Script executed:
cat -n docs/oss/building-features/i18n.md | sed -n '130,155p'Repository: shakacode/react_on_rails
Length of output: 1090
🏁 Script executed:
# Check if there's documentation about project structure setup
rg -n "package\.json" docs/oss/getting-started/ -A2 -B2 | head -30Repository: shakacode/react_on_rails
Length of output: 1042
🏁 Script executed:
# Check for any client/ directory structure in modern examples
fd -type d "client" react_on_rails/spec/dummy/ 2>/dev/null
fd -type d "client" react_on_rails/spec/ 2>/dev/null | head -5Repository: shakacode/react_on_rails
Length of output: 50
🏁 Script executed:
# Search for any references to why client/ directory exists or should exist
rg -n "client.*(directory|structure|subdirectory)" docs/oss/ -i
# Check if any setup instructions recommend creating a client/ directory
rg -n "mkdir.*client|create.*client" docs/oss/ -iRepository: shakacode/react_on_rails
Length of output: 15463
🏁 Script executed:
# Look at the upgrading docs more carefully to understand the client directory deprecation
cat -n docs/oss/upgrading/upgrading-react-on-rails.md | sed -n '420,435p'Repository: shakacode/react_on_rails
Length of output: 860
🏁 Script executed:
# Check if any current example or setup instructions reference client/package.json as the primary approach
rg -n "client/package\.json" docs/oss/ | wc -l
rg -n "^[^#]*package\.json" docs/oss/ --no-filename | grep -v client | head -5Repository: shakacode/react_on_rails
Length of output: 979
Update i18n.md guidance to be universally compatible with both modern and legacy project structures.
The documented instruction to add dependencies to client/package.json is overly specific. While valid for legacy React on Rails setups that retained the /client directory, this is not the default or recommended structure in modern React on Rails projects. The spec/dummy canonical app and Shakapacker (the modern default) use a root-level package.json. The /client directory is optional and explicitly documented as a legacy structure in the upgrading guides.
Recommend reverting to the original wording: "Add react-intl & intl to your package.json" (without specifying client/) so the guidance works universally across both modern and legacy project structures.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/oss/building-features/i18n.md` at line 139, The docs line currently
instructs adding dependencies to "client/package.json", which is too specific;
update the phrase in docs/oss/building-features/i18n.md (the line containing
"Add `react-intl` & `intl` to `client/package.json`") to the more general
wording "Add `react-intl` & `intl` to your `package.json`" so the guidance
applies to both modern (root-level package.json) and legacy (client/) project
structures.
| **images** is a defined alias, so "images/foobar.jpg" would point to the file at | ||
| `/client/app/assets/images/foobar.jpg.` | ||
|
|
||
| ```javascript | ||
| resolve: { | ||
| resolve: { | ||
| alias: { | ||
| images: join(process.cwd(), 'app', 'javascript', 'images'), | ||
| images: join(process.cwd(), 'app', 'assets', 'images'), | ||
| }, |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify whether an `images` alias is actually defined in shipped webpack configs/templates/docs.
set -euo pipefail
echo "== Find webpack config files and templates =="
fd -i 'webpack' .
echo
echo "== Search for alias declarations involving images =="
rg -n --iglob '*webpack*' --iglob '*.mjs' --iglob '*.js' --iglob '*.ts' "alias|images\\s*:" .
echo
echo "== Search docs for statements about default images alias behavior =="
rg -n "images\\s+is\\s+a\\s+defined alias|does not define an `images` alias|app/assets/images|app/javascript/images" docsRepository: shakacode/react_on_rails
Length of output: 50445
🏁 Script executed:
cat -n ./react_on_rails/spec/dummy/config/webpack/alias.jsRepository: shakacode/react_on_rails
Length of output: 1034
🏁 Script executed:
cat -n ./react_on_rails_pro/spec/dummy/config/webpack/alias.jsRepository: shakacode/react_on_rails
Length of output: 1034
🏁 Script executed:
# Check the templates for alias definitions
find ./react_on_rails/lib/generators -name "alias.js*" -o -name "*alias*" | grep -E '\.(js|ts)' | head -20Repository: shakacode/react_on_rails
Length of output: 50
🏁 Script executed:
# Search for alias definitions in generator templates
rg -l "alias" ./react_on_rails/lib/generators/react_on_rails/templates --type js --type tsRepository: shakacode/react_on_rails
Length of output: 50
🏁 Script executed:
# Read the full images.md file to see the context around lines 37-44
cat -n ./docs/oss/building-features/images.mdRepository: shakacode/react_on_rails
Length of output: 1702
🏁 Script executed:
# Check if there are any alias.js or similar files in the generator templates
fd -i "alias" ./react_on_rails/lib/generators/react_on_rails/templates/Repository: shakacode/react_on_rails
Length of output: 50
🏁 Script executed:
# Search for "images" in all template webpack config files
rg "images" ./react_on_rails/lib/generators/react_on_rails/templates --type js --type ts -A 2 -B 2Repository: shakacode/react_on_rails
Length of output: 50
🏁 Script executed:
# List all webpack template files
find ./react_on_rails/lib/generators/react_on_rails/templates -name "*webpack*" -type f | head -20Repository: shakacode/react_on_rails
Length of output: 273
🏁 Script executed:
# Check the commonWebpackConfig template file for any alias definition
cat -n ./react_on_rails/lib/generators/react_on_rails/templates/base/base/config/webpack/commonWebpackConfig.js.ttRepository: shakacode/react_on_rails
Length of output: 857
🏁 Script executed:
# Check if there's any other webpack config in templates that might define images alias
find ./react_on_rails/lib/generators/react_on_rails/templates -name "*.tt" -o -name "*.js" -o -name "*.ts" | xargs grep -l "images.*alias\|alias.*images" 2>/dev/nullRepository: shakacode/react_on_rails
Length of output: 52
Remove or correct the false "images is a defined alias" claim to prevent broken imports.
The statement on line 37 that "images is a defined alias" is factually incorrect. The code snippet shown (lines 41-45) is an example configuration, not confirmation the alias exists by default. Default webpack configs in the repository—including react_on_rails/spec/dummy/config/webpack/alias.js, react_on_rails_pro/spec/dummy/config/webpack/alias.js, and the template commonWebpackConfig.js.tt—define only React and Assets aliases, not an images alias. Users following this documentation will encounter build-time import failures.
Either clarify that this configuration is optional and must be added by developers, or remove the misleading claim.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/oss/building-features/images.md` around lines 37 - 44, The documentation
wrongly asserts that the "images" alias exists by default; update the text
around the resolve.alias snippet to state that this is an example showing how to
add an alias (not a built-in), e.g. explain that users must add the
resolve.alias entry (images -> join(process.cwd(), 'app','assets','images')) to
their webpack config if they want to import "images/..." paths, or remove the
claim entirely so it no longer implies a default alias exists. Ensure you
reference the resolve: { alias: { images: join(process.cwd(), 'app', 'assets',
'images') } } example and clarify it is optional user configuration.
| import path from 'path'; | ||
| import { reactOnRailsProNodeRenderer } from 'react-on-rails-pro-node-renderer'; | ||
|
|
||
| const config = { | ||
| // Save bundles to relative "./.node-renderer-bundles" dir of our app root | ||
| serverBundleCachePath: path.resolve(__dirname, '../.node-renderer-bundles'), | ||
| // Save bundles to relative "./.node-renderer-bundles" dir of our app | ||
| serverBundleCachePath: path.resolve(__dirname, './.node-renderer-bundles'), | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
In Node.js ES modules, is __dirnameavailable by default? What is the recommended replacement pattern usingimport.meta.url?
💡 Result:
No, dirname is not available by default in Node.js ES modules. It is a CommonJS-specific variable and unavailable in ESM. The recommended replacement uses import.meta.url to derive the directory path. Prior to Node.js v20.11.0 / v21.2.0, the pattern was: import { fileURLToPath } from 'node:url'; import { dirname } from 'node:path'; const filename = fileURLToPath(import.meta.url); const dirname = dirname(filename); Since Node.js v20.11.0 (stable in v22.16.0+ / v24.0.0+), use the built-in import.meta.dirname directly: const dirname = import.meta.dirname; This is equivalent to path.dirname(import.meta.filename) and only available for file: modules. As of 2026-03-30, with Node.js v25+ current, this is the modern recommendation per official docs.
Citations:
- 1: https://nodejs.org/api/esm.html
- 2: https://www.sonarsource.com/blog/dirname-node-js-es-modules
- 3: https://stackoverflow.com/questions/46745014/alternative-for-dirname-in-node-js-when-using-es6-modules/65895043
- 4: esm: add import.meta.dirname and import.meta.filename nodejs/node#48740
🏁 Script executed:
# Find and read the file mentioned in the review
fd -t f "js-configuration.md" --exec head -n 80 {} \;Repository: shakacode/react_on_rails
Length of output: 7945
🏁 Script executed:
# Check project's Node.js version requirement
fd -t f "package.json" | head -20 | xargs -I {} sh -c 'echo "File: {}" && cat {} | jq ".engines.node // .volta.node // .nvmrc // empty" 2>/dev/null || true'Repository: shakacode/react_on_rails
Length of output: 1398
🏁 Script executed:
# Also check for .nvmrc or Node version config files
fd -E node_modules -t f "\.(nvmrc|nvmrc|node-version)$|package\.json$" | grep -E "(nvmrc|node-version)" | head -5Repository: shakacode/react_on_rails
Length of output: 104
🏁 Script executed:
# Check the main project's package.json for Node.js engine requirement
cat packages/react-on-rails/package.json | jq '.engines'Repository: shakacode/react_on_rails
Length of output: 72
🏁 Script executed:
# Also check the react_on_rails_pro dummy app's .nvmrc for the actual Node version
cat react_on_rails_pro/spec/dummy/.nvmrcRepository: shakacode/react_on_rails
Length of output: 76
Fix ESM example: __dirname is undefined in this snippet.
Line 65 uses ESM (import ...), but line 70 references __dirname, which is not available in Node.js ES modules and will throw at runtime.
Since the project targets Node.js v22.12.0, use the modern import.meta.dirname pattern:
Suggested doc fix
import path from 'path';
import { reactOnRailsProNodeRenderer } from 'react-on-rails-pro-node-renderer';
const config = {
// Save bundles to relative "./.node-renderer-bundles" dir of our app
- serverBundleCachePath: path.resolve(__dirname, './.node-renderer-bundles'),
+ serverBundleCachePath: path.resolve(import.meta.dirname, './.node-renderer-bundles'),🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/oss/building-features/node-renderer/js-configuration.md` around lines 65
- 71, The snippet uses ESM imports but still references __dirname (used in
serverBundleCachePath via path.resolve), which is undefined in ES modules;
update the example to derive __dirname from import.meta.url (e.g., using
fileURLToPath(import.meta.url) and path.dirname) or use new URL-based dirname
resolution so serverBundleCachePath is computed from a valid directory value
when using the reactOnRailsProNodeRenderer example and path.resolve.
| import { useStaticRendering } from "mobx-react"; | ||
|
|
||
| **Fix:** Register listeners once (outside the render path), or guard with a flag: | ||
| const App = (props, railsContext) => { | ||
| const { location, serverSide } = railsContext; | ||
| const context = {}; | ||
|
|
||
| ```javascript | ||
| let listenerRegistered = false; | ||
| if (!listenerRegistered) { | ||
| process.on('unhandledRejection', (err) => reportError(err)); | ||
| listenerRegistered = true; | ||
| } | ||
| useStaticRendering(true); | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
What is the correct usage pattern for mobx-react useStaticRendering in server-side rendering?
💡 Result:
The correct usage pattern for useStaticRendering (also referred to as enableStaticRendering in modern versions) from mobx-react or mobx-react-lite in server-side rendering (SSR) is to call it with true on the server before rendering any observer-wrapped components, and optionally with false on the client after hydration if needed. This prevents MobX observers from subscribing to observables during SSR (to avoid memory leaks and unnecessary re-renders) and ensures proper cleanup after the initial render. Key points: - Import from mobx-react or mobx-react-lite: import { enableStaticRendering } from 'mobx-react-lite' - Call once at app/module level, typically in a way that distinguishes server from client: enableStaticRendering(typeof window === 'undefined') - Do this before any observer components render during SSR. - Purpose: Disables reactive subscriptions in SSR context; components render statically once. Example (common in Next.js _app.js or server entry): import { enableStaticRendering } from 'mobx-react-lite' enableStaticRendering(typeof window === 'undefined') This pattern is confirmed across official MobX docs, npm package README, and GitHub issues/PRs up to 2025-2026.
Citations:
- 1: https://mobx.js.org/react-integration.html
- 2: https://mobx.js.org/react-integration
- 3: https://www.npmjs.com/package/mobx-react-lite
- 4: mobx-react-lite component wrapped in
observerrenders twice in latest Next.js mobxjs/mobx#3826 - 5: https://dev.to/ivandotv/mobx-server-side-rendering-with-next-js-4m18
- 6: https://dev.to/maximlogunov/how-to-properly-initialize-mobx-store-in-react-applications-with-ssr-55ek
- 7: https://www.mtib.gov.my
- 8: https://www.egghead.io
🏁 Script executed:
# Check if the file exists and read the relevant section
if [ -f "docs/pro/js-memory-leaks.md" ]; then
echo "=== File found, reading lines 8-25 ==="
sed -n '8,25p' docs/pro/js-memory-leaks.md
else
echo "File not found at docs/pro/js-memory-leaks.md"
# Try to find similar files
find . -name "*memory*" -type f | head -20
fiRepository: shakacode/react_on_rails
Length of output: 448
🏁 Script executed:
# Search for useStaticRendering references in the codebase
rg -i "usestaticrendering|enablestaticrendering" --type md --type js --type tsRepository: shakacode/react_on_rails
Length of output: 344
Move useStaticRendering(true) to module level before the App component.
The code example calls useStaticRendering(true) inside the App component, which means it runs on every render. According to MobX SSR documentation, it should be called once at module level before any observer components render.
🔧 Suggested fix
import { useStaticRendering } from "mobx-react";
+// Call once at module level for SSR
+useStaticRendering(true);
+
const App = (props, railsContext) => {
const { location, serverSide } = railsContext;
const context = {};
-
- useStaticRendering(true);🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/pro/js-memory-leaks.md` around lines 12 - 19, Move the
useStaticRendering(true) call out of the App component and invoke it once at
module scope before the App component is defined and before any observer
components are imported or rendered; specifically, place
useStaticRendering(true) right after the import of useStaticRendering from
"mobx-react" (so it runs once on module load), and remove the call from inside
the App function to prevent it running on every render.
| yarn add [email protected] [email protected] | ||
| bundle add [email protected] [email protected] |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, locate and read the file to see the full context
cat -n docs/pro/react-server-components/create-without-ssr.mdRepository: shakacode/react_on_rails
Length of output: 20407
Install only react-on-rails-pro in Pro projects; it already includes base package functionality.
Line 16 should not install both react-on-rails and react-on-rails-pro. Pro setups must install only react-on-rails-pro and use the --exact flag to pin the version.
Suggested doc fix
- yarn add [email protected] [email protected]
+ yarn add --exact [email protected]📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| yarn add [email protected] [email protected] | |
| bundle add [email protected].2 [email protected] | |
| yarn add --exact [email protected] | |
| bundle add [email protected].2 [email protected] |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/pro/react-server-components/create-without-ssr.md` around lines 16 - 17,
Remove installation of the base package and install only the Pro package with an
exact/pinned version: replace the yarn command to install only
react-on-rails-pro using the --exact flag (e.g., yarn add --exact
[email protected]) and replace the Bundler line to add only
react_on_rails_pro with a pinned version (e.g., bundle add react_on_rails_pro
--version '=4.0.0' or equivalent), removing react-on-rails from both commands.
| ```javascript | ||
| // config/webpack/rscWebpackConfig.mjs | ||
| const rscConfig = serverWebpackConfig(); | ||
|
|
||
| // Configure RSC entry point | ||
| rscConfig.entry = { | ||
| 'rsc-bundle': rscConfig.entry['server-bundle'], | ||
| }; | ||
|
|
||
| // Add RSC loader | ||
| rules.forEach((rule) => { | ||
| if (Array.isArray(rule.use)) { | ||
| const babelLoader = extractLoader(rule, 'babel-loader'); | ||
| if (babelLoader) { | ||
| rule.use.push({ | ||
| loader: 'react-on-rails-rsc/WebpackLoader', | ||
| }); | ||
| } | ||
| } | ||
| }); | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Locate canonical examples that define these identifiers so the doc snippet can be completed accurately.
set -euo pipefail
echo "== Find occurrences of referenced identifiers =="
rg -n "serverWebpackConfig\\(|extractLoader\\(|rules\\.forEach\\(" docs react_on_rails react_on_rails_pro packages
echo
echo "== Find existing rscWebpackConfig examples =="
rg -n "rscWebpackConfig" docs react_on_rails react_on_rails_proRepository: shakacode/react_on_rails
Length of output: 14537
🏁 Script executed:
#!/bin/bash
# View full context around the example in purpose-and-benefits.md
echo "=== Full context in purpose-and-benefits.md (lines 140-180) ==="
sed -n '140,180p' docs/pro/react-server-components/purpose-and-benefits.md
echo
echo "=== Full context in create-without-ssr.md (lines 64-110) for comparison ==="
sed -n '64,110p' docs/pro/react-server-components/create-without-ssr.mdRepository: shakacode/react_on_rails
Length of output: 2883
Webpack RSC configuration example is incomplete and non-runnable.
The snippet references serverWebpackConfig, rules, and extractLoader without providing their definitions or imports. Include the required imports, the extractLoader helper function definition, and the rules variable declaration. See docs/pro/react-server-components/create-without-ssr.md for a complete working example.
Additionally, the file extension .mjs suggests ES modules, but the code uses CommonJS require() syntax—ensure consistency.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/pro/react-server-components/purpose-and-benefits.md` around lines 153 -
173, The snippet is incomplete and mixes module formats: ensure
imports/definitions for serverWebpackConfig, extractLoader, and rules are
present and the module syntax matches the .mjs extension; specifically, replace
any CommonJS require() with ES module imports for serverWebpackConfig and other
helpers, define rules as rscConfig.module.rules (or const rules =
rscConfig.module?.rules || []), and add an extractLoader helper function (e.g.,
function extractLoader(rule, name){ return Array.isArray(rule.use) ?
rule.use.find(l=> (l.loader||'').includes(name)) : null }) so the logic that
finds babel-loader and pushes the react-on-rails-rsc/WebpackLoader operates
correctly; also keep rscConfig.entry assignment unchanged to map 'rsc-bundle' to
rscConfig.entry['server-bundle'].
| ```bash | ||
| bundle add react_on_rails --strict | ||
| bundle exec rails generate react_on_rails:install | ||
| rails generate react_on_rails:install |
There was a problem hiding this comment.
Clarify whether gem installation is needed before running the generator.
The base install instructions show only the generator command, while both Pro install sections (lines 29 and 35) explicitly include bundle add react_on_rails_pro before the generator. This asymmetry may confuse users about whether they need to manually add the react_on_rails gem to their Gemfile before running rails generate react_on_rails:install.
Consider either:
- Adding
bundle add react_on_railsbefore line 24 for consistency, OR - Adding a brief note explaining that the generator handles gem installation automatically (if that's the case), OR
- Adding a prerequisite note that users should have
gem 'react_on_rails'in their Gemfile before running the generator
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@llms.txt` at line 24, The docs show the generator command "rails generate
react_on_rails:install" but don't state whether the react_on_rails gem must be
added first, causing inconsistency with the Pro sections; update the
installation instructions to either add a preceding step to run "bundle add
react_on_rails" (or ensure Gemfile has gem 'react_on_rails') before the "rails
generate react_on_rails:install" line, or insert a short clarifying note stating
that the generator will install the gem automatically—make the choice consistent
with the Pro instructions and mention "rails generate react_on_rails:install"
and the "react_on_rails" gem explicitly.
| - Ruby >= 3.2 (CI tested: 3.2 - 3.4) | ||
| - Node.js >= 20 (CI tested: 20 - 22) |
There was a problem hiding this comment.
Keep documented minimum versions aligned with runtime validator floors.
Line 203 and Line 204 now document Ruby >= 3.2 and Node.js >= 20, which conflicts with the intentional support floors used by package/runtime checks. This can incorrectly tell users their valid environments are unsupported.
Suggested doc fix
-- Ruby >= 3.2 (CI tested: 3.2 - 3.4)
-- Node.js >= 20 (CI tested: 20 - 22)
+- Ruby >= 3.0 (package minimum; CI tested: 3.2 - 3.4)
+- Node.js >= 18 (package minimum; CI tested: 20 - 22)Based on learnings: In README.md and related docs, Ruby >= 3.0 and Node >= 18 are intentional package-validator floors, while CI-tested ranges are documented separately.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` around lines 203 - 204, Update the documented minimum runtime
versions in the README where it currently reads "Ruby >= 3.2" and "Node.js >=
20" to match the package/runtime validator floors ("Ruby >= 3.0" and "Node.js >=
18"); keep the CI-tested ranges (e.g., "CI tested: 3.2 - 3.4" and "CI tested: 20
- 22") as separate notes rather than changing the minimums so documentation
reflects supported floors used by runtime/package validators.
|
Need to start over on this stuff. |
1 participant
Summary
Scope
docs/**README.mdAGENTS_USER_GUIDE.mdinternal/contributor-info/create-react-on-rails-app-smoke-testing.mdanalysis/open-issue-deep-dive/wave-3-long-tail.mdllms.txtTesting
Note
Low Risk
Documentation-only changes, but they update stated prerequisites and Pro/Node Renderer setup guidance, so incorrect edits could mislead users during installs or upgrades.
Overview
Updates docs across the repo to refresh prerequisites and Pro references, including bumping recommended minimums to Ruby 3.2 / Node 20 and standardizing many Pro links to
pro.reactonrails.com/reactonrails.com/pro.Reworks several guides for clarity and focus: adds a new Pro quick-start-from-scratch walkthrough, trims/rewrites sections in the alternatives comparison and RSC migration docs, and adjusts generator/install notes (e.g., React 19.0.x requirement and gem version constraints).
Restructures deployment documentation by simplifying
docs/oss/deployment/README.mdand re-adding archived deployment pages (capistrano-deployment.md,elastic-beanstalk.md), plus multiple Node Renderer doc edits (Heroku, debugging, JS config) that change recommended commands and defaults.Written by Cursor Bugbot for commit 085e515. This will update automatically on new commits. Configure here.
Summary by CodeRabbit
Documentation
Chores