Clarify Shakapacker package manager preflights

Author: justin808

docs/oss/getting-started/installation-into-an-existing-rails-app.md

@@ -7,7 +7,7 @@ Use this path when you already have a Rails application and want React on Rails
 - Rails 7+ is recommended. Rails 5.2+ can work, but Webpacker-era apps usually need an incremental upgrade first.
 - If your app still uses `webpacker`, expect this to be a two-step migration: move to `shakapacker`, then install React on Rails.
 - If `bundle install` is already failing on older native gems such as `pg`, `nio4r`, `mysql2`, or `msgpack`, fix that baseline first. React on Rails installation cannot get past a broken app bundle.
-- If your repo has a `yarn.lock` but no `"packageManager"` field in `package.json`, add one before introducing Shakapacker 9. Example: `"packageManager": "yarn@1.22.22"`.
+- If your repo has a `yarn.lock` but no `"packageManager"` field in `package.json`, add one before introducing Shakapacker 9. Example for Yarn Classic: `npm pkg set packageManager="yarn@1.22.22"` (or add the field manually). Use the version that matches your project's Yarn installation.
 - The install generator boots your app. Make sure `config/database.yml` exists and any required env vars for initializers are set before running `rails generate`.
 - If your app is Rails 5 API-only, first [convert it to a standard Rails app](../migrating/convert-rails-5-api-only-app.md).
 - Commit or stash your current work if you want the generated diff to be easier to review. The generator updates files like `bin/dev`, `config/shakapacker.yml`, routes, initializers, and sample views/controllers.

docs/oss/migrating/migrating-from-react-rails.md

@@ -12,7 +12,7 @@ Before swapping gems, check these first:
 2. **Bundler age**: some older `react-rails` apps still carry Bundler 1.x lockfiles. Those can fail on modern Ruby before you even reach the migration work.
 3. **Native gem age**: older lockfiles often pin `nio4r`, `pg`, or `mysql2` versions that fail to compile on current macOS and Ruby before the migration even starts.
 4. **App boot readiness**: the React on Rails install generator boots the full Rails app. Make sure `config/database.yml` exists and required env vars for initializers are set.
-5. **Package manager metadata**: if the repo has a `yarn.lock` but no `"packageManager"` field in `package.json`, add one before introducing Shakapacker 9. Example: `"packageManager": "yarn@1.22.22"`.
+5. **Package manager metadata**: if the repo has a `yarn.lock` but no `"packageManager"` field in `package.json`, add one before introducing Shakapacker 9. Example for Yarn Classic: `npm pkg set packageManager="yarn@1.22.22"` (or add the field manually). Use the version that matches your project's Yarn installation.
 6. **Rails age**: current `react_on_rails` requires Rails 5.2+. Rails 5.1 / Webpacker 3 apps are usually a staged migration, not a one-command migration.
 
 If you are already on `shakapacker` 7+ and React 18+, the migration is mostly about helper syntax, component registration, and generated defaults.
@@ -29,7 +29,7 @@ If the first failure is a native gem compile error, solve that before swapping t
 1. Update Deps
    1. Replace `react-rails` in `Gemfile` with `react_on_rails` and make sure `shakapacker` is present.
    2. Remove `react_ujs` from `package.json`.
-   3. If the repo uses Yarn and `package.json` does not already declare it, add `"packageManager": "yarn@1.22.22"` before booting the app with Shakapacker 9.
+   3. If the repo uses Yarn and `package.json` does not already declare it, add the package manager field before booting the app with Shakapacker 9: `npm pkg set packageManager="yarn@1.22.22"` (or add it manually to `package.json`). The example is for Yarn Classic; use the version that matches your project.
    4. Run `bundle install` and your package manager's install command.
    5. Commit changes.
 

docs/oss/migrating/migrating-from-vite-rails.md

@@ -19,7 +19,7 @@ Before you start, make sure the current app still installs cleanly on the Ruby a
 
 - If `bundle install` fails on older native gems such as `pg`, `nio4r`, `mysql2`, or `msgpack`, refresh those gems or use the Ruby version already pinned by the app before introducing React on Rails.
 - If the app has an older Bundler-era lockfile, refresh that lockfile first.
