[mirror] docs: add example migrations guide

docs/README.md

@@ -22,10 +22,10 @@ React on Rails is one product with two tiers: open source for Rails + React inte
 
 ### Evaluating Rails + React options
 
-- [Examples and migration references](https://reactonrails.com/examples)
+- [Example migrations](./oss/migrating/example-migrations.md) — curated migration references and proof criteria
+- [Examples gallery](https://reactonrails.com/examples) — reactonrails.com showcase apps
 - [Compare with alternatives](./oss/getting-started/comparing-react-on-rails-to-alternatives.md) — decision guide covering Hotwire, Inertia, Next.js, and more
 - [Migrate from react-rails](./oss/migrating/migrating-from-react-rails.md)
-- [Published migration example repo (Rails 7)](https://github.com/shakacode/react-on-rails-migration-example)
 
 ## Dive deeper when you need it
 

docs/oss/migrating/example-migrations.md

@@ -0,0 +1,138 @@
+# Example Migrations
+
+Teams evaluating React on Rails are usually not starting from a blank Rails app.
+
+They already have one of these:
+
+- `react-rails`
+- `vite_rails`
+- a custom Rails-side React helper
+
+Some teams also arrive from Inertia-first apps. We treat those as a separate
+architecture case study because they are usually broader page-shell migrations,
+not narrow React mount migrations. If that is your starting point, begin with
+[Compare with alternatives](../getting-started/comparing-react-on-rails-to-alternatives.md).
+
+This page tracks practical migration references for those cases.
+
+## What makes a useful migration example
+
+The best examples are:
+
+1. Real Rails applications, not toy demos
+2. Small PRs that convert one page, mount point, or component boundary
+3. Honest about blockers such as old lockfiles, native gems, or custom frontend bridges
+4. Measured with before-and-after performance or maintainability notes instead of marketing claims
+
+## Current public references
+
+### Published example repos
+
+These maintainer-owned references are the stable starting set. Add community
+examples here after they have landed or stabilized enough to inspect.
+
+1. [react-rails example app: `react-rails-to-react-on-rails` snapshot](https://github.com/shakacode/react-rails-example-app/tree/c6b794a4b96746dbbc98a46f31119171109d70b0) —
+   covers an older `react-rails` v3 → `react_on_rails` v13.4 migration, so treat
+   it as a structural reference and follow current migration guides for gem and
+   configuration specifics
+2. [react-on-rails-migration-example](https://github.com/shakacode/react-on-rails-migration-example) —
+   demonstrates a Rails 7-era `react-rails` → `react_on_rails` migration with
+   Shakapacker client/server bundles and SSR setup, based on
+   [ganchdev/react-rails-example](https://github.com/ganchdev/react-rails-example)
+
+### In-progress migration work
+
+In-progress third-party migration PRs are tracked in the
+[example-migrations meta issue](https://github.com/shakacode/react_on_rails/issues/3125)
+instead of this docs page.
+
+That keeps the public docs focused on durable references while the meta issue can
+carry working notes about draft PRs, maintainer coordination, blockers, and proof
+artifacts that may change quickly.
+
+When a public migration becomes a stable reference, add it to the published example
+list above with a short proof note.
+
+## Example categories
+
+### `react-rails` to React on Rails
+
+This is usually the cleanest migration path: primarily a gem swap and mount
+registration change while the app architecture stays intact during
+slice-by-slice conversion.
+
+### `vite_rails` to React on Rails
+
+This is more of an asset and entrypoint migration than a component rewrite: the
+route behavior should stay stable while registration moves into the React on
+Rails and Shakapacker flow.
+
+### Custom Rails React bridge to React on Rails
+
+This is common in mature apps that built a thin wrapper around React mounts.
+
+Treat the wrapper as the migration boundary: preserve the Rails-side props
+contract, replace one helper-backed component first, and remove the wrapper
+later.
+
+No dedicated guide exists yet. If your app uses this pattern and you want to
+contribute an example, see [Contribute an example](#contribute-an-example).
+The [react-rails migration guide](./migrating-from-react-rails.md) covers the
+nearest-neighbor mechanics for helper syntax and component registration.
+
+## What counts as proof
+
+Not every good migration example is performance-first.
+
+When the change is performance-first, compare the same route on the baseline branch and the migration branch. At minimum, record:
+
+1. Response timing
+2. HTML size
+3. Route JavaScript bytes
+4. Number of JS assets needed for the route
+5. Hydration warnings or client boot errors
+
+If possible, also record browser load metrics such as FCP, LCP, CLS, and TBT,
+plus interaction metrics such as INP. TBT is captured by Lighthouse; INP
+requires field data or a real-user monitoring tool.
+
+When the change is maintainability-first, record:
+
+1. The custom bridge, oversized mount, or repo-specific contract that existed before the migration
+2. The standardized React on Rails helper or smaller boundary that replaced it
+3. What got easier to review, test, or evolve afterward
+4. The validation that supports the claim
+
+Use maintainability notes when that is the honest win. Do not force a weak benchmark onto an example whose real value is simpler ownership or a narrower integration boundary.
+
+## Contribute an example
+
+If your migration could help other teams evaluate React on Rails, [open an issue](https://github.com/shakacode/react_on_rails/issues/new/choose) or [submit a PR](https://github.com/shakacode/react_on_rails/compare) adding it to this page, and include:
+
+1. The integration you started from, such as `react-rails`, `vite_rails`, or a custom helper
+2. The first slice you picked and why it was small enough to review
+3. The proof you captured, whether that was performance, maintainability, or both
+4. The validation you ran locally or in CI
+
+The most useful next examples are:
+
+1. `react-rails` apps that migrate one Rails-owned mount at a time
+2. Modern `vite_rails` apps where one Rails-owned island can move before a broader asset rewrite
+3. Apps with a custom Rails-side React bridge where one helper-backed boundary can be replaced before removing the wrapper
+4. Upgrades from older `react_on_rails` versions to current maintained defaults
+
+## How to use these examples
+
+Use this page together with the specific migration guide that matches your current stack:
+
+1. [Migrate from `react-rails`](./migrating-from-react-rails.md)
+2. [Migrate from `vite_rails`](./migrating-from-vite-rails.md)
+
+Other migration paths:
+
+1. [Webpack to Rspack](./migrating-from-webpack-to-rspack.md)
+2. [Babel to SWC](./babel-to-swc-migration.md)
+
+The Rails 5 API-only and AngularJS paths also live in the **Migration Guides** sidebar. For React Server Components migration content, start with [Migrating to RSC](./migrating-to-rsc.md).
+
+The migration guides explain the mechanics. This page shows what those mechanics look like in real repos.

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

@@ -1,7 +1,19 @@
-## Migrate From react-rails
+# Migrate From react-rails
 
 This migration is easiest when the app is already on a modern Rails + Shakapacker baseline.
 
+If you want repo-shaped references before touching your own app, start with
+[Example Migrations](./example-migrations.md) and then come back here for the
+mechanics.
+
+## Choose a first slice
+
+Pick a small first slice before you touch the whole app:
+
+1. Prefer one Rails-owned page, island, or shell fragment over a broad page rewrite.
+2. Good first wins are often maintainability-first: replacing `ReactRailsUJS` on one low-risk mount, splitting a large shell into smaller boundaries, or moving one legacy Rails page behind a documented helper path.
+3. The first PR does not need to eliminate every `react_component` call. It only needs to prove that one mount can move cleanly.
+
 ## Preflight
 
 Before swapping gems, check these first:
@@ -124,9 +136,7 @@ Older `react-rails` apps frequently need these additional fixes after the genera
    ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
    ```
 
-You can also check [react-rails-to-react-on-rails](https://github.com/shakacode/react-rails-example-app/tree/react-rails-to-react-on-rails) branch on [react-rails example app](https://github.com/shakacode/react-rails-example-app) for an example of migration from `react-rails` v3 to `react_on_rails` v13.4.
-
-For a more recent Rails 7-era migration example (published under ShakaCode), see [react-on-rails-migration-example](https://github.com/shakacode/react-on-rails-migration-example), based on [ganchdev/react-rails-example](https://github.com/ganchdev/react-rails-example).
+For published repo examples, including older and Rails 7-era `react-rails` migrations, see [Example Migrations](./example-migrations.md).
 
 ## Practical checklist for Webpacker-era apps
 

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

@@ -2,6 +2,10 @@
 
 This guide is for Rails apps that currently use `vite_rails` with React and want to move to React on Rails.
 
+If you want repo-shaped references before touching your own app, start with
+[Example Migrations](./example-migrations.md) and then come back here for the
+mechanics.
+
 ## When this migration makes sense
 
 React on Rails is a better fit when you want one or more of these:
@@ -38,6 +42,12 @@ Do the migration in a branch and keep the Vite setup working until the new React
 
 For anything beyond a tiny app, prefer a route-by-route cutover instead of a big-bang rewrite.
 
+If the app uses `vite_rails` plus a custom Rails-side React wrapper, the first credible PR may be maintainability-first rather than a full Vite removal. In that case:
+
+1. Replace one helper-backed component or boundary with React on Rails first.
+2. Keep Vite in place for the rest of the app until the narrow slice has parity.
+3. Treat Vite removal as a later step, not as the proof point itself.
+
 ## 1. Add React on Rails and Shakapacker
 
 ```bash
@@ -180,3 +190,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.
+
+For additional real-world migration references and active public PRs, see [Example Migrations](./example-migrations.md).

docs/oss/misc/doctrine.md

@@ -50,8 +50,8 @@ Here's the chef's selection from the React on Rails community:
 ### JavaScript Tooling
 
 - [Babel](https://babeljs.io/): Transpiler for ES6 into ES5 and much more.
-- [ESLint](http://eslint.org/)
-- [Webpack](http://webpack.github.io/): Generator of deployment assets and provider of hot module reloading.
+- [ESLint](https://eslint.org/)
+- [Webpack](https://webpack.js.org/): Generator of deployment assets and provider of hot module reloading.
 
 By having a common set of tools, we can discuss what we should or shouldn't be using. Thus, this takes out the "JavaScript Fatigue" from having too many unclear choices in the JavaScript world.
 

docs/sidebars.ts

@@ -175,6 +175,7 @@ const sidebars: SidebarsConfig = {
           type: 'category',
           label: 'Migration Guides',
           items: [
+            'migrating/example-migrations',
             'migrating/migrating-from-react-rails',
             'migrating/migrating-from-vite-rails',
             'migrating/migrating-from-webpack-to-rspack',