Skip to content

Commit b016a75

Browse files
justin808claude
justin808
and
claude
authored
docs: add example migrations guide (#3126)
## Summary Adds a new OSS docs page for real-world example migrations and wires it into the docs navigation. ## What changed - add `docs/oss/migrating/example-migrations.md` - link the new page from `docs/README.md` - add the page to the migration sidebar - cross-link the page from the `react-rails` and `vite_rails` migration guides - fix the top-level heading in `docs/oss/migrating/migrating-from-react-rails.md` from `##` to `#` so Docusaurus renders it as the page title (real correctness fix, not cosmetic) - add a direct `open an issue` link in the `Contribute an example` section of `example-migrations.md` so contributors don't need to hunt for the repo URL ## Why Teams evaluating React on Rails often already have an app on `react-rails`, `vite_rails`, or a custom Rails-side React bridge. This docs page gives them one place to see: - published example repos - active public migration PRs - the main migration categories - what should be compared before and after a migration Related to #3125 (kept open as the long-lived meta tracker for in-progress migration PRs, which this doc page links to). ## Validation - pre-commit hooks passed during commit - pre-push hooks passed during push - `pnpm exec prettier --check` on all changed docs files - `eslint docs/sidebars.ts` ## <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Low risk documentation-only change that adds new navigation and cross-links; primary risk is broken doc links/sidebars if an ID/path is incorrect. > > **Overview** > Adds a new `Example Migrations` docs page that curates real-world migration references (published repos and a meta issue for in-progress PRs), plus guidance on what constitutes useful proof for a migration. > > Updates the docs entry points and migration guides to link to this new page (including adding it to `docs/sidebars.ts`), adjusts `migrating-from-react-rails.md` to use a top-level `#` heading for correct Docusaurus page titles, and refreshes a couple of legacy outbound links in `misc/doctrine.md`. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit e08fa27. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup> <!-- /CURSOR_SUMMARY --> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Added an "Example Migrations" page with real-world migration references, selection criteria, migration lanes, proof requirements, and a table of active public PRs. - Enhanced migration guides with advice to pick small first slices and a maintainability-first, slice-by-slice approach for different starter setups. - Updated README links and added the new page to the migration guides sidebar. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 80242fe commit b016a75

6 files changed

Lines changed: 169 additions & 8 deletions

File tree

‎docs/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,10 +22,10 @@ React on Rails is one product with two tiers: open source for Rails + React inte
2222

2323
### Evaluating Rails + React options
2424

25-
- [Examples and migration references](https://reactonrails.com/examples)
25+
- [Example migrations](./oss/migrating/example-migrations.md) — curated migration references and proof criteria
26+
- [Examples gallery](https://reactonrails.com/examples) — reactonrails.com showcase apps
2627
- [Compare with alternatives](./oss/getting-started/comparing-react-on-rails-to-alternatives.md) — decision guide covering Hotwire, Inertia, Next.js, and more
2728
- [Migrate from react-rails](./oss/migrating/migrating-from-react-rails.md)
28-
- [Published migration example repo (Rails 7)](https://github.com/shakacode/react-on-rails-migration-example)
2929

3030
## Dive deeper when you need it
3131

‎docs/oss/migrating/example-migrations.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# Example Migrations
2+
3+
Teams evaluating React on Rails are usually not starting from a blank Rails app.
4+
5+
They already have one of these:
6+
7+
- `react-rails`
8+
- `vite_rails`
9+
- a custom Rails-side React helper
10+
11+
Some teams also arrive from Inertia-first apps. We treat those as a separate
12+
architecture case study because they are usually broader page-shell migrations,
13+
not narrow React mount migrations. If that is your starting point, begin with
14+
[Compare with alternatives](../getting-started/comparing-react-on-rails-to-alternatives.md).
15+
16+
This page tracks practical migration references for those cases.
17+
18+
## What makes a useful migration example
19+
20+
The best examples are:
21+
22+
1. Real Rails applications, not toy demos
23+
2. Small PRs that convert one page, mount point, or component boundary
24+
3. Honest about blockers such as old lockfiles, native gems, or custom frontend bridges
25+
4. Measured with before-and-after performance or maintainability notes instead of marketing claims
26+
27+
## Current public references
28+
29+
### Published example repos
30+
31+
These maintainer-owned references are the stable starting set. Add community
32+
examples here after they have landed or stabilized enough to inspect.
33+
34+
1. [react-rails example app: `react-rails-to-react-on-rails` snapshot](https://github.com/shakacode/react-rails-example-app/tree/c6b794a4b96746dbbc98a46f31119171109d70b0) —
35+
covers an older `react-rails` v3 → `react_on_rails` v13.4 migration, so treat
36+
it as a structural reference and follow current migration guides for gem and
37+
configuration specifics
38+
2. [react-on-rails-migration-example](https://github.com/shakacode/react-on-rails-migration-example) —
39+
demonstrates a Rails 7-era `react-rails` → `react_on_rails` migration with
40+
Shakapacker client/server bundles and SSR setup, based on
41+
[ganchdev/react-rails-example](https://github.com/ganchdev/react-rails-example)
42+
43+
### In-progress migration work
44+
45+
In-progress third-party migration PRs are tracked in the
46+
[example-migrations meta issue](https://github.com/shakacode/react_on_rails/issues/3125)
47+
instead of this docs page.
48+
49+
That keeps the public docs focused on durable references while the meta issue can
50+
carry working notes about draft PRs, maintainer coordination, blockers, and proof
51+
artifacts that may change quickly.
52+
53+
When a public migration becomes a stable reference, add it to the published example
54+
list above with a short proof note.
55+
56+
## Example categories
57+
58+
### `react-rails` to React on Rails
59+
60+
This is usually the cleanest migration path: primarily a gem swap and mount
61+
registration change while the app architecture stays intact during
62+
slice-by-slice conversion.
63+
64+
### `vite_rails` to React on Rails
65+
66+
This is more of an asset and entrypoint migration than a component rewrite: the
67+
route behavior should stay stable while registration moves into the React on
68+
Rails and Shakapacker flow.
69+
70+
### Custom Rails React bridge to React on Rails
71+
72+
This is common in mature apps that built a thin wrapper around React mounts.
73+
74+
Treat the wrapper as the migration boundary: preserve the Rails-side props
75+
contract, replace one helper-backed component first, and remove the wrapper
76+
later.
77+
78+
No dedicated guide exists yet. If your app uses this pattern and you want to
79+
contribute an example, see [Contribute an example](#contribute-an-example).
80+
The [react-rails migration guide](./migrating-from-react-rails.md) covers the
81+
nearest-neighbor mechanics for helper syntax and component registration.
82+
83+
## What counts as proof
84+
85+
Not every good migration example is performance-first.
86+
87+
When the change is performance-first, compare the same route on the baseline branch and the migration branch. At minimum, record:
88+
89+
1. Response timing
90+
2. HTML size
91+
3. Route JavaScript bytes
92+
4. Number of JS assets needed for the route
93+
5. Hydration warnings or client boot errors
94+
95+
If possible, also record browser load metrics such as FCP, LCP, CLS, and TBT,
96+
plus interaction metrics such as INP. TBT is captured by Lighthouse; INP
97+
requires field data or a real-user monitoring tool.
98+
99+
When the change is maintainability-first, record:
100+
101+
1. The custom bridge, oversized mount, or repo-specific contract that existed before the migration
102+
2. The standardized React on Rails helper or smaller boundary that replaced it
103+
3. What got easier to review, test, or evolve afterward
104+
4. The validation that supports the claim
105+
106+
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.
107+
108+
## Contribute an example
109+
110+
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:
111+
112+
1. The integration you started from, such as `react-rails`, `vite_rails`, or a custom helper
113+
2. The first slice you picked and why it was small enough to review
114+
3. The proof you captured, whether that was performance, maintainability, or both
115+
4. The validation you ran locally or in CI
116+
117+
The most useful next examples are:
118+
119+
1. `react-rails` apps that migrate one Rails-owned mount at a time
120+
2. Modern `vite_rails` apps where one Rails-owned island can move before a broader asset rewrite
121+
3. Apps with a custom Rails-side React bridge where one helper-backed boundary can be replaced before removing the wrapper
122+
4. Upgrades from older `react_on_rails` versions to current maintained defaults
123+
124+
## How to use these examples
125+
126+
Use this page together with the specific migration guide that matches your current stack:
127+
128+
1. [Migrate from `react-rails`](./migrating-from-react-rails.md)
129+
2. [Migrate from `vite_rails`](./migrating-from-vite-rails.md)
130+
131+
Other migration paths:
132+
133+
1. [Webpack to Rspack](./migrating-from-webpack-to-rspack.md)
134+
2. [Babel to SWC](./babel-to-swc-migration.md)
135+
136+
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).
137+
138+
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‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,19 @@
1-
## Migrate From react-rails
1+
# Migrate From react-rails
22

33
This migration is easiest when the app is already on a modern Rails + Shakapacker baseline.
44

5+
If you want repo-shaped references before touching your own app, start with
6+
[Example Migrations](./example-migrations.md) and then come back here for the
7+
mechanics.
8+
9+
## Choose a first slice
10+
11+
Pick a small first slice before you touch the whole app:
12+
13+
1. Prefer one Rails-owned page, island, or shell fragment over a broad page rewrite.
14+
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.
15+
3. The first PR does not need to eliminate every `react_component` call. It only needs to prove that one mount can move cleanly.
16+
517
## Preflight
618

719
Before swapping gems, check these first:
@@ -124,9 +136,7 @@ Older `react-rails` apps frequently need these additional fixes after the genera
124136
ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
125137
```
126138

127-
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.
128-
129-
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).
139+
For published repo examples, including older and Rails 7-era `react-rails` migrations, see [Example Migrations](./example-migrations.md).
130140

131141
## Practical checklist for Webpacker-era apps
132142

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

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@
22

33
This guide is for Rails apps that currently use `vite_rails` with React and want to move to React on Rails.
44

5+
If you want repo-shaped references before touching your own app, start with
6+
[Example Migrations](./example-migrations.md) and then come back here for the
7+
mechanics.
8+
59
## When this migration makes sense
610

711
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
3842

3943
For anything beyond a tiny app, prefer a route-by-route cutover instead of a big-bang rewrite.
4044

45+
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:
46+
47+
1. Replace one helper-backed component or boundary with React on Rails first.
48+
2. Keep Vite in place for the rest of the app until the narrow slice has parity.
49+
3. Treat Vite removal as a later step, not as the proof point itself.
50+
4151
## 1. Add React on Rails and Shakapacker
4252

4353
```bash
@@ -180,3 +190,5 @@ one reasonable React on Rails target is:
180190
- Turbo usage, if your app already uses it
181191

182192
The migration is mostly about asset/build integration, mounting strategy, and optional SSR capability.
193+
194+
For additional real-world migration references and active public PRs, see [Example Migrations](./example-migrations.md).

‎docs/oss/misc/doctrine.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -50,8 +50,8 @@ Here's the chef's selection from the React on Rails community:
5050
### JavaScript Tooling
5151

5252
- [Babel](https://babeljs.io/): Transpiler for ES6 into ES5 and much more.
53-
- [ESLint](http://eslint.org/)
54-
- [Webpack](http://webpack.github.io/): Generator of deployment assets and provider of hot module reloading.
53+
- [ESLint](https://eslint.org/)
54+
- [Webpack](https://webpack.js.org/): Generator of deployment assets and provider of hot module reloading.
5555

5656
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.
5757

‎docs/sidebars.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -175,6 +175,7 @@ const sidebars: SidebarsConfig = {
175175
type: 'category',
176176
label: 'Migration Guides',
177177
items: [
178+
'migrating/example-migrations',
178179
'migrating/migrating-from-react-rails',
179180
'migrating/migrating-from-vite-rails',
180181
'migrating/migrating-from-webpack-to-rspack',

0 commit comments

Comments
 (0)