From 94ab21ed80b5151a693bcf591303136898c0a0c5 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 12 Apr 2026 15:37:27 -1000 Subject: [PATCH 01/29] docs: add example migrations guide --- docs/README.md | 2 +- docs/oss/migrating/example-migrations.md | 94 +++++++++++++++++++ .../migrating/migrating-from-react-rails.md | 2 + .../migrating/migrating-from-vite-rails.md | 2 + docs/sidebars.ts | 1 + 5 files changed, 100 insertions(+), 1 deletion(-) create mode 100644 docs/oss/migrating/example-migrations.md diff --git a/docs/README.md b/docs/README.md index 4070c1ecb5..2b36cd6c49 100644 --- a/docs/README.md +++ b/docs/README.md @@ -22,7 +22,7 @@ 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) - [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) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md new file mode 100644 index 0000000000..2e40d09704 --- /dev/null +++ b/docs/oss/migrating/example-migrations.md @@ -0,0 +1,94 @@ +## 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 +- a legacy asset-pipeline React mount + +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 notes instead of marketing claims + +## Current public references + +### Published example repos + +These are stable references you can inspect today: + +1. [react-rails example app: `react-rails-to-react-on-rails` branch](https://github.com/shakacode/react-rails-example-app/tree/react-rails-to-react-on-rails) +2. [react-on-rails-migration-example](https://github.com/shakacode/react-on-rails-migration-example) + +### Public migration PRs in progress + +These show how narrow, app-by-app migration slices look in real repositories: + +| Repo | Current Integration | First Slice | Status | +| ------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------- | +| [`EFForg/action-center-platform`](https://github.com/EFForg/action-center-platform) | `react-rails` | Admin topics page | [Draft PR #975](https://github.com/EFForg/action-center-platform/pull/975) | +| [`thewca/worldcubeassociation.org`](https://github.com/thewca/worldcubeassociation.org) | `react-rails` | Disclaimer page mount | [Draft PR #14010](https://github.com/thewca/worldcubeassociation.org/pull/14010) | +| [`demarche-numerique/demarche.numerique.gouv.fr`](https://github.com/demarche-numerique/demarche.numerique.gouv.fr) | `vite_rails` + custom React bridge | `SelectProcedureDropDownListComponent` | [Draft PR #12954](https://github.com/demarche-numerique/demarche.numerique.gouv.fr/pull/12954) | +| [`GSA/search-gov`](https://github.com/GSA/search-gov) | `react-rails` + Shakapacker | Search results shell split | [Draft PR #2010](https://github.com/GSA/search-gov/pull/2010) | + +## Example categories + +### `react-rails` to React on Rails + +This is usually the cleanest migration path. The main changes are: + +1. Replace `react_ujs` mounting with explicit React on Rails registration +2. Update `react_component` helper calls to the React on Rails options style +3. Keep the old app architecture in place while converting one mount at a time + +### `vite_rails` to React on Rails + +This is more of an asset and entrypoint migration than a component rewrite. + +The biggest changes are: + +1. Replace Vite layout tags and entrypoints +2. Move component registration into the React on Rails / Shakapacker flow +3. Preserve route behavior before removing Vite + +### Custom Rails React bridge to React on Rails + +This is common in mature apps that built a thin wrapper around React mounts. + +The safest approach is: + +1. Preserve the Rails-side props contract +2. Replace one helper-backed component boundary first +3. Treat the wrapper removal as a later step + +## What to compare before and after + +For each example, 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 metrics such as FCP, LCP, CLS, and TBT or INP. + +## 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) + +The migration guides explain the mechanics. This page shows what those mechanics look like in real repos. diff --git a/docs/oss/migrating/migrating-from-react-rails.md b/docs/oss/migrating/migrating-from-react-rails.md index fdcc031f16..44e6c30e7b 100644 --- a/docs/oss/migrating/migrating-from-react-rails.md +++ b/docs/oss/migrating/migrating-from-react-rails.md @@ -128,6 +128,8 @@ You can also check [react-rails-to-react-on-rails](https://github.com/shakacode/ 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 additional real-world migration references and active public PRs, see [Example Migrations](./example-migrations.md). + ## Practical checklist for Webpacker-era apps If your app looks like this: diff --git a/docs/oss/migrating/migrating-from-vite-rails.md b/docs/oss/migrating/migrating-from-vite-rails.md index 868263b904..3f2ba9ce4a 100644 --- a/docs/oss/migrating/migrating-from-vite-rails.md +++ b/docs/oss/migrating/migrating-from-vite-rails.md @@ -180,3 +180,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). diff --git a/docs/sidebars.ts b/docs/sidebars.ts index 62b99422ba..2add056dc3 100644 --- a/docs/sidebars.ts +++ b/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', From 483fd7ac48da183fff255eb243151df1d6967927 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 12 Apr 2026 16:19:45 -1000 Subject: [PATCH 02/29] docs: clarify migration proof examples --- docs/oss/migrating/example-migrations.md | 39 ++++++++++++++----- .../migrating/migrating-from-react-rails.md | 6 +++ .../migrating/migrating-from-vite-rails.md | 6 +++ 3 files changed, 41 insertions(+), 10 deletions(-) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index 2e40d09704..63d318365d 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -18,7 +18,7 @@ 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 notes instead of marketing claims +4. Measured with before-and-after performance or maintainability notes instead of marketing claims ## Current public references @@ -33,12 +33,14 @@ These are stable references you can inspect today: These show how narrow, app-by-app migration slices look in real repositories: -| Repo | Current Integration | First Slice | Status | -| ------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------- | -| [`EFForg/action-center-platform`](https://github.com/EFForg/action-center-platform) | `react-rails` | Admin topics page | [Draft PR #975](https://github.com/EFForg/action-center-platform/pull/975) | -| [`thewca/worldcubeassociation.org`](https://github.com/thewca/worldcubeassociation.org) | `react-rails` | Disclaimer page mount | [Draft PR #14010](https://github.com/thewca/worldcubeassociation.org/pull/14010) | -| [`demarche-numerique/demarche.numerique.gouv.fr`](https://github.com/demarche-numerique/demarche.numerique.gouv.fr) | `vite_rails` + custom React bridge | `SelectProcedureDropDownListComponent` | [Draft PR #12954](https://github.com/demarche-numerique/demarche.numerique.gouv.fr/pull/12954) | -| [`GSA/search-gov`](https://github.com/GSA/search-gov) | `react-rails` + Shakapacker | Search results shell split | [Draft PR #2010](https://github.com/GSA/search-gov/pull/2010) | +| Repo | Current Integration | First Slice | Status | Evidence so far | +| ------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| [`EFForg/action-center-platform`](https://github.com/EFForg/action-center-platform) | `react-rails` | Admin topics page | [Draft PR #975](https://github.com/EFForg/action-center-platform/pull/975) | Local benchmark note: warm request median `6.11ms -> 5.04ms`; estimated total JS bytes `2,179,067 -> 1,636,265` for the slice | +| [`thewca/worldcubeassociation.org`](https://github.com/thewca/worldcubeassociation.org) | `react-rails` | Disclaimer page mount | [Draft PR #14010](https://github.com/thewca/worldcubeassociation.org/pull/14010) | Maintainability note: one legacy Rails page now has a React on Rails path that stays separate from `next-frontend/` | +| [`demarche-numerique/demarche.numerique.gouv.fr`](https://github.com/demarche-numerique/demarche.numerique.gouv.fr) | `vite_rails` + custom React bridge | `SelectProcedureDropDownListComponent` | [Draft PR #12954](https://github.com/demarche-numerique/demarche.numerique.gouv.fr/pull/12954) | Maintainability note: replaced a custom `coldwired/react` mount contract with a documented React on Rails helper path | +| [`GSA/search-gov`](https://github.com/GSA/search-gov) | `react-rails` + Shakapacker | Search results shell split | [Draft PR #2010](https://github.com/GSA/search-gov/pull/2010) | Maintainability note: split SERP chrome into smaller mounts; public PR is green on `jest`, `rspec`, and `cucumber` | + +These PRs are still in progress. The useful part is the scope and the evidence, not whether they are already merged. ## Example categories @@ -70,11 +72,11 @@ The safest approach is: 2. Replace one helper-backed component boundary first 3. Treat the wrapper removal as a later step -## What to compare before and after +## What counts as proof -For each example, compare the same route on the baseline branch and the migration branch. +Not every good migration example is performance-first. -At minimum, record: +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 @@ -84,6 +86,23 @@ At minimum, record: If possible, also record browser metrics such as FCP, LCP, CLS, and TBT or INP. +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. + +## Later targets worth watching + +The current PR wave is intentionally narrow. After that, the next high-signal targets are: + +1. [`mastodon/mastodon`](https://github.com/mastodon/mastodon) and [`gitlabhq/gitlabhq`](https://github.com/gitlabhq/gitlabhq) as whale targets +2. [`thecartercenter/nemo`](https://github.com/thecartercenter/nemo) as a smaller institutionally credible `react-rails` target +3. [`Codeminer42/cm42-central`](https://github.com/Codeminer42/cm42-central) and [`broadinstitute/single_cell_portal_core`](https://github.com/broadinstitute/single_cell_portal_core) as modern `vite_rails` examples + ## How to use these examples Use this page together with the specific migration guide that matches your current stack: diff --git a/docs/oss/migrating/migrating-from-react-rails.md b/docs/oss/migrating/migrating-from-react-rails.md index 44e6c30e7b..283751c46b 100644 --- a/docs/oss/migrating/migrating-from-react-rails.md +++ b/docs/oss/migrating/migrating-from-react-rails.md @@ -15,6 +15,12 @@ Before swapping gems, check these first: If you are already on `shakapacker` 7+ and React 18+, the migration is mostly about helper syntax, component registration, and generated defaults. +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. + If `bundle install` fails before you even start because the lockfile was generated by Bundler 1.x, refresh the lockfile with a modern Bundler first: ```bash diff --git a/docs/oss/migrating/migrating-from-vite-rails.md b/docs/oss/migrating/migrating-from-vite-rails.md index 3f2ba9ce4a..c003522b9e 100644 --- a/docs/oss/migrating/migrating-from-vite-rails.md +++ b/docs/oss/migrating/migrating-from-vite-rails.md @@ -38,6 +38,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 From 6b09a4e8eafd266b52a29ec6012be7ddf4d8b2d1 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 12 Apr 2026 16:22:50 -1000 Subject: [PATCH 03/29] docs: timestamp migration references --- docs/oss/migrating/example-migrations.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index 63d318365d..377392239d 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -33,6 +33,8 @@ These are stable references you can inspect today: These show how narrow, app-by-app migration slices look in real repositories: +Last verified on April 12, 2026. Draft PR states may change after that date. + | Repo | Current Integration | First Slice | Status | Evidence so far | | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | [`EFForg/action-center-platform`](https://github.com/EFForg/action-center-platform) | `react-rails` | Admin topics page | [Draft PR #975](https://github.com/EFForg/action-center-platform/pull/975) | Local benchmark note: warm request median `6.11ms -> 5.04ms`; estimated total JS bytes `2,179,067 -> 1,636,265` for the slice | @@ -56,7 +58,7 @@ This is usually the cleanest migration path. The main changes are: This is more of an asset and entrypoint migration than a component rewrite. -The biggest changes are: +The primary changes are: 1. Replace Vite layout tags and entrypoints 2. Move component registration into the React on Rails / Shakapacker flow From 19dc8e026bf66bc9efac8b561de9a83ac67cb201 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 12 Apr 2026 16:24:19 -1000 Subject: [PATCH 04/29] docs: refine migration references wording --- docs/README.md | 1 + docs/oss/migrating/example-migrations.md | 14 +++++++------- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/README.md b/docs/README.md index 2b36cd6c49..179d1a7c5c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -23,6 +23,7 @@ React on Rails is one product with two tiers: open source for Rails + React inte ### Evaluating Rails + React options - [Example migrations](./oss/migrating/example-migrations.md) +- [Historical examples gallery](https://reactonrails.com/examples) - [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) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index 377392239d..e1616da0a4 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -1,4 +1,4 @@ -## Example Migrations +# Example Migrations Teams evaluating React on Rails are usually not starting from a blank Rails app. @@ -33,7 +33,7 @@ These are stable references you can inspect today: These show how narrow, app-by-app migration slices look in real repositories: -Last verified on April 12, 2026. Draft PR states may change after that date. +Snapshot verified on April 12, 2026. These external PR links may later point to merged or closed PRs. | Repo | Current Integration | First Slice | Status | Evidence so far | | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | @@ -97,13 +97,13 @@ When the change is maintainability-first, record: 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. -## Later targets worth watching +## Later research lanes -The current PR wave is intentionally narrow. After that, the next high-signal targets are: +The current PR wave is intentionally narrow. After that, the next high-signal lanes are: -1. [`mastodon/mastodon`](https://github.com/mastodon/mastodon) and [`gitlabhq/gitlabhq`](https://github.com/gitlabhq/gitlabhq) as whale targets -2. [`thecartercenter/nemo`](https://github.com/thecartercenter/nemo) as a smaller institutionally credible `react-rails` target -3. [`Codeminer42/cm42-central`](https://github.com/Codeminer42/cm42-central) and [`broadinstitute/single_cell_portal_core`](https://github.com/broadinstitute/single_cell_portal_core) as modern `vite_rails` examples +1. Large Rails + React monoliths on `vite_rails`, once a genuinely narrow maintainers-first slice exists +2. Institutionally credible `react-rails` apps that are still small enough for a one-mount PR +3. Modern `vite_rails` apps where one Rails-owned island or helper-backed boundary can move before broader asset changes ## How to use these examples From 27daf53546d9cf22a08b84ae66cab59e61e5f405 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 12 Apr 2026 16:25:40 -1000 Subject: [PATCH 05/29] docs: timestamp public pr rows --- docs/oss/migrating/example-migrations.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index e1616da0a4..322ce543ba 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -35,12 +35,12 @@ These show how narrow, app-by-app migration slices look in real repositories: Snapshot verified on April 12, 2026. These external PR links may later point to merged or closed PRs. -| Repo | Current Integration | First Slice | Status | Evidence so far | -| ------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -| [`EFForg/action-center-platform`](https://github.com/EFForg/action-center-platform) | `react-rails` | Admin topics page | [Draft PR #975](https://github.com/EFForg/action-center-platform/pull/975) | Local benchmark note: warm request median `6.11ms -> 5.04ms`; estimated total JS bytes `2,179,067 -> 1,636,265` for the slice | -| [`thewca/worldcubeassociation.org`](https://github.com/thewca/worldcubeassociation.org) | `react-rails` | Disclaimer page mount | [Draft PR #14010](https://github.com/thewca/worldcubeassociation.org/pull/14010) | Maintainability note: one legacy Rails page now has a React on Rails path that stays separate from `next-frontend/` | -| [`demarche-numerique/demarche.numerique.gouv.fr`](https://github.com/demarche-numerique/demarche.numerique.gouv.fr) | `vite_rails` + custom React bridge | `SelectProcedureDropDownListComponent` | [Draft PR #12954](https://github.com/demarche-numerique/demarche.numerique.gouv.fr/pull/12954) | Maintainability note: replaced a custom `coldwired/react` mount contract with a documented React on Rails helper path | -| [`GSA/search-gov`](https://github.com/GSA/search-gov) | `react-rails` + Shakapacker | Search results shell split | [Draft PR #2010](https://github.com/GSA/search-gov/pull/2010) | Maintainability note: split SERP chrome into smaller mounts; public PR is green on `jest`, `rspec`, and `cucumber` | +| Repo | Current Integration | First Slice | Status | Evidence so far | +| ------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | +| [`EFForg/action-center-platform`](https://github.com/EFForg/action-center-platform) | `react-rails` | Admin topics page | [Draft PR #975](https://github.com/EFForg/action-center-platform/pull/975) _(verified Apr 12, 2026)_ | Local benchmark note: warm request median `6.11ms -> 5.04ms`; estimated total JS bytes `2,179,067 -> 1,636,265` for the slice | +| [`thewca/worldcubeassociation.org`](https://github.com/thewca/worldcubeassociation.org) | `react-rails` | Disclaimer page mount | [Draft PR #14010](https://github.com/thewca/worldcubeassociation.org/pull/14010) _(verified Apr 12, 2026)_ | Maintainability note: one legacy Rails page now has a React on Rails path that stays separate from `next-frontend/` | +| [`demarche-numerique/demarche.numerique.gouv.fr`](https://github.com/demarche-numerique/demarche.numerique.gouv.fr) | `vite_rails` + custom React bridge | `SelectProcedureDropDownListComponent` | [Draft PR #12954](https://github.com/demarche-numerique/demarche.numerique.gouv.fr/pull/12954) _(verified Apr 12, 2026)_ | Maintainability note: replaced a custom `coldwired/react` mount contract with a documented React on Rails helper path | +| [`GSA/search-gov`](https://github.com/GSA/search-gov) | `react-rails` + Shakapacker | Search results shell split | [Draft PR #2010](https://github.com/GSA/search-gov/pull/2010) _(verified Apr 12, 2026)_ | Maintainability note: split SERP chrome into smaller mounts; public PR is green on `jest`, `rspec`, and `cucumber` | These PRs are still in progress. The useful part is the scope and the evidence, not whether they are already merged. From 800da332e04e4f6d1621269710c8121c29a56e51 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 12 Apr 2026 20:22:16 -1000 Subject: [PATCH 06/29] Clarify example migration caveats --- docs/oss/migrating/example-migrations.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index 322ce543ba..9d080cf55e 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -33,14 +33,14 @@ These are stable references you can inspect today: These show how narrow, app-by-app migration slices look in real repositories: -Snapshot verified on April 12, 2026. These external PR links may later point to merged or closed PRs. - -| Repo | Current Integration | First Slice | Status | Evidence so far | -| ------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | -| [`EFForg/action-center-platform`](https://github.com/EFForg/action-center-platform) | `react-rails` | Admin topics page | [Draft PR #975](https://github.com/EFForg/action-center-platform/pull/975) _(verified Apr 12, 2026)_ | Local benchmark note: warm request median `6.11ms -> 5.04ms`; estimated total JS bytes `2,179,067 -> 1,636,265` for the slice | -| [`thewca/worldcubeassociation.org`](https://github.com/thewca/worldcubeassociation.org) | `react-rails` | Disclaimer page mount | [Draft PR #14010](https://github.com/thewca/worldcubeassociation.org/pull/14010) _(verified Apr 12, 2026)_ | Maintainability note: one legacy Rails page now has a React on Rails path that stays separate from `next-frontend/` | -| [`demarche-numerique/demarche.numerique.gouv.fr`](https://github.com/demarche-numerique/demarche.numerique.gouv.fr) | `vite_rails` + custom React bridge | `SelectProcedureDropDownListComponent` | [Draft PR #12954](https://github.com/demarche-numerique/demarche.numerique.gouv.fr/pull/12954) _(verified Apr 12, 2026)_ | Maintainability note: replaced a custom `coldwired/react` mount contract with a documented React on Rails helper path | -| [`GSA/search-gov`](https://github.com/GSA/search-gov) | `react-rails` + Shakapacker | Search results shell split | [Draft PR #2010](https://github.com/GSA/search-gov/pull/2010) _(verified Apr 12, 2026)_ | Maintainability note: split SERP chrome into smaller mounts; public PR is green on `jest`, `rspec`, and `cucumber` | +Snapshot verified on April 12, 2026. These external PR links may later point to merged or closed PRs. When one of them changes state, update the row status or move it into the published examples list. + +| Repo | Current Integration | First Slice | Status | Evidence so far | +| ------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`EFForg/action-center-platform`](https://github.com/EFForg/action-center-platform) | `react-rails` | Admin topics page | [Draft PR #975](https://github.com/EFForg/action-center-platform/pull/975) _(verified Apr 12, 2026)_ | Contributor-local benchmark note, not a controlled public benchmark: warm request median `6.11ms -> 5.04ms`; estimated total JS bytes `2,179,067 -> 1,636,265` for the slice | +| [`thewca/worldcubeassociation.org`](https://github.com/thewca/worldcubeassociation.org) | `react-rails` | Disclaimer page mount | [Draft PR #14010](https://github.com/thewca/worldcubeassociation.org/pull/14010) _(verified Apr 12, 2026)_ | Maintainability note: one legacy Rails page now has a React on Rails path that stays separate from `next-frontend/` | +| [`demarche-numerique/demarche.numerique.gouv.fr`](https://github.com/demarche-numerique/demarche.numerique.gouv.fr) | `vite_rails` + custom React bridge | `SelectProcedureDropDownListComponent` | [Draft PR #12954](https://github.com/demarche-numerique/demarche.numerique.gouv.fr/pull/12954) _(verified Apr 12, 2026)_ | Maintainability note: replaced a custom `coldwired/react` mount contract with a documented React on Rails helper path | +| [`GSA/search-gov`](https://github.com/GSA/search-gov) | `react-rails` + Shakapacker | Search results shell split | [Draft PR #2010](https://github.com/GSA/search-gov/pull/2010) _(verified Apr 12, 2026)_ | Maintainability note: split SERP chrome into smaller mounts; public PR is green on `jest`, `rspec`, and `cucumber` | These PRs are still in progress. The useful part is the scope and the evidence, not whether they are already merged. From 3c3c636f749b81b730a2250ba7155b8cc384293d Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 12 Apr 2026 20:23:30 -1000 Subject: [PATCH 07/29] Refine migration docs wording --- docs/oss/migrating/example-migrations.md | 4 ++-- docs/oss/migrating/migrating-from-react-rails.md | 14 ++++++++------ 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index 9d080cf55e..5eb609b6b3 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -33,7 +33,7 @@ These are stable references you can inspect today: These show how narrow, app-by-app migration slices look in real repositories: -Snapshot verified on April 12, 2026. These external PR links may later point to merged or closed PRs. When one of them changes state, update the row status or move it into the published examples list. +These are point-in-time references. External PR links may later point to merged or closed PRs, and each row notes when it was last verified. When one of them changes state, update the row status or move it into the published examples list. | Repo | Current Integration | First Slice | Status | Evidence so far | | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -99,7 +99,7 @@ Use maintainability notes when that is the honest win. Do not force a weak bench ## Later research lanes -The current PR wave is intentionally narrow. After that, the next high-signal lanes are: +The examples in this page are intentionally narrow first slices. After those land, the next useful lanes are: 1. Large Rails + React monoliths on `vite_rails`, once a genuinely narrow maintainers-first slice exists 2. Institutionally credible `react-rails` apps that are still small enough for a one-mount PR diff --git a/docs/oss/migrating/migrating-from-react-rails.md b/docs/oss/migrating/migrating-from-react-rails.md index 283751c46b..b92e1f7307 100644 --- a/docs/oss/migrating/migrating-from-react-rails.md +++ b/docs/oss/migrating/migrating-from-react-rails.md @@ -2,6 +2,14 @@ This migration is easiest when the app is already on a modern Rails + Shakapacker baseline. +## 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: @@ -15,12 +23,6 @@ Before swapping gems, check these first: If you are already on `shakapacker` 7+ and React 18+, the migration is mostly about helper syntax, component registration, and generated defaults. -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. - If `bundle install` fails before you even start because the lockfile was generated by Bundler 1.x, refresh the lockfile with a modern Bundler first: ```bash From c03162e62761072a4ab8e468b067c32df3b13cf6 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Mon, 13 Apr 2026 11:45:36 -1000 Subject: [PATCH 08/29] Finish example migration docs cleanup --- docs/README.md | 2 +- docs/oss/migrating/example-migrations.md | 33 +++++++++++-------- .../migrating/migrating-from-react-rails.md | 2 +- docs/sidebars.ts | 2 +- 4 files changed, 23 insertions(+), 16 deletions(-) diff --git a/docs/README.md b/docs/README.md index 179d1a7c5c..3933c06926 100644 --- a/docs/README.md +++ b/docs/README.md @@ -23,7 +23,7 @@ React on Rails is one product with two tiers: open source for Rails + React inte ### Evaluating Rails + React options - [Example migrations](./oss/migrating/example-migrations.md) -- [Historical examples gallery](https://reactonrails.com/examples) +- [Examples gallery](https://reactonrails.com/examples) - [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) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index 5eb609b6b3..e9f929a2b7 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -31,16 +31,16 @@ These are stable references you can inspect today: ### Public migration PRs in progress -These show how narrow, app-by-app migration slices look in real repositories: +These show how narrow, app-by-app migration slices look in real repositories. They are point-in-time references: external PR links may later point to merged or closed PRs, and each row notes when it was last verified. -These are point-in-time references. External PR links may later point to merged or closed PRs, and each row notes when it was last verified. When one of them changes state, update the row status or move it into the published examples list. +> Maintainer note: check each linked PR before any docs release. Move merged or closed PRs into the published examples list above, and consider removing rows that have gone stale for multiple months. -| Repo | Current Integration | First Slice | Status | Evidence so far | -| ------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`EFForg/action-center-platform`](https://github.com/EFForg/action-center-platform) | `react-rails` | Admin topics page | [Draft PR #975](https://github.com/EFForg/action-center-platform/pull/975) _(verified Apr 12, 2026)_ | Contributor-local benchmark note, not a controlled public benchmark: warm request median `6.11ms -> 5.04ms`; estimated total JS bytes `2,179,067 -> 1,636,265` for the slice | -| [`thewca/worldcubeassociation.org`](https://github.com/thewca/worldcubeassociation.org) | `react-rails` | Disclaimer page mount | [Draft PR #14010](https://github.com/thewca/worldcubeassociation.org/pull/14010) _(verified Apr 12, 2026)_ | Maintainability note: one legacy Rails page now has a React on Rails path that stays separate from `next-frontend/` | -| [`demarche-numerique/demarche.numerique.gouv.fr`](https://github.com/demarche-numerique/demarche.numerique.gouv.fr) | `vite_rails` + custom React bridge | `SelectProcedureDropDownListComponent` | [Draft PR #12954](https://github.com/demarche-numerique/demarche.numerique.gouv.fr/pull/12954) _(verified Apr 12, 2026)_ | Maintainability note: replaced a custom `coldwired/react` mount contract with a documented React on Rails helper path | -| [`GSA/search-gov`](https://github.com/GSA/search-gov) | `react-rails` + Shakapacker | Search results shell split | [Draft PR #2010](https://github.com/GSA/search-gov/pull/2010) _(verified Apr 12, 2026)_ | Maintainability note: split SERP chrome into smaller mounts; public PR is green on `jest`, `rspec`, and `cucumber` | +| Repo | Current Integration | First Slice | Status | Evidence so far | +| ------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`EFForg/action-center-platform`](https://github.com/EFForg/action-center-platform) | `react-rails` | Admin topics page | [Draft PR #975](https://github.com/EFForg/action-center-platform/pull/975) _(verified Apr 12, 2026)_ | Contributor-local benchmark note, not a controlled public benchmark: warm request time and total JS weight both decreased for this slice; see the draft PR for the contributor's measurements | +| [`thewca/worldcubeassociation.org`](https://github.com/thewca/worldcubeassociation.org) | `react-rails` | Disclaimer page mount | [Draft PR #14010](https://github.com/thewca/worldcubeassociation.org/pull/14010) _(verified Apr 12, 2026)_ | Maintainability note: one legacy Rails page now has a React on Rails path that stays separate from `next-frontend/` | +| [`demarche-numerique/demarche.numerique.gouv.fr`](https://github.com/demarche-numerique/demarche.numerique.gouv.fr) | `vite_rails` + custom React bridge | `SelectProcedureDropDownListComponent` | [Draft PR #12954](https://github.com/demarche-numerique/demarche.numerique.gouv.fr/pull/12954) _(verified Apr 12, 2026)_ | Maintainability note: replaced a custom `coldwired/react` mount contract with a documented React on Rails helper path | +| [`GSA/search-gov`](https://github.com/GSA/search-gov) | `react-rails` + Shakapacker | Search results shell split | [Draft PR #2010](https://github.com/GSA/search-gov/pull/2010) _(verified Apr 12, 2026)_ | Maintainability note: split SERP chrome into smaller mounts; public PR is green on `jest`, `rspec`, and `cucumber` | These PRs are still in progress. The useful part is the scope and the evidence, not whether they are already merged. @@ -97,13 +97,20 @@ When the change is maintainability-first, record: 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. -## Later research lanes +## Contribute an example -The examples in this page are intentionally narrow first slices. After those land, the next useful lanes are: +If your migration could help other teams evaluate React on Rails, open an issue or PR that adds it here and include: -1. Large Rails + React monoliths on `vite_rails`, once a genuinely narrow maintainers-first slice exists -2. Institutionally credible `react-rails` apps that are still small enough for a one-mount PR -3. Modern `vite_rails` apps where one Rails-owned island or helper-backed boundary can move before broader asset changes +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. Upgrades from older `react_on_rails` versions to current maintained defaults ## How to use these examples diff --git a/docs/oss/migrating/migrating-from-react-rails.md b/docs/oss/migrating/migrating-from-react-rails.md index b92e1f7307..7aaa617644 100644 --- a/docs/oss/migrating/migrating-from-react-rails.md +++ b/docs/oss/migrating/migrating-from-react-rails.md @@ -1,4 +1,4 @@ -## Migrate From react-rails +# Migrate From react-rails This migration is easiest when the app is already on a modern Rails + Shakapacker baseline. diff --git a/docs/sidebars.ts b/docs/sidebars.ts index 2add056dc3..da85ae717d 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -175,13 +175,13 @@ 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', 'migrating/babel-to-swc-migration', 'migrating/convert-rails-5-api-only-app', 'migrating/angular-js-integration-migration', + 'migrating/example-migrations', ], }, ], From a4cf44cbdce7cb069d57d8eba31faefc2222931d Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Mon, 13 Apr 2026 11:53:14 -1000 Subject: [PATCH 09/29] Keep example migration docs stable --- docs/oss/migrating/example-migrations.md | 20 +++++++++---------- .../migrating/migrating-from-react-rails.md | 4 ++++ .../migrating/migrating-from-vite-rails.md | 4 ++++ 3 files changed, 17 insertions(+), 11 deletions(-) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index e9f929a2b7..3f3ccdc60e 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -29,20 +29,18 @@ These are stable references you can inspect today: 1. [react-rails example app: `react-rails-to-react-on-rails` branch](https://github.com/shakacode/react-rails-example-app/tree/react-rails-to-react-on-rails) 2. [react-on-rails-migration-example](https://github.com/shakacode/react-on-rails-migration-example) -### Public migration PRs in progress +### In-progress migration work -These show how narrow, app-by-app migration slices look in real repositories. They are point-in-time references: external PR links may later point to merged or closed PRs, and each row notes when it was last verified. +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. -> Maintainer note: check each linked PR before any docs release. Move merged or closed PRs into the published examples list above, and consider removing rows that have gone stale for multiple months. +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. -| Repo | Current Integration | First Slice | Status | Evidence so far | -| ------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`EFForg/action-center-platform`](https://github.com/EFForg/action-center-platform) | `react-rails` | Admin topics page | [Draft PR #975](https://github.com/EFForg/action-center-platform/pull/975) _(verified Apr 12, 2026)_ | Contributor-local benchmark note, not a controlled public benchmark: warm request time and total JS weight both decreased for this slice; see the draft PR for the contributor's measurements | -| [`thewca/worldcubeassociation.org`](https://github.com/thewca/worldcubeassociation.org) | `react-rails` | Disclaimer page mount | [Draft PR #14010](https://github.com/thewca/worldcubeassociation.org/pull/14010) _(verified Apr 12, 2026)_ | Maintainability note: one legacy Rails page now has a React on Rails path that stays separate from `next-frontend/` | -| [`demarche-numerique/demarche.numerique.gouv.fr`](https://github.com/demarche-numerique/demarche.numerique.gouv.fr) | `vite_rails` + custom React bridge | `SelectProcedureDropDownListComponent` | [Draft PR #12954](https://github.com/demarche-numerique/demarche.numerique.gouv.fr/pull/12954) _(verified Apr 12, 2026)_ | Maintainability note: replaced a custom `coldwired/react` mount contract with a documented React on Rails helper path | -| [`GSA/search-gov`](https://github.com/GSA/search-gov) | `react-rails` + Shakapacker | Search results shell split | [Draft PR #2010](https://github.com/GSA/search-gov/pull/2010) _(verified Apr 12, 2026)_ | Maintainability note: split SERP chrome into smaller mounts; public PR is green on `jest`, `rspec`, and `cucumber` | - -These PRs are still in progress. The useful part is the scope and the evidence, not whether they are already merged. +When a public migration becomes a stable reference, add it to the published example +list above with a short proof note. ## Example categories diff --git a/docs/oss/migrating/migrating-from-react-rails.md b/docs/oss/migrating/migrating-from-react-rails.md index 7aaa617644..b3dd5c03e5 100644 --- a/docs/oss/migrating/migrating-from-react-rails.md +++ b/docs/oss/migrating/migrating-from-react-rails.md @@ -2,6 +2,10 @@ 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: diff --git a/docs/oss/migrating/migrating-from-vite-rails.md b/docs/oss/migrating/migrating-from-vite-rails.md index c003522b9e..d0f91f3ae3 100644 --- a/docs/oss/migrating/migrating-from-vite-rails.md +++ b/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: From 4a7b246e1ff4ba5d7a4e9318ea6c725f19221325 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Fri, 17 Apr 2026 21:56:13 -1000 Subject: [PATCH 10/29] docs: address PR #3126 review feedback - Move Example Migrations to the top of the Migration Guides sidebar so the nav order matches the 'start with Example Migrations' pointer at the top of the react-rails and vite-rails guides. - Add a short qualifier to the second published example repo link so it has parity with the first (describes the underlying reference app). - Add the custom Rails React bridge lane to the 'Contribute an example' list so it matches the three migration categories earlier in the doc. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/oss/migrating/example-migrations.md | 5 +++-- docs/sidebars.ts | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index 3f3ccdc60e..825fe29652 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -27,7 +27,7 @@ The best examples are: These are stable references you can inspect today: 1. [react-rails example app: `react-rails-to-react-on-rails` branch](https://github.com/shakacode/react-rails-example-app/tree/react-rails-to-react-on-rails) -2. [react-on-rails-migration-example](https://github.com/shakacode/react-on-rails-migration-example) +2. [react-on-rails-migration-example](https://github.com/shakacode/react-on-rails-migration-example) — based on `ganchdev/react-rails-example` ### In-progress migration work @@ -108,7 +108,8 @@ 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. Upgrades from older `react_on_rails` versions to current maintained defaults +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 diff --git a/docs/sidebars.ts b/docs/sidebars.ts index da85ae717d..2add056dc3 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -175,13 +175,13 @@ 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', 'migrating/babel-to-swc-migration', 'migrating/convert-rails-5-api-only-app', 'migrating/angular-js-integration-migration', - 'migrating/example-migrations', ], }, ], From 6f32579ab937592e1261fdeffc6bd369565e3b88 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sat, 18 Apr 2026 09:29:33 -1000 Subject: [PATCH 11/29] docs: link the issue tracker from the contribute section Adds a direct `open an issue` link to the GitHub issue tracker in the `Contribute an example` section of `example-migrations.md` so readers unfamiliar with the repo don't need to hunt for the URL. Addresses PR #3126 review feedback on thread PRRT_kwDOAnNnU8577IAz. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/oss/migrating/example-migrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index 825fe29652..5e5bd34335 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -97,7 +97,7 @@ Use maintainability notes when that is the honest win. Do not force a weak bench ## Contribute an example -If your migration could help other teams evaluate React on Rails, open an issue or PR that adds it here and include: +If your migration could help other teams evaluate React on Rails, [open an issue](https://github.com/shakacode/react_on_rails/issues/new) or PR that adds it here 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 From dcec18381ba29c0a44cfc73de9c71e03fad1fa58 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sat, 18 Apr 2026 09:50:47 -1000 Subject: [PATCH 12/29] docs: address final review polish on example migrations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Drop the duplicate `react-on-rails-migration-example` link from `docs/README.md`; it is now the first entry in the example-migrations page that the README already links to. - Drop the "legacy asset-pipeline React mount" bullet from the intro list in `example-migrations.md` so the four-stack list matches the three subsections under "Example categories". - Add a one-line pointer at the end of "How to use these examples" to the other migration guides (Webpack → Rspack, Babel → SWC, Rails 5 API-only, AngularJS, RSC) so readers know the broader sidebar set exists. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/README.md | 1 - docs/oss/migrating/example-migrations.md | 3 ++- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/README.md b/docs/README.md index 3933c06926..d8aa6b27db 100644 --- a/docs/README.md +++ b/docs/README.md @@ -26,7 +26,6 @@ React on Rails is one product with two tiers: open source for Rails + React inte - [Examples gallery](https://reactonrails.com/examples) - [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 diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index 5e5bd34335..9b17c5efb7 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -7,7 +7,6 @@ They already have one of these: - `react-rails` - `vite_rails` - a custom Rails-side React helper -- a legacy asset-pipeline React mount This page tracks practical migration references for those cases. @@ -118,4 +117,6 @@ Use this page together with the specific migration guide that matches your curre 1. [Migrate from `react-rails`](./migrating-from-react-rails.md) 2. [Migrate from `vite_rails`](./migrating-from-vite-rails.md) +Other migration paths (Webpack → Rspack, Babel → SWC, Rails 5 API-only, AngularJS, RSC) live in the **Migration Guides** sidebar. + The migration guides explain the mechanics. This page shows what those mechanics look like in real repos. From 7040927a4bd47a455257762ac321aa034ada35a2 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sat, 18 Apr 2026 13:26:02 -1000 Subject: [PATCH 13/29] docs: clarify example migration guidance --- docs/oss/migrating/example-migrations.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index 9b17c5efb7..aa56c2bf63 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -7,6 +7,11 @@ They already have one of these: - `react-rails` - `vite_rails` - a custom Rails-side React helper +- a legacy asset-pipeline React mount + +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. This page tracks practical migration references for those cases. @@ -26,7 +31,7 @@ The best examples are: These are stable references you can inspect today: 1. [react-rails example app: `react-rails-to-react-on-rails` branch](https://github.com/shakacode/react-rails-example-app/tree/react-rails-to-react-on-rails) -2. [react-on-rails-migration-example](https://github.com/shakacode/react-on-rails-migration-example) — based on `ganchdev/react-rails-example` +2. [react-on-rails-migration-example](https://github.com/shakacode/react-on-rails-migration-example) ### In-progress migration work @@ -83,7 +88,9 @@ When the change is performance-first, compare the same route on the baseline bra 4. Number of JS assets needed for the route 5. Hydration warnings or client boot errors -If possible, also record browser metrics such as FCP, LCP, CLS, and TBT or INP. +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: @@ -96,7 +103,7 @@ Use maintainability notes when that is the honest win. Do not force a weak bench ## 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) or PR that adds it here and include: +If your migration could help other teams evaluate React on Rails, [open an issue](https://github.com/shakacode/react_on_rails/issues/new) or open a PR that adds it here, 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 @@ -107,8 +114,7 @@ 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 +3. Upgrades from older `react_on_rails` versions to current maintained defaults ## How to use these examples @@ -117,6 +123,4 @@ Use this page together with the specific migration guide that matches your curre 1. [Migrate from `react-rails`](./migrating-from-react-rails.md) 2. [Migrate from `vite_rails`](./migrating-from-vite-rails.md) -Other migration paths (Webpack → Rspack, Babel → SWC, Rails 5 API-only, AngularJS, RSC) live in the **Migration Guides** sidebar. - The migration guides explain the mechanics. This page shows what those mechanics look like in real repos. From 7c7ae4f22bb3303764a1dfdec1bcb262d262abbe Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sat, 18 Apr 2026 13:32:04 -1000 Subject: [PATCH 14/29] docs: clarify example migration guidance --- docs/oss/migrating/example-migrations.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index aa56c2bf63..98e6d3e7b8 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -7,7 +7,6 @@ They already have one of these: - `react-rails` - `vite_rails` - a custom Rails-side React helper -- a legacy asset-pipeline React mount 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, @@ -31,7 +30,7 @@ The best examples are: These are stable references you can inspect today: 1. [react-rails example app: `react-rails-to-react-on-rails` branch](https://github.com/shakacode/react-rails-example-app/tree/react-rails-to-react-on-rails) -2. [react-on-rails-migration-example](https://github.com/shakacode/react-on-rails-migration-example) +2. [react-on-rails-migration-example](https://github.com/shakacode/react-on-rails-migration-example) — based on `ganchdev/react-rails-example` ### In-progress migration work @@ -114,7 +113,8 @@ 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. Upgrades from older `react_on_rails` versions to current maintained defaults +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 @@ -123,4 +123,6 @@ Use this page together with the specific migration guide that matches your curre 1. [Migrate from `react-rails`](./migrating-from-react-rails.md) 2. [Migrate from `vite_rails`](./migrating-from-vite-rails.md) +Other migration paths (Webpack → Rspack, Babel → SWC, Rails 5 API-only, AngularJS, RSC) live in the **Migration Guides** sidebar. + The migration guides explain the mechanics. This page shows what those mechanics look like in real repos. From c029bc9d4acc105d4918d575d7a1ff67cb66a4ee Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sat, 18 Apr 2026 13:32:16 -1000 Subject: [PATCH 15/29] docs: keep example migration guidance precise --- docs/oss/migrating/example-migrations.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index 98e6d3e7b8..4ded77b823 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -10,7 +10,8 @@ They already have one of these: 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. +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. From 3796d6e1252e29136147615247698ba801a54bb1 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sat, 18 Apr 2026 13:36:18 -1000 Subject: [PATCH 16/29] docs: align example migration links --- docs/oss/migrating/example-migrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index 4ded77b823..2cb7f94aa3 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -31,7 +31,7 @@ The best examples are: These are stable references you can inspect today: 1. [react-rails example app: `react-rails-to-react-on-rails` branch](https://github.com/shakacode/react-rails-example-app/tree/react-rails-to-react-on-rails) -2. [react-on-rails-migration-example](https://github.com/shakacode/react-on-rails-migration-example) — based on `ganchdev/react-rails-example` +2. [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) ### In-progress migration work From bed61a7e977e05e2a4f8d35c56cb5955025b3149 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sat, 18 Apr 2026 23:56:45 -1000 Subject: [PATCH 17/29] docs: address review on example migrations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - correct RSC sidebar pointer: RSC migration guides live under React on Rails Pro → React Server Components, not the top-level Migration Guides sidebar - add version baseline ("react-rails v3 → react_on_rails v13.4") on the first published example repo so readers can calibrate relevance without clicking through Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/oss/migrating/example-migrations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index 2cb7f94aa3..913d29c089 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -30,7 +30,7 @@ The best examples are: These are stable references you can inspect today: -1. [react-rails example app: `react-rails-to-react-on-rails` branch](https://github.com/shakacode/react-rails-example-app/tree/react-rails-to-react-on-rails) +1. [react-rails example app: `react-rails-to-react-on-rails` branch](https://github.com/shakacode/react-rails-example-app/tree/react-rails-to-react-on-rails) — covers react-rails v3 → react_on_rails v13.4 2. [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) ### In-progress migration work @@ -124,6 +124,6 @@ Use this page together with the specific migration guide that matches your curre 1. [Migrate from `react-rails`](./migrating-from-react-rails.md) 2. [Migrate from `vite_rails`](./migrating-from-vite-rails.md) -Other migration paths (Webpack → Rspack, Babel → SWC, Rails 5 API-only, AngularJS, RSC) live in the **Migration Guides** sidebar. +Other migration paths (Webpack → Rspack, Babel → SWC, Rails 5 API-only, AngularJS) live in the **Migration Guides** sidebar. RSC migration content lives under **React on Rails Pro → React Server Components**. The migration guides explain the mechanics. This page shows what those mechanics look like in real repos. From 200ce49bb11683e6ac3f02c5643e21db68b76cf6 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sat, 18 Apr 2026 12:18:55 -1000 Subject: [PATCH 18/29] docs: clarify example migration guidance --- docs/oss/migrating/example-migrations.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index 913d29c089..95b4abbac4 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -13,6 +13,10 @@ 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). +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. + This page tracks practical migration references for those cases. ## What makes a useful migration example From e3e3e1acdf64f9f7a73482cbcd2509e83cad174f Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 19 Apr 2026 00:37:20 -1000 Subject: [PATCH 19/29] docs: tighten example migration references --- docs/oss/migrating/example-migrations.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index 95b4abbac4..be3d131998 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -34,7 +34,7 @@ The best examples are: These are stable references you can inspect today: -1. [react-rails example app: `react-rails-to-react-on-rails` branch](https://github.com/shakacode/react-rails-example-app/tree/react-rails-to-react-on-rails) — covers react-rails v3 → react_on_rails v13.4 +1. [react-rails example app: `react-rails-to-react-on-rails` branch](https://github.com/shakacode/react-rails-example-app/tree/react-rails-to-react-on-rails) — covers `react-rails` v3 → `react_on_rails` v13.4, so compare it with the current migration guides before following it step by step 2. [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) ### In-progress migration work @@ -128,6 +128,11 @@ Use this page together with the specific migration guide that matches your curre 1. [Migrate from `react-rails`](./migrating-from-react-rails.md) 2. [Migrate from `vite_rails`](./migrating-from-vite-rails.md) -Other migration paths (Webpack → Rspack, Babel → SWC, Rails 5 API-only, AngularJS) live in the **Migration Guides** sidebar. RSC migration content lives under **React on Rails Pro → React Server Components**. +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. React Server Components migration content lives under **React on Rails Pro → React Server Components**. The migration guides explain the mechanics. This page shows what those mechanics look like in real repos. From 368a5df5a3267893d439410b7f85572fc20ffc4b Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 19 Apr 2026 18:16:45 -1000 Subject: [PATCH 20/29] docs: remove duplicate Inertia paragraph in example migrations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Inertia framing paragraph was present twice in docs/oss/migrating/example-migrations.md — the second copy was missing the Compare with alternatives link and was redundant. Deletes the second copy so the intro flows straight into the This page tracks practical migration references sentence. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/oss/migrating/example-migrations.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index be3d131998..1651195818 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -13,10 +13,6 @@ 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). -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. - This page tracks practical migration references for those cases. ## What makes a useful migration example From 2adc9a50632627de42fbeddb3cb2698f36db7190 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Wed, 22 Apr 2026 14:56:13 -1000 Subject: [PATCH 21/29] docs: tighten example migration guidance --- docs/oss/migrating/example-migrations.md | 37 +++++++++++------------- 1 file changed, 17 insertions(+), 20 deletions(-) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index 1651195818..bb417973ba 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -28,10 +28,15 @@ The best examples are: ### Published example repos -These are stable references you can inspect today: +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` branch](https://github.com/shakacode/react-rails-example-app/tree/react-rails-to-react-on-rails) — covers `react-rails` v3 → `react_on_rails` v13.4, so compare it with the current migration guides before following it step by step -2. [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) +1. [react-rails example app: `react-rails-to-react-on-rails` branch](https://github.com/shakacode/react-rails-example-app/tree/react-rails-to-react-on-rails) — + covers `react-rails` v3 → `react_on_rails` v13.4 (current is v16.6.0), 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) — + based on [ganchdev/react-rails-example](https://github.com/ganchdev/react-rails-example) ### In-progress migration work @@ -50,31 +55,23 @@ list above with a short proof note. ### `react-rails` to React on Rails -This is usually the cleanest migration path. The main changes are: - -1. Replace `react_ujs` mounting with explicit React on Rails registration -2. Update `react_component` helper calls to the React on Rails options style -3. Keep the old app architecture in place while converting one mount at a time +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 primary changes are: - -1. Replace Vite layout tags and entrypoints -2. Move component registration into the React on Rails / Shakapacker flow -3. Preserve route behavior before removing Vite +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. -The safest approach is: - -1. Preserve the Rails-side props contract -2. Replace one helper-backed component boundary first -3. Treat the wrapper removal as a later step +Treat the wrapper as the migration boundary: preserve the Rails-side props +contract, replace one helper-backed component first, and remove the wrapper +later. ## What counts as proof From faf25fee694cdefdfc3dfe4da44ef784c4a91643 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Wed, 22 Apr 2026 15:04:59 -1000 Subject: [PATCH 22/29] docs: fix markdown link check failures --- docs/oss/building-features/node-renderer/js-configuration.md | 2 +- docs/oss/misc/doctrine.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/oss/building-features/node-renderer/js-configuration.md b/docs/oss/building-features/node-renderer/js-configuration.md index d524c424b9..f67644adb6 100644 --- a/docs/oss/building-features/node-renderer/js-configuration.md +++ b/docs/oss/building-features/node-renderer/js-configuration.md @@ -58,7 +58,7 @@ Deprecated options: ### Testing example: -[spec/dummy/client/node-renderer.js](https://github.com/shakacode/react_on_rails/blob/main/react_on_rails_pro/spec/dummy/client/node-renderer.js) +See `react_on_rails_pro/spec/dummy/client/node-renderer.js` in this repository. ### Simple example: diff --git a/docs/oss/misc/doctrine.md b/docs/oss/misc/doctrine.md index dc8415e2c7..28766bda43 100644 --- a/docs/oss/misc/doctrine.md +++ b/docs/oss/misc/doctrine.md @@ -50,7 +50,7 @@ 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/) +- [ESLint](https://eslint.org/) - [Webpack](http://webpack.github.io/): 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. From 4adf75811d11a7f83564cd73d6ea401d93d73b09 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Wed, 22 Apr 2026 15:09:06 -1000 Subject: [PATCH 23/29] docs: clarify example migration references --- docs/oss/migrating/example-migrations.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index bb417973ba..a2cfdff83f 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -32,11 +32,13 @@ 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` branch](https://github.com/shakacode/react-rails-example-app/tree/react-rails-to-react-on-rails) — - covers `react-rails` v3 → `react_on_rails` v13.4 (current is v16.6.0), so - treat it as a structural reference and follow current migration guides for - gem and configuration specifics + 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) — - based on [ganchdev/react-rails-example](https://github.com/ganchdev/react-rails-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 From 9c3529a8acbb5d23c1bcbde612a50fdc9a496ddd Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Wed, 22 Apr 2026 15:18:28 -1000 Subject: [PATCH 24/29] docs: resolve migration guide review follow-ups --- docs/README.md | 4 ++-- docs/oss/migrating/example-migrations.md | 6 +++++- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/README.md b/docs/README.md index d8aa6b27db..1dcfdafae8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -22,8 +22,8 @@ React on Rails is one product with two tiers: open source for Rails + React inte ### Evaluating Rails + React options -- [Example migrations](./oss/migrating/example-migrations.md) -- [Examples gallery](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) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index a2cfdff83f..ad64f71b06 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -31,7 +31,7 @@ The best examples are: 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` branch](https://github.com/shakacode/react-rails-example-app/tree/react-rails-to-react-on-rails) — +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 @@ -75,6 +75,10 @@ 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. 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. From 4cd2750598f8109c3a5dbf1cb2dc8a6426c3b664 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Wed, 22 Apr 2026 15:22:38 -1000 Subject: [PATCH 25/29] docs: address final migration review notes --- docs/oss/migrating/example-migrations.md | 2 +- docs/oss/misc/doctrine.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index ad64f71b06..18cbc41c1e 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -132,6 +132,6 @@ 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. React Server Components migration content lives under **React on Rails Pro → React Server Components**. +The Rails 5 API-only and AngularJS paths also live in the **Migration Guides** sidebar. React Server Components migration content lives under **React on Rails Pro → React Server Components → Migrating to RSC**. The migration guides explain the mechanics. This page shows what those mechanics look like in real repos. diff --git a/docs/oss/misc/doctrine.md b/docs/oss/misc/doctrine.md index 28766bda43..d050ba81e0 100644 --- a/docs/oss/misc/doctrine.md +++ b/docs/oss/misc/doctrine.md @@ -51,7 +51,7 @@ Here's the chef's selection from the React on Rails community: - [Babel](https://babeljs.io/): Transpiler for ES6 into ES5 and much more. - [ESLint](https://eslint.org/) -- [Webpack](http://webpack.github.io/): Generator of deployment assets and provider of hot module reloading. +- [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. From e12844b9f93efea845e44ff009be93e21dd91615 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Wed, 22 Apr 2026 15:27:04 -1000 Subject: [PATCH 26/29] docs: standardize migration reference links --- docs/oss/migrating/example-migrations.md | 4 ++-- docs/oss/migrating/migrating-from-react-rails.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index 18cbc41c1e..0f6fd7ec15 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -106,7 +106,7 @@ Use maintainability notes when that is the honest win. Do not force a weak bench ## 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) or open a PR that adds it here, and include: +If your migration could help other teams evaluate React on Rails, [open an issue](https://github.com/shakacode/react_on_rails/issues/new?title=Migration+example%3A+) or open a PR that adds it here, 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 @@ -132,6 +132,6 @@ 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. React Server Components migration content lives under **React on Rails Pro → React Server Components → Migrating to RSC**. +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. diff --git a/docs/oss/migrating/migrating-from-react-rails.md b/docs/oss/migrating/migrating-from-react-rails.md index b3dd5c03e5..a92f9bc154 100644 --- a/docs/oss/migrating/migrating-from-react-rails.md +++ b/docs/oss/migrating/migrating-from-react-rails.md @@ -136,7 +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. +You can also check the [react-rails-to-react-on-rails snapshot](https://github.com/shakacode/react-rails-example-app/tree/c6b794a4b96746dbbc98a46f31119171109d70b0) 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). From a7da991e00ad60fddecaf092b0b499da8e9efde5 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Wed, 22 Apr 2026 15:31:13 -1000 Subject: [PATCH 27/29] docs: consolidate migration examples references --- docs/oss/migrating/example-migrations.md | 2 +- docs/oss/migrating/migrating-from-react-rails.md | 6 +----- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index 0f6fd7ec15..33824a3d31 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -106,7 +106,7 @@ Use maintainability notes when that is the honest win. Do not force a weak bench ## 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?title=Migration+example%3A+) or open a PR that adds it here, and include: +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 open a PR that adds it here, 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 diff --git a/docs/oss/migrating/migrating-from-react-rails.md b/docs/oss/migrating/migrating-from-react-rails.md index a92f9bc154..a3ed797cd1 100644 --- a/docs/oss/migrating/migrating-from-react-rails.md +++ b/docs/oss/migrating/migrating-from-react-rails.md @@ -136,11 +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 the [react-rails-to-react-on-rails snapshot](https://github.com/shakacode/react-rails-example-app/tree/c6b794a4b96746dbbc98a46f31119171109d70b0) 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 additional real-world migration references and active public PRs, see [Example Migrations](./example-migrations.md). +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 From 5c07d428c6eead27c572a28def93c78f47dfde37 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Wed, 22 Apr 2026 15:36:08 -1000 Subject: [PATCH 28/29] docs: point custom bridge examples to contribution flow --- docs/oss/migrating/example-migrations.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index 33824a3d31..c3570b3feb 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -75,9 +75,9 @@ 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. The [react-rails migration guide](./migrating-from-react-rails.md) -covers the nearest-neighbor mechanics for helper syntax and component -registration. +No dedicated guide exists yet; if you have one, 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 From e08fa277941980a3358a085eb86858aab2b9635a Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Wed, 22 Apr 2026 15:41:48 -1000 Subject: [PATCH 29/29] docs: clarify example contribution links --- docs/oss/migrating/example-migrations.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index c3570b3feb..6582f7a32a 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -75,7 +75,8 @@ 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 you have one, see [Contribute an example](#contribute-an-example). +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. @@ -106,7 +107,7 @@ Use maintainability notes when that is the honest win. Do not force a weak bench ## 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 open a PR that adds it here, and include: +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