Tighten migration preflights from validation runs

Author: justin808

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

@@ -6,6 +6,9 @@ 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"`.
+- 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

@@ -2,13 +2,18 @@
 
 This migration is easiest when the app is already on a modern Rails + Shakapacker baseline.
 
+If your `react-rails` app uses Vite or another non-Shakapacker asset setup, use this page for the helper and registration changes, but follow [Migrate from `vite_rails`](./migrating-from-vite-rails.md) for the asset-pipeline and entrypoint steps.
+
 ## Preflight
 
 Before swapping gems, check these first:
 
 1. **Webpacker vs Shakapacker**: if the app still uses `webpacker`, migrate to `shakapacker` 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. **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.
+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"`.
+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.
 
@@ -19,11 +24,14 @@ bundle _2.3.26_ lock --update
 bundle _2.3.26_ install
 ```
 
+If the first failure is a native gem compile error, solve that before swapping to React on Rails. Typical examples are `nio4r` in older Rails/Webpacker apps and `pg` or `mysql2` in apps with older database adapters pinned in the lockfile.
+
 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. Run `bundle install` and your package manager's install command.
-   4. Commit changes.
+   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.
+   4. Run `bundle install` and your package manager's install command.
+   5. Commit changes.
 
 2. Run `rails g react_on_rails:install` but do not commit the change. `react_on_rails` installs node dependencies and also creates sample React component, Rails view/controller, and updates `config/routes.rb`.
 
@@ -60,6 +68,7 @@ then treat the migration as:
 1. Move from `webpacker` to `shakapacker`.
 2. If the app is still on Rails 5.1, upgrade Rails to 5.2+ before adding current `react_on_rails`.
 3. Remove `react_ujs`.
-4. Run the React on Rails install generator.
-5. Replace helper syntax and component registration.
-6. Review `bin/dev`, `config/shakapacker.yml`, and webpack config diffs before committing.
+4. Ensure the app can boot for generator execution (`config/database.yml`, initializer env vars, package manager metadata).
+5. Run the React on Rails install generator.
+6. Replace helper syntax and component registration.
+7. Review `bin/dev`, `config/shakapacker.yml`, and webpack config diffs before committing.

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

@@ -17,8 +17,10 @@ If your app is already happy with a Vite-only client-rendered setup, this migrat
 
 Before you start, make sure the current app still installs cleanly on the Ruby and Node versions you plan to use for the migration.
 
-- If `bundle install` fails on older native gems such as `pg`, `nio4r`, or `msgpack`, refresh those gems or use the Ruby version already pinned by the app before introducing React on Rails.
+- 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"`.
+- 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.
 
 Then inventory the Vite-specific pieces in your app:
@@ -46,6 +48,12 @@ 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:
+
+```bash
+npm pkg set packageManager="yarn@1.22.22"
+```
+
 The generator adds the React on Rails initializer, `bin/dev`, Shakapacker config, example routes, and the server bundle entrypoint.
 
 ## 2. Replace Vite layout tags
@@ -180,3 +188,5 @@ one reasonable React on Rails target is:
 - Turbo usage, if your app already uses it
 
 The migration is mostly about asset/build integration, mounting strategy, and optional SSR capability.
+
+One practical detail from real app migrations: if the generator fails while booting your app, treat that as an application preflight problem first, not a React on Rails problem. Missing `APP_URL`-style env vars or an absent `config/database.yml` can stop the migration before any React on Rails files are generated.

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

@@ -29,7 +29,10 @@ Before changing versions, check these first:
 2. **Bundler age**: legacy apps may have lockfiles created by Bundler 1.x. Those lockfiles can fail on modern Ruby before the React on Rails upgrade even starts.
 3. **Rails version**: current `react_on_rails` requires Rails 5.2+. Rails 5.1 apps need a Rails upgrade before they can bundle v16.
 4. **Asset stack**: if the app still uses `webpacker`, upgrade to `shakapacker` first.
-5. **Version pinning**: use exact gem and npm package versions for React on Rails-related packages. Avoid `^`, `~`, or `*`.
+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"`.
+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.
 
@@ -41,6 +44,8 @@ bundle lock --update
 bundle install
 ```
 
+If `bundle install` is failing even earlier on native gems, fix that baseline before upgrading React on Rails. Common examples from real upgrades are `pg` compile errors in older Postgres apps, `nio4r` failures in older Rails/Webpacker stacks, or `mysql2` linker issues on Homebrew/macOS setups.
+
 ## Upgrading Precompile Hooks for SSR + HMR
 
 If your app uses server-side rendering with HMR, Shakapacker commonly runs two webpack processes during development (client HMR and server watcher). In that setup, direct-command precompile hooks are more fragile because each process can trigger the hook.