-- If the repo uses Yarn and has a `yarn.lock` but no `"packageManager"` field in `package.json`, add one before introducing Shakapacker 9. Example: `"packageManager": "yarn@1.22.22"`.
+- If the repo uses Yarn and has a `yarn.lock` but no `"packageManager"` field in `package.json`, add one before introducing Shakapacker 9. Example for Yarn Classic: `npm pkg set packageManager="yarn@1.22.22"` (or add the field manually). Use the version that matches your project's Yarn installation.
 - The React on Rails install generator boots the full app. Make sure `config/database.yml` exists and any required env vars for initializers are set before you run it.
 - Commit or stash your current work so the generator diff is easier to review.
 
@@ -45,18 +45,27 @@ For anything beyond a tiny app, prefer a route-by-route cutover instead of a big
 ```bash
 bundle add shakapacker --strict
 bundle add react_on_rails --strict
-bundle exec rails generate react_on_rails:install
 ```
 
-If you use Yarn and `package.json` does not already declare it, set the package manager before running the generator:
+## 2. Declare the package manager if needed
+
+If you use Yarn and `package.json` does not already declare it, set the package manager before running the generator. This only updates `package.json`; it does not install or switch Yarn for you.
 
 ```bash
 npm pkg set packageManager="yarn@1.22.22"
 ```
 
+If you prefer, add the same field manually in `package.json`. The example above is for Yarn Classic; use the version that matches your project.
+
+## 3. Run the generator
+
+```bash
+bundle exec rails generate react_on_rails:install
+```
+
 The generator adds the React on Rails initializer, `bin/dev`, Shakapacker config, example routes, and the server bundle entrypoint.
 
-## 2. Replace Vite layout tags
+## 4. Replace Vite layout tags
 
 A typical Vite layout looks like this:
 
@@ -76,7 +85,7 @@ React on Rails + Shakapacker layouts use pack tags instead:
 
 If you use React on Rails auto-bundling, keep those empty pack-tag placeholders in the layout and let React on Rails load component-specific bundles per page.
 
-## 3. Move frontend code into the React on Rails structure
+## 5. Move frontend code into the React on Rails structure
 
 A common Vite layout is:
 
@@ -101,7 +110,7 @@ For auto-bundling, move page-level components into a `ror_components` directory,
 app/javascript/src/Hero/ror_components/Hero.client.jsx
 ```
 
-## 4. Replace client bootstraps with Rails view rendering
+## 6. Replace client bootstraps with Rails view rendering
 
 Vite apps often mount React manually from an entrypoint:
 
@@ -117,7 +126,7 @@ With React on Rails, render the component from the Rails view instead:
 
 This is the key mental model shift: Rails decides where the component mounts, and React on Rails handles registration and hydration.
 
-## 5. Replace Vite-specific asset and env usage
+## 7. Replace Vite-specific asset and env usage
 
 ### `vite_asset_path`
 
@@ -135,7 +144,7 @@ Vite-specific `import.meta.env` usage needs to be replaced. In a React on Rails
 - Rails-passed props
 - `railsContext` for request-aware values
 
-## 6. Replace the development workflow
+## 8. Replace the development workflow
 
 Vite apps usually have a dev command like:
 
@@ -153,7 +162,7 @@ bin/rails db:prepare
 bin/dev
 ```
 
-## 7. Remove Vite once parity is confirmed
+## 9. Remove Vite once parity is confirmed
 
 After the new React on Rails entrypoints are working, remove:
 

docs/oss/upgrading/upgrading-react-on-rails.md

@@ -31,7 +31,7 @@ Before changing versions, check these first:
 4. **Asset stack**: if the app still uses `webpacker`, upgrade to `shakapacker` first.
 5. **Native gem age**: older `pg`, `nio4r`, `mysql2`, or `msgpack` versions can fail on current Ruby or macOS before the React on Rails upgrade even begins.
 6. **App boot readiness**: the install generator boots the full Rails app. Make sure `config/database.yml` exists and required env vars for initializers are set.
-7. **Package manager metadata**: if the repo has a `yarn.lock` but no `"packageManager"` field in `package.json`, add one before introducing Shakapacker 9. Example: `"packageManager": "yarn@1.22.22"`.
+7. **Package manager metadata**: if the repo has a `yarn.lock` but no `"packageManager"` field in `package.json`, add one before introducing Shakapacker 9. Example for Yarn Classic: `npm pkg set packageManager="yarn@1.22.22"` (or add the field manually). Use the version that matches your project's Yarn installation.
 8. **Version pinning**: use exact gem and npm package versions for React on Rails-related packages. Avoid `^`, `~`, or `*`.
 
 If your app is both Ruby/Bundler-old and Webpacker-old, do those upgrades first. Trying to jump directly from a Rails 5 / Webpacker 3 / Bundler 1 stack to current React on Rails is usually more than one migration.