From 101968a6c340dc6d25337f482b122781482cb33a Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 19 Apr 2026 00:18:23 -1000 Subject: [PATCH 01/22] Document examples catalog and naming plan --- docs/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/README.md b/docs/README.md index 1dcfdafae8..905fea26b2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -22,6 +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](./oss/getting-started/examples-and-references.md) - [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 From ac2e64dc7f3b000a9ed411763ab4c9b99154d4b4 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 19 Apr 2026 00:18:24 -1000 Subject: [PATCH 02/22] Document examples catalog and naming plan --- docs/oss/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/oss/introduction.md b/docs/oss/introduction.md index c2030ff42c..3695917754 100644 --- a/docs/oss/introduction.md +++ b/docs/oss/introduction.md @@ -72,7 +72,7 @@ Step-by-step walkthrough building a full app with Redux, routing, and deployment ### 👀 Learn by Example? - **[Spec/Dummy App](https://github.com/shakacode/react_on_rails/tree/main/react_on_rails/spec/dummy)** - Simple example in this repo -- **[Tutorial Demo App](https://github.com/shakacode/react-on-rails-demo-ssr-hmr)** - Example with SSR, HMR, and TypeScript +- **[Examples and migration references](./getting-started/examples-and-references.md)** - Maintained starters, migration references, and Pro + RSC demos - **[Live Demo with Source](https://github.com/shakacode/react-webpack-rails-tutorial)** - Full production app at [reactrails.com](https://reactrails.com) ## Popular Use Cases From 06faa3188080f7a2e2776bee7e7b95add4d6dd78 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 19 Apr 2026 00:18:26 -1000 Subject: [PATCH 03/22] Document examples catalog and naming plan --- docs/oss/getting-started/tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/oss/getting-started/tutorial.md b/docs/oss/getting-started/tutorial.md index cfa0b8a44d..fe048c3369 100644 --- a/docs/oss/getting-started/tutorial.md +++ b/docs/oss/getting-started/tutorial.md @@ -1,6 +1,6 @@ # React on Rails Basic Tutorial -_Also see the example repo of [React on Rails Tutorial With SSR, HMR fast refresh, and TypeScript](https://github.com/shakacode/react-on-rails-demo-ssr-hmr)_ +_See also [Examples and migration references](./examples-and-references.md) for the maintained tutorial demo, migration references, and current React on Rails Pro + RSC demos._ --- From a811dddc38749c0f03239214b22d5d4cc9cf4474 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 19 Apr 2026 00:18:27 -1000 Subject: [PATCH 04/22] Document examples catalog and naming plan --- docs/oss/core-concepts/react-server-rendering.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/oss/core-concepts/react-server-rendering.md b/docs/oss/core-concepts/react-server-rendering.md index d4fadcd9c1..14b1f0b666 100644 --- a/docs/oss/core-concepts/react-server-rendering.md +++ b/docs/oss/core-concepts/react-server-rendering.md @@ -4,7 +4,8 @@ See also [Client vs. Server Rendering](../core-concepts/client-vs-server-renderi ## What is the easiest way to set up a Webpack configuration for server-side-rendering? -See the example Webpack setup here: [github.com/shakacode/react-on-rails-demo-ssr-hmr](https://github.com/shakacode/react-on-rails-demo-ssr-hmr). +See the maintained SSR + HMR tutorial repo and related evaluation apps in +[Examples and migration references](../getting-started/examples-and-references.md). ## What is Server Rendering? From f9b9cb5a476c5078fd7d8d02c654d273dbb69407 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 19 Apr 2026 00:18:29 -1000 Subject: [PATCH 05/22] Document examples catalog and naming plan --- docs/oss/core-concepts/webpack-configuration.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/oss/core-concepts/webpack-configuration.md b/docs/oss/core-concepts/webpack-configuration.md index 9397727c3e..03d4b412a3 100644 --- a/docs/oss/core-concepts/webpack-configuration.md +++ b/docs/oss/core-concepts/webpack-configuration.md @@ -110,8 +110,10 @@ serverWebpackConfig.output = { **For older Shakapacker versions:** Use hardcoded paths and manual configuration as shown in the generator templates. -Per the example repo [shakacode/react-on-rails-demo-ssr-hmr](https://github.com/shakacode/react-on-rails-demo-ssr-hmr), -you should consider keeping your codebase mostly consistent with the defaults for [Shakapacker](https://github.com/shakacode/shakapacker). +Per the maintained SSR + HMR tutorial repo listed in +[Examples and migration references](../getting-started/examples-and-references.md), +you should consider keeping your codebase mostly consistent with the defaults +for [Shakapacker](https://github.com/shakacode/shakapacker). # React on Rails @@ -121,7 +123,7 @@ A key decision in your use React on Rails is whether you go with the Shakapacker ## Option 1: Default Generator Setup: Shakapacker app/javascript -Typical Shakapacker apps have a standard directory structure as documented in the [Shakapacker README](https://github.com/shakacode/shakapacker/blob/master/README.md#configuration-and-code). If you follow [the basic tutorial](../getting-started/tutorial.md), you will see this pattern in action. In order to customize the Webpack configuration, consult the [Shakapacker webpack customization docs](https://github.com/shakacode/shakapacker#webpack-configuration). +Typical Shakapacker apps have a standard directory structure as documented [here](https://github.com/shakacode/shakapacker/blob/master/README.md#configuration-and-code). If you follow [the basic tutorial](../getting-started/tutorial.md), you will see this pattern in action. In order to customize the Webpack configuration, consult the [Shakapacker webpack customization docs](https://github.com/shakacode/shakapacker#webpack-configuration). The _advantage_ of using Shakapacker to configure Webpack is that there is very little code needed to get started, and you don't need to understand really anything about Webpack customization. From 50ba3cb9452b4d4e81ac39f5156a03918ad317ad Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 19 Apr 2026 00:18:30 -1000 Subject: [PATCH 06/22] Document examples catalog and naming plan --- .../rails-webpacker-react-integration-options.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/oss/building-features/rails-webpacker-react-integration-options.md b/docs/oss/building-features/rails-webpacker-react-integration-options.md index ab6fd62f3d..b30edb7056 100644 --- a/docs/oss/building-features/rails-webpacker-react-integration-options.md +++ b/docs/oss/building-features/rails-webpacker-react-integration-options.md @@ -113,7 +113,8 @@ Webpack's HMR allows the replacement of modules for React in-place without reloa [github.com/pmmmwh/react-refresh-webpack-plugin](https://github.com/pmmmwh/react-refresh-webpack-plugin) -You can see an [example commit adding this in the SSR HMR demo](https://github.com/shakacode/react-on-rails-demo-ssr-hmr/commit/7e53803fce7034f5ecff335db1f400a5743a87e7). +You can see an example commit of adding this in the maintained SSR + HMR +tutorial repo [here](https://github.com/shakacode/react_on_rails_demo_ssr_hmr/commit/7e53803fce7034f5ecff335db1f400a5743a87e7). 1. Add react refresh packages: ```bash From b163c38a907556fa97405dd3468db03fe41f3313 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 19 Apr 2026 00:18:31 -1000 Subject: [PATCH 07/22] Document examples catalog and naming plan --- .../examples-and-references.md | 86 +++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 docs/oss/getting-started/examples-and-references.md diff --git a/docs/oss/getting-started/examples-and-references.md b/docs/oss/getting-started/examples-and-references.md new file mode 100644 index 0000000000..ef47f990fa --- /dev/null +++ b/docs/oss/getting-started/examples-and-references.md @@ -0,0 +1,86 @@ +# Examples and Migration References + +Use this page as the canonical index for public React on Rails reference repos. +The goal is to make evaluation, migration, and React on Rails Pro adoption easy +to navigate without scattering hard-coded repository links across the docs. + +For the curated marketing view, see +[reactonrails.com/examples](https://reactonrails.com/examples). + +## Repo Naming Pattern + +React on Rails public reference repos fall into three buckets: + +| Type | Preferred pattern | Use it for | +| -------- | --------------------------- | -------------------------------------------------------------------------- | +| Demo | `react-on-rails-demo-*` | Evaluation apps, benchmarks, feature showcases, and product comparisons | +| Example | `react-on-rails-example-*` | Focused implementation references and migration references | +| Tutorial | `react-on-rails-tutorial-*` | Step-by-step follow-along repos that map directly to docs or video lessons | + +Some current repos still use older slugs with underscores or legacy wording. +This page and the examples site are the source of truth for which public repos +are current and worth starting from. + +## Starter Repos + +### SSR + HMR Tutorial Demo + +- Repo: [shakacode/react_on_rails_demo_ssr_hmr](https://github.com/shakacode/react_on_rails_demo_ssr_hmr) +- Use it when you want the maintained Rails + React + SSR + HMR walkthrough repo + that backs the tutorial and Webpack configuration guidance. + +### React on Rails Pro + RSC Starter + +- Repo: [shakacode/react-on-rails-rsc-demo](https://github.com/shakacode/react-on-rails-rsc-demo) +- Use it when you want a minimal public sample for React Server Components with + React on Rails Pro. + +### Spec Dummy App + +- Repo: [shakacode/react_on_rails/tree/main/react_on_rails/spec/dummy](https://github.com/shakacode/react_on_rails/tree/main/react_on_rails/spec/dummy) +- Use it when you want the simplest in-repo reference for current generator and + feature behavior. + +## Migration References + +### Migrate from `react-rails` + +- Repo: [shakacode/react-on-rails-migration-example](https://github.com/shakacode/react-on-rails-migration-example) +- Use it when you want a focused before/after migration reference instead of + reconstructing the upgrade from older blog posts. + +### Open Flights Migration Example + +- Repo: [shakacode/react-on-rails-open-flights-example](https://github.com/shakacode/react-on-rails-open-flights-example) +- Use it when you want a larger example app that shows React on Rails replacing + `react-rails` in a more realistic codebase. + +## React on Rails Pro + RSC Demos + +### Hacker News RSC Demo + +- Repo: [shakacode/react-on-rails-hn-rsc-demo](https://github.com/shakacode/react-on-rails-hn-rsc-demo) +- Use it when you want a compact public demo of React on Rails Pro with React + Server Components on a familiar read-heavy UI. + +### Marketplace RSC Performance Demo + +- Repo: [shakacode/react-server-components-marketplace-demo](https://github.com/shakacode/react-server-components-marketplace-demo) +- Use it when you want a public performance-oriented RSC demo showing the shape + of the user-visible win on a marketplace-style surface. + +### Gumroad Inertia vs React on Rails Pro Comparison + +- Repo: [shakacode/gumroad-rsc](https://github.com/shakacode/gumroad-rsc) +- Use it when you want a benchmark-oriented comparison between an Inertia-style + surface and a React on Rails Pro + RSC surface on the same product domain. + +## Legacy Repos + +Version-specific demos, `test-*` repos, generator snapshots, and older tutorial +repos are useful historical references, but they are not the primary starting +point for new evaluations. + +If you are choosing a public reference repo for docs, talks, or adoption work, +start with the repos above and the curated catalog at +[reactonrails.com/examples](https://reactonrails.com/examples). From 79e11d93114ea4067df245a2f8259018b7b972ec Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 19 Apr 2026 00:18:32 -1000 Subject: [PATCH 08/22] Document examples catalog and naming plan --- .../examples-catalog-and-repo-naming-plan.md | 108 ++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 internal/planning/examples-catalog-and-repo-naming-plan.md diff --git a/internal/planning/examples-catalog-and-repo-naming-plan.md b/internal/planning/examples-catalog-and-repo-naming-plan.md new file mode 100644 index 0000000000..0d1eb2fc24 --- /dev/null +++ b/internal/planning/examples-catalog-and-repo-naming-plan.md @@ -0,0 +1,108 @@ +# Examples Catalog and Repo Naming Plan + +## Goals + +1. Make React on Rails and React on Rails Pro example repos easy to discover on + GitHub. +2. Make `reactonrails.com/examples` a clean marketing catalog rather than a + random list of historical repos. +3. Keep canonical taxonomy and example guidance in `react_on_rails/docs/`. +4. Reduce future docs churn by routing doc references through one maintained + examples page instead of repeating repo slugs everywhere. + +## Naming Decision + +Use these public repo prefixes for anything we want to market actively: + +| Type | Pattern | Why | +| -------- | --------------------------- | ----------------------------------------------------------- | +| Demo | `react-on-rails-demo-*` | Best for evaluation apps, benchmarks, and feature showcases | +| Example | `react-on-rails-example-*` | Best for focused migration and implementation references | +| Tutorial | `react-on-rails-tutorial-*` | Best for repos that map directly to docs or video lessons | + +Keep package and product repos as-is: + +- `react_on_rails` +- `react_on_rails_pro` +- `react_on_rails_rsc` + +Those names are package identities, not marketing slugs. + +## Repos to Feature Publicly + +These are the repos we should feature on `reactonrails.com/examples` and point +to from the docs: + +| Current repo | Recommended action | Proposed canonical name | Notes | +| ------------------------------------------ | ------------------ | ------------------------------------- | ----------------------------------------- | +| `react_on_rails_demo_ssr_hmr` | Rename | `react-on-rails-demo-ssr-hmr` | Maintained SSR + HMR tutorial repo | +| `react-on-rails-rsc-demo` | Rename | `react-on-rails-demo-rsc-starter` | Minimal public RSC starter | +| `react-on-rails-hn-rsc-demo` | Rename | `react-on-rails-demo-hacker-news-rsc` | Compact Pro + RSC showcase | +| `react-server-components-marketplace-demo` | Rename | `react-on-rails-demo-marketplace-rsc` | Performance-focused RSC demo | +| `gumroad-rsc` | Rename | `react-on-rails-demo-gumroad-rsc` | Inertia vs React on Rails Pro benchmark | +| `react-on-rails-migration-example` | Rename | `react-on-rails-example-migration` | Focused `react-rails` migration reference | +| `react-on-rails-open-flights-example` | Rename | `react-on-rails-example-open-flights` | Larger migration reference | +| `react_on_rails-demos` | Rename | `react-on-rails-demos` | Shared infrastructure repo for demo apps | + +## Repos to De-emphasize or Archive + +These should not appear on the primary public examples page. Some can stay +public for historical reference, but they should be archived or treated as +legacy once the current catalog is in place. + +| Repo | Recommended action | Reason | +| ---------------------------------------------------------------- | ---------------------------- | --------------------------------------------------------------- | +| `react_on_rails-hacker-news-app` | Archive or de-emphasize | Duplicate Hacker News concept; keep one canonical HN repo | +| `spike-react-on-rails-tutorial-v15-with-rspack` | De-emphasize | Useful engineering spike, weak marketing name | +| `react_on_rails-v16-generator-playground` | De-emphasize | Playground/test utility, not a user-facing example | +| `react_on_rails-demo-v16-ssr-auto-registration-bundle-splitting` | De-emphasize or rename later | Valuable topic, but current slug is too long and version-heavy | +| `react_on_rails-demo-16-4-0-rc5` | Archive | Release snapshot, not a maintained example | +| `test-react-on-rails-v12` | Archive | Version-specific test repo | +| `test-react-on-rails-v12-no-sprockets` | Archive | Version-specific test repo | +| `test-react-on-rails-plus-webpacker-v4` | Archive | Version-specific tutorial repo | +| `react_on_rails-tutorial-v11` | Archive | Older tutorial generation | +| `v8-demo` | Archive | Historical version demo | +| `old-react-on-rails-examples` | Archive | Already marked outdated by name | +| `react_on_rails-with-webpacker` | Archive | Historical integration prototype | +| `react_on_rails-update-webpack-v2` | Archive | Historical upgrade experiment | +| `react_on_rails-test-new-redux-generation` | Archive | PR-specific experiment repo | +| `react_on_rails-generator-results` | Archive | Generator output snapshot | +| `react_on_rails-generator-results-pre-0` | Archive | Generator output snapshot | +| `react_on_rails-generator-results-testing` | Archive | Generator output snapshot | +| `react_actioncable_counter` | De-emphasize | Narrow feature demo, not a primary entry point | +| `rails-tutorial-with-react-on-rails` | De-emphasize | Historical tutorial adaptation | +| `egghead-tutorial-react-on-rails-v6.3.1-create-component` | Archive or de-emphasize | Video-course artifact | +| `egghead-add-redux-component-to-react-on-rails` | Archive or de-emphasize | Video-course artifact | +| `react-webpack-rails-tutorial` | De-emphasize | Legacy full app; still useful, but not a primary modern starter | + +## Private or Internal Repos to Exclude from Public Catalog + +- `react-on-rails-template` +- `react_on_rails-demo-octochangelog-on-rails-pro` +- `react-on-rails-builds` +- `react_on_rails_pro_licensing` + +These may matter operationally, but they should not be linked from the public +examples page. + +## Docs and Site Follow-up + +1. Keep a canonical examples/reference page in `react_on_rails/docs/`. +2. Use `reactonrails.com/examples` as the marketing-forward catalog. +3. Replace hard-coded repo links in docs with the maintained examples page when + the repo itself is not the main point. +4. Update GitHub descriptions and topics for all featured repos: + - `react-on-rails` + - `react-on-rails-pro` + - `react-server-components` + - `ruby-on-rails` + - `shakapacker` + - `rspack` where applicable + - `migration`, `benchmark`, or `demo` as appropriate + +## Execution Order + +1. Update docs and `reactonrails.com/examples` first. +2. Rename active featured repos. +3. Update repo descriptions/topics. +4. Archive or de-emphasize legacy repos after the new catalog is live. From dcfe7cbf4904605f9aaa7c94fae638bb1155fc3e Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 19 Apr 2026 10:23:58 -1000 Subject: [PATCH 09/22] Fix docs catalog follow-ups --- docs/sidebars.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/sidebars.ts b/docs/sidebars.ts index 8797720bab..97c7904097 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -29,6 +29,7 @@ const sidebars: SidebarsConfig = { 'getting-started/quick-start', 'getting-started/create-react-on-rails-app', 'getting-started/tutorial', + 'getting-started/examples-and-references', 'getting-started/installation-into-an-existing-rails-app', 'getting-started/project-structure', 'getting-started/using-react-on-rails', From 9b76d47507b43b032f052b7463a6876a1d8d45c5 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 19 Apr 2026 10:34:19 -1000 Subject: [PATCH 10/22] Fix docs catalog follow-ups --- docs/oss/core-concepts/webpack-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/oss/core-concepts/webpack-configuration.md b/docs/oss/core-concepts/webpack-configuration.md index 03d4b412a3..1136a93e1e 100644 --- a/docs/oss/core-concepts/webpack-configuration.md +++ b/docs/oss/core-concepts/webpack-configuration.md @@ -123,7 +123,7 @@ A key decision in your use React on Rails is whether you go with the Shakapacker ## Option 1: Default Generator Setup: Shakapacker app/javascript -Typical Shakapacker apps have a standard directory structure as documented [here](https://github.com/shakacode/shakapacker/blob/master/README.md#configuration-and-code). If you follow [the basic tutorial](../getting-started/tutorial.md), you will see this pattern in action. In order to customize the Webpack configuration, consult the [Shakapacker webpack customization docs](https://github.com/shakacode/shakapacker#webpack-configuration). +Typical Shakapacker apps have a standard directory structure documented in the [Shakapacker README](https://github.com/shakacode/shakapacker/blob/master/README.md#configuration-and-code). If you follow [the basic tutorial](../getting-started/tutorial.md), you will see this pattern in action. In order to customize the Webpack configuration, consult the [Shakapacker webpack customization docs](https://github.com/shakacode/shakapacker#webpack-configuration). The _advantage_ of using Shakapacker to configure Webpack is that there is very little code needed to get started, and you don't need to understand really anything about Webpack customization. From b94ebfa6eeacc9738db5a0eae293c31d8917d55b Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 19 Apr 2026 10:39:21 -1000 Subject: [PATCH 11/22] Fix docs catalog follow-ups --- .../rails-webpacker-react-integration-options.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/oss/building-features/rails-webpacker-react-integration-options.md b/docs/oss/building-features/rails-webpacker-react-integration-options.md index b30edb7056..40653f9789 100644 --- a/docs/oss/building-features/rails-webpacker-react-integration-options.md +++ b/docs/oss/building-features/rails-webpacker-react-integration-options.md @@ -113,8 +113,8 @@ Webpack's HMR allows the replacement of modules for React in-place without reloa [github.com/pmmmwh/react-refresh-webpack-plugin](https://github.com/pmmmwh/react-refresh-webpack-plugin) -You can see an example commit of adding this in the maintained SSR + HMR -tutorial repo [here](https://github.com/shakacode/react_on_rails_demo_ssr_hmr/commit/7e53803fce7034f5ecff335db1f400a5743a87e7). +You can see an example commit in the maintained SSR + HMR tutorial repo that +[adds React Refresh](https://github.com/shakacode/react_on_rails_demo_ssr_hmr/commit/7e53803fce7034f5ecff335db1f400a5743a87e7). 1. Add react refresh packages: ```bash From 8c137aa97824f66ca053a6b85678abafb079ea70 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 19 Apr 2026 11:06:01 -1000 Subject: [PATCH 12/22] Tighten examples docs guidance --- .../getting-started/examples-and-references.md | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/docs/oss/getting-started/examples-and-references.md b/docs/oss/getting-started/examples-and-references.md index ef47f990fa..e6570535e1 100644 --- a/docs/oss/getting-started/examples-and-references.md +++ b/docs/oss/getting-started/examples-and-references.md @@ -7,17 +7,7 @@ to navigate without scattering hard-coded repository links across the docs. For the curated marketing view, see [reactonrails.com/examples](https://reactonrails.com/examples). -## Repo Naming Pattern - -React on Rails public reference repos fall into three buckets: - -| Type | Preferred pattern | Use it for | -| -------- | --------------------------- | -------------------------------------------------------------------------- | -| Demo | `react-on-rails-demo-*` | Evaluation apps, benchmarks, feature showcases, and product comparisons | -| Example | `react-on-rails-example-*` | Focused implementation references and migration references | -| Tutorial | `react-on-rails-tutorial-*` | Step-by-step follow-along repos that map directly to docs or video lessons | - -Some current repos still use older slugs with underscores or legacy wording. +Some public repos still use older slugs with underscores or legacy wording. This page and the examples site are the source of truth for which public repos are current and worth starting from. @@ -35,11 +25,15 @@ are current and worth starting from. - Use it when you want a minimal public sample for React Server Components with React on Rails Pro. +## In-Repo Reference + ### Spec Dummy App - Repo: [shakacode/react_on_rails/tree/main/react_on_rails/spec/dummy](https://github.com/shakacode/react_on_rails/tree/main/react_on_rails/spec/dummy) - Use it when you want the simplest in-repo reference for current generator and feature behavior. +- Note: this is the in-repo test app used by the RSpec suite, not a standalone + starter repository. ## Migration References From 3f70e77181639cb5f8be27312ded8a18d8b0f6c8 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 19 Apr 2026 11:08:07 -1000 Subject: [PATCH 13/22] Polish examples catalog docs --- .../planning/examples-catalog-and-repo-naming-plan.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/internal/planning/examples-catalog-and-repo-naming-plan.md b/internal/planning/examples-catalog-and-repo-naming-plan.md index 0d1eb2fc24..7731a63b36 100644 --- a/internal/planning/examples-catalog-and-repo-naming-plan.md +++ b/internal/planning/examples-catalog-and-repo-naming-plan.md @@ -103,6 +103,8 @@ examples page. ## Execution Order 1. Update docs and `reactonrails.com/examples` first. -2. Rename active featured repos. -3. Update repo descriptions/topics. -4. Archive or de-emphasize legacy repos after the new catalog is live. +2. After the docs PRs land and demo links are verified, open a tracking issue + for the rename/archive rollout. +3. Rename active featured repos. +4. Update repo descriptions/topics. +5. Archive or de-emphasize legacy repos after the new catalog is live. From 5b1390c1afc90ae3a19d45fb613f91d55becf67e Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 19 Apr 2026 11:08:11 -1000 Subject: [PATCH 14/22] Polish examples catalog docs --- docs/oss/introduction.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/oss/introduction.md b/docs/oss/introduction.md index 3695917754..3d2ca91e50 100644 --- a/docs/oss/introduction.md +++ b/docs/oss/introduction.md @@ -73,7 +73,6 @@ Step-by-step walkthrough building a full app with Redux, routing, and deployment - **[Spec/Dummy App](https://github.com/shakacode/react_on_rails/tree/main/react_on_rails/spec/dummy)** - Simple example in this repo - **[Examples and migration references](./getting-started/examples-and-references.md)** - Maintained starters, migration references, and Pro + RSC demos -- **[Live Demo with Source](https://github.com/shakacode/react-webpack-rails-tutorial)** - Full production app at [reactrails.com](https://reactrails.com) ## Popular Use Cases From 663587a4e1283e814d7b2715b836b0cef5c19fba Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 19 Apr 2026 11:09:24 -1000 Subject: [PATCH 15/22] Polish examples catalog docs --- docs/oss/getting-started/examples-and-references.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/oss/getting-started/examples-and-references.md b/docs/oss/getting-started/examples-and-references.md index e6570535e1..851c0587f9 100644 --- a/docs/oss/getting-started/examples-and-references.md +++ b/docs/oss/getting-started/examples-and-references.md @@ -29,7 +29,7 @@ are current and worth starting from. ### Spec Dummy App -- Repo: [shakacode/react_on_rails/tree/main/react_on_rails/spec/dummy](https://github.com/shakacode/react_on_rails/tree/main/react_on_rails/spec/dummy) +- Repo: [shakacode/react_on_rails — spec/dummy](https://github.com/shakacode/react_on_rails/tree/main/react_on_rails/spec/dummy) - Use it when you want the simplest in-repo reference for current generator and feature behavior. - Note: this is the in-repo test app used by the RSpec suite, not a standalone From 1de953b49e9ac43bb42f95656a7a58301213eea4 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 19 Apr 2026 11:21:03 -1000 Subject: [PATCH 16/22] Decouple examples docs from pending site work --- .../examples-and-references.md | 23 ++++++++----------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/docs/oss/getting-started/examples-and-references.md b/docs/oss/getting-started/examples-and-references.md index 851c0587f9..e1b1ce3eda 100644 --- a/docs/oss/getting-started/examples-and-references.md +++ b/docs/oss/getting-started/examples-and-references.md @@ -4,12 +4,9 @@ Use this page as the canonical index for public React on Rails reference repos. The goal is to make evaluation, migration, and React on Rails Pro adoption easy to navigate without scattering hard-coded repository links across the docs. -For the curated marketing view, see -[reactonrails.com/examples](https://reactonrails.com/examples). - Some public repos still use older slugs with underscores or legacy wording. -This page and the examples site are the source of truth for which public repos -are current and worth starting from. +This page is the source of truth for which public repos are current and worth +starting from. ## Starter Repos @@ -24,6 +21,8 @@ are current and worth starting from. - Repo: [shakacode/react-on-rails-rsc-demo](https://github.com/shakacode/react-on-rails-rsc-demo) - Use it when you want a minimal public sample for React Server Components with React on Rails Pro. +- Note: this repo uses React on Rails Pro. See [OSS vs Pro](./oss-vs-pro.md) + for evaluation guidance. ## In-Repo Reference @@ -51,6 +50,9 @@ are current and worth starting from. ## React on Rails Pro + RSC Demos +> **Note:** The repos below use React on Rails Pro. See [OSS vs Pro](./oss-vs-pro.md) +> for evaluation guidance. + ### Hacker News RSC Demo - Repo: [shakacode/react-on-rails-hn-rsc-demo](https://github.com/shakacode/react-on-rails-hn-rsc-demo) @@ -63,18 +65,13 @@ are current and worth starting from. - Use it when you want a public performance-oriented RSC demo showing the shape of the user-visible win on a marketplace-style surface. -### Gumroad Inertia vs React on Rails Pro Comparison - -- Repo: [shakacode/gumroad-rsc](https://github.com/shakacode/gumroad-rsc) -- Use it when you want a benchmark-oriented comparison between an Inertia-style - surface and a React on Rails Pro + RSC surface on the same product domain. - ## Legacy Repos Version-specific demos, `test-*` repos, generator snapshots, and older tutorial repos are useful historical references, but they are not the primary starting point for new evaluations. +- Legacy full app: [shakacode/react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial) — older production-style app with a [live demo at reactrails.com](https://reactrails.com). Still useful as a historical reference, but not the recommended starting point for new projects. + If you are choosing a public reference repo for docs, talks, or adoption work, -start with the repos above and the curated catalog at -[reactonrails.com/examples](https://reactonrails.com/examples). +start with the repos above. From 75fc22c4fc702f59bbeeb497b0421e03a0804de6 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Sun, 19 Apr 2026 11:21:06 -1000 Subject: [PATCH 17/22] Decouple examples docs from pending site work --- .../examples-catalog-and-repo-naming-plan.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/internal/planning/examples-catalog-and-repo-naming-plan.md b/internal/planning/examples-catalog-and-repo-naming-plan.md index 7731a63b36..d75de1ef93 100644 --- a/internal/planning/examples-catalog-and-repo-naming-plan.md +++ b/internal/planning/examples-catalog-and-repo-naming-plan.md @@ -75,15 +75,11 @@ legacy once the current catalog is in place. | `egghead-add-redux-component-to-react-on-rails` | Archive or de-emphasize | Video-course artifact | | `react-webpack-rails-tutorial` | De-emphasize | Legacy full app; still useful, but not a primary modern starter | -## Private or Internal Repos to Exclude from Public Catalog +## Internal Repos -- `react-on-rails-template` -- `react_on_rails-demo-octochangelog-on-rails-pro` -- `react-on-rails-builds` -- `react_on_rails_pro_licensing` - -These may matter operationally, but they should not be linked from the public -examples page. +Operational or private repos can matter for maintenance work, but they should +not appear in public catalogs or public-facing docs. Keep those references in +private planning material only. ## Docs and Site Follow-up From 746ab34ea2e324528627593a69a8a84acd135afe Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Wed, 22 Apr 2026 21:26:28 -1000 Subject: [PATCH 18/22] Normalize examples catalog repo slugs --- docs/README.md | 2 +- ...ils-webpacker-react-integration-options.md | 2 +- .../examples-and-references.md | 21 ++++++++++---- .../examples-catalog-and-repo-naming-plan.md | 29 +++++++++---------- 4 files changed, 32 insertions(+), 22 deletions(-) diff --git a/docs/README.md b/docs/README.md index 905fea26b2..e4fddb9f72 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](./oss/getting-started/examples-and-references.md) +- [Examples and migration references](./oss/getting-started/examples-and-references.md) — maintained starters, migration repos, and Pro + RSC demos - [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 diff --git a/docs/oss/building-features/rails-webpacker-react-integration-options.md b/docs/oss/building-features/rails-webpacker-react-integration-options.md index 40653f9789..b74f44764e 100644 --- a/docs/oss/building-features/rails-webpacker-react-integration-options.md +++ b/docs/oss/building-features/rails-webpacker-react-integration-options.md @@ -114,7 +114,7 @@ Webpack's HMR allows the replacement of modules for React in-place without reloa [github.com/pmmmwh/react-refresh-webpack-plugin](https://github.com/pmmmwh/react-refresh-webpack-plugin) You can see an example commit in the maintained SSR + HMR tutorial repo that -[adds React Refresh](https://github.com/shakacode/react_on_rails_demo_ssr_hmr/commit/7e53803fce7034f5ecff335db1f400a5743a87e7). +[adds React Refresh](https://github.com/shakacode/react-on-rails-demo-ssr-hmr/commit/7e53803fce7034f5ecff335db1f400a5743a87e7). 1. Add react refresh packages: ```bash diff --git a/docs/oss/getting-started/examples-and-references.md b/docs/oss/getting-started/examples-and-references.md index e1b1ce3eda..0c92ee0253 100644 --- a/docs/oss/getting-started/examples-and-references.md +++ b/docs/oss/getting-started/examples-and-references.md @@ -12,7 +12,7 @@ starting from. ### SSR + HMR Tutorial Demo -- Repo: [shakacode/react_on_rails_demo_ssr_hmr](https://github.com/shakacode/react_on_rails_demo_ssr_hmr) +- Repo: [shakacode/react-on-rails-demo-ssr-hmr](https://github.com/shakacode/react-on-rails-demo-ssr-hmr) - Use it when you want the maintained Rails + React + SSR + HMR walkthrough repo that backs the tutorial and Webpack configuration guidance. @@ -36,15 +36,18 @@ starting from. ## Migration References +For detailed proof criteria and migration contribution guidance, see +[Example Migrations](../migrating/example-migrations.md). + ### Migrate from `react-rails` -- Repo: [shakacode/react-on-rails-migration-example](https://github.com/shakacode/react-on-rails-migration-example) +- Repo: [shakacode/react-on-rails-example-migration](https://github.com/shakacode/react-on-rails-example-migration) - Use it when you want a focused before/after migration reference instead of reconstructing the upgrade from older blog posts. ### Open Flights Migration Example -- Repo: [shakacode/react-on-rails-open-flights-example](https://github.com/shakacode/react-on-rails-open-flights-example) +- Repo: [shakacode/react-on-rails-example-open-flights](https://github.com/shakacode/react-on-rails-example-open-flights) - Use it when you want a larger example app that shows React on Rails replacing `react-rails` in a more realistic codebase. @@ -55,16 +58,24 @@ starting from. ### Hacker News RSC Demo -- Repo: [shakacode/react-on-rails-hn-rsc-demo](https://github.com/shakacode/react-on-rails-hn-rsc-demo) +- Repo: [shakacode/react-on-rails-demo-hacker-news-rsc](https://github.com/shakacode/react-on-rails-demo-hacker-news-rsc) - Use it when you want a compact public demo of React on Rails Pro with React Server Components on a familiar read-heavy UI. ### Marketplace RSC Performance Demo -- Repo: [shakacode/react-server-components-marketplace-demo](https://github.com/shakacode/react-server-components-marketplace-demo) +- Repo: [shakacode/react-on-rails-demo-marketplace-rsc](https://github.com/shakacode/react-on-rails-demo-marketplace-rsc) - Use it when you want a public performance-oriented RSC demo showing the shape of the user-visible win on a marketplace-style surface. +### Gumroad-Style RSC Benchmark Demo + +- Repo: [shakacode/react-on-rails-demo-gumroad-rsc](https://github.com/shakacode/react-on-rails-demo-gumroad-rsc) +- Use it when you want a benchmark-oriented comparison between an Inertia-style + surface and a React on Rails Pro + RSC surface on the same product domain. +- Note: this is a ShakaCode-built demo modeled on a Gumroad-style UI, not an + official Gumroad product or integration. + ## Legacy Repos Version-specific demos, `test-*` repos, generator snapshots, and older tutorial diff --git a/internal/planning/examples-catalog-and-repo-naming-plan.md b/internal/planning/examples-catalog-and-repo-naming-plan.md index d75de1ef93..d429c20fbb 100644 --- a/internal/planning/examples-catalog-and-repo-naming-plan.md +++ b/internal/planning/examples-catalog-and-repo-naming-plan.md @@ -33,16 +33,16 @@ Those names are package identities, not marketing slugs. These are the repos we should feature on `reactonrails.com/examples` and point to from the docs: -| Current repo | Recommended action | Proposed canonical name | Notes | -| ------------------------------------------ | ------------------ | ------------------------------------- | ----------------------------------------- | -| `react_on_rails_demo_ssr_hmr` | Rename | `react-on-rails-demo-ssr-hmr` | Maintained SSR + HMR tutorial repo | -| `react-on-rails-rsc-demo` | Rename | `react-on-rails-demo-rsc-starter` | Minimal public RSC starter | -| `react-on-rails-hn-rsc-demo` | Rename | `react-on-rails-demo-hacker-news-rsc` | Compact Pro + RSC showcase | -| `react-server-components-marketplace-demo` | Rename | `react-on-rails-demo-marketplace-rsc` | Performance-focused RSC demo | -| `gumroad-rsc` | Rename | `react-on-rails-demo-gumroad-rsc` | Inertia vs React on Rails Pro benchmark | -| `react-on-rails-migration-example` | Rename | `react-on-rails-example-migration` | Focused `react-rails` migration reference | -| `react-on-rails-open-flights-example` | Rename | `react-on-rails-example-open-flights` | Larger migration reference | -| `react_on_rails-demos` | Rename | `react-on-rails-demos` | Shared infrastructure repo for demo apps | +| Public repo | Recommended action | Canonical status | Notes | +| ------------------------------------- | ------------------ | ------------------------- | ----------------------------------------- | +| `react-on-rails-demo-ssr-hmr` | Feature | Rename completed | Maintained SSR + HMR tutorial repo | +| `react-on-rails-rsc-demo` | Feature | Keep current slug for now | Minimal public RSC starter | +| `react-on-rails-demo-hacker-news-rsc` | Feature | Rename completed | Compact Pro + RSC showcase | +| `react-on-rails-demo-marketplace-rsc` | Feature | Rename completed | Performance-focused RSC demo | +| `react-on-rails-demo-gumroad-rsc` | Feature | Rename completed | Inertia vs React on Rails Pro benchmark | +| `react-on-rails-example-migration` | Feature | Rename completed | Focused `react-rails` migration reference | +| `react-on-rails-example-open-flights` | Feature | Rename completed | Larger migration reference | +| `react-on-rails-demos` | Feature | Rename completed | Shared infrastructure repo for demo apps | ## Repos to De-emphasize or Archive @@ -99,8 +99,7 @@ private planning material only. ## Execution Order 1. Update docs and `reactonrails.com/examples` first. -2. After the docs PRs land and demo links are verified, open a tracking issue - for the rename/archive rollout. -3. Rename active featured repos. -4. Update repo descriptions/topics. -5. Archive or de-emphasize legacy repos after the new catalog is live. +2. Verify GitHub redirects for completed renames before removing any legacy + slugs from docs or issue references. +3. Update repo descriptions and topics. +4. Archive or de-emphasize legacy repos after the new catalog is live. From 8fbf3d330f155d6703830b523cae8bf043172c52 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Fri, 24 Apr 2026 20:11:13 -1000 Subject: [PATCH 19/22] Address optional review nits on examples catalog - Note the rsc-demo slug exception in the public docs and prefer linking the docs page over the repo URL. - Point contributors from the public Legacy Repos section to the internal examples-catalog and repo-naming plan. - Add a Target slug column to the planning table so the rsc-demo exception is visible at a glance. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../examples-and-references.md | 8 ++++++++ .../examples-catalog-and-repo-naming-plan.md | 20 +++++++++---------- 2 files changed, 18 insertions(+), 10 deletions(-) diff --git a/docs/oss/getting-started/examples-and-references.md b/docs/oss/getting-started/examples-and-references.md index 0c92ee0253..a0700a6e51 100644 --- a/docs/oss/getting-started/examples-and-references.md +++ b/docs/oss/getting-started/examples-and-references.md @@ -23,6 +23,10 @@ starting from. React on Rails Pro. - Note: this repo uses React on Rails Pro. See [OSS vs Pro](./oss-vs-pro.md) for evaluation guidance. +- Note: this slug predates the `react-on-rails-demo-*` naming convention used + by the other demos on this page. It may be renamed to + `react-on-rails-demo-rsc` in a future cleanup, so prefer linking to this + docs page rather than the repo URL directly. ## In-Repo Reference @@ -84,5 +88,9 @@ point for new evaluations. - Legacy full app: [shakacode/react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial) — older production-style app with a [live demo at reactrails.com](https://reactrails.com). Still useful as a historical reference, but not the recommended starting point for new projects. +For the full list of repos being de-emphasized or archived, see the internal +[examples-catalog and repo-naming plan](../../../internal/planning/examples-catalog-and-repo-naming-plan.md) +in this repository. + If you are choosing a public reference repo for docs, talks, or adoption work, start with the repos above. diff --git a/internal/planning/examples-catalog-and-repo-naming-plan.md b/internal/planning/examples-catalog-and-repo-naming-plan.md index d429c20fbb..37719690d1 100644 --- a/internal/planning/examples-catalog-and-repo-naming-plan.md +++ b/internal/planning/examples-catalog-and-repo-naming-plan.md @@ -33,16 +33,16 @@ Those names are package identities, not marketing slugs. These are the repos we should feature on `reactonrails.com/examples` and point to from the docs: -| Public repo | Recommended action | Canonical status | Notes | -| ------------------------------------- | ------------------ | ------------------------- | ----------------------------------------- | -| `react-on-rails-demo-ssr-hmr` | Feature | Rename completed | Maintained SSR + HMR tutorial repo | -| `react-on-rails-rsc-demo` | Feature | Keep current slug for now | Minimal public RSC starter | -| `react-on-rails-demo-hacker-news-rsc` | Feature | Rename completed | Compact Pro + RSC showcase | -| `react-on-rails-demo-marketplace-rsc` | Feature | Rename completed | Performance-focused RSC demo | -| `react-on-rails-demo-gumroad-rsc` | Feature | Rename completed | Inertia vs React on Rails Pro benchmark | -| `react-on-rails-example-migration` | Feature | Rename completed | Focused `react-rails` migration reference | -| `react-on-rails-example-open-flights` | Feature | Rename completed | Larger migration reference | -| `react-on-rails-demos` | Feature | Rename completed | Shared infrastructure repo for demo apps | +| Public repo | Recommended action | Canonical status | Target slug | Notes | +| ------------------------------------- | ------------------ | ------------------------- | ---------------------------------- | ----------------------------------------- | +| `react-on-rails-demo-ssr-hmr` | Feature | Rename completed | (current) | Maintained SSR + HMR tutorial repo | +| `react-on-rails-rsc-demo` | Feature | Keep current slug for now | `react-on-rails-demo-rsc` (future) | Minimal public RSC starter | +| `react-on-rails-demo-hacker-news-rsc` | Feature | Rename completed | (current) | Compact Pro + RSC showcase | +| `react-on-rails-demo-marketplace-rsc` | Feature | Rename completed | (current) | Performance-focused RSC demo | +| `react-on-rails-demo-gumroad-rsc` | Feature | Rename completed | (current) | Inertia vs React on Rails Pro benchmark | +| `react-on-rails-example-migration` | Feature | Rename completed | (current) | Focused `react-rails` migration reference | +| `react-on-rails-example-open-flights` | Feature | Rename completed | (current) | Larger migration reference | +| `react-on-rails-demos` | Feature | Rename completed | (current) | Shared infrastructure repo for demo apps | ## Repos to De-emphasize or Archive From 06a8475ab77d3aeea05032d5222475cfa10ba63f Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Tue, 28 Apr 2026 20:31:11 -1000 Subject: [PATCH 20/22] Remove internal planning link from public examples docs The public examples-and-references page linked to internal/planning/examples-catalog-and-repo-naming-plan.md, but internal/ is explicitly excluded from the published docs site (see internal/README.md). The relative link only resolved on GitHub and was a dead link for users on the docs site. Drop the paragraph since the planning doc is contributor-facing, not user-facing. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/oss/getting-started/examples-and-references.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/oss/getting-started/examples-and-references.md b/docs/oss/getting-started/examples-and-references.md index a0700a6e51..4cfe1bada0 100644 --- a/docs/oss/getting-started/examples-and-references.md +++ b/docs/oss/getting-started/examples-and-references.md @@ -88,9 +88,5 @@ point for new evaluations. - Legacy full app: [shakacode/react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial) — older production-style app with a [live demo at reactrails.com](https://reactrails.com). Still useful as a historical reference, but not the recommended starting point for new projects. -For the full list of repos being de-emphasized or archived, see the internal -[examples-catalog and repo-naming plan](../../../internal/planning/examples-catalog-and-repo-naming-plan.md) -in this repository. - If you are choosing a public reference repo for docs, talks, or adoption work, start with the repos above. From 504de32fc6dd0e41ac0dd7144a2aedb1a1c196fe Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Tue, 28 Apr 2026 22:18:09 -1000 Subject: [PATCH 21/22] Address examples catalog review feedback - Remove the future-rename caveat from the public RSC starter entry; the rename is unscheduled and the caveat undercuts the page's "link here, not the repo" guidance. Tracking stays in the internal plan only. - Tag each starter repo with "(open source)" / "(Pro)" and add a one-line signal under the heading so readers know up front which entry needs a Pro license before they scan the per-entry notes. - Trim the Migration References subsections to a single bulleted list; the detailed proof criteria live in example-migrations.md and the cross-link is already at the section top. - Restore reactrails.com as a first-class entry by adding a Live Demos subsection above Legacy Repos and a direct intro-page link, so the only click-through-in-browser demo is not buried under "Legacy". - Move react-on-rails-demos out of the public-feature table in the plan and document it under Internal Repos so the plan and public catalog stay in sync. --- .../examples-and-references.md | 36 +++++++++---------- docs/oss/introduction.md | 1 + .../examples-catalog-and-repo-naming-plan.md | 5 ++- 3 files changed, 23 insertions(+), 19 deletions(-) diff --git a/docs/oss/getting-started/examples-and-references.md b/docs/oss/getting-started/examples-and-references.md index 4cfe1bada0..ef7997f179 100644 --- a/docs/oss/getting-started/examples-and-references.md +++ b/docs/oss/getting-started/examples-and-references.md @@ -10,23 +10,22 @@ starting from. ## Starter Repos -### SSR + HMR Tutorial Demo +One starter repo is fully open source; one requires React on Rails Pro — +check each entry's note before evaluating. + +### SSR + HMR Tutorial Demo (open source) - Repo: [shakacode/react-on-rails-demo-ssr-hmr](https://github.com/shakacode/react-on-rails-demo-ssr-hmr) - Use it when you want the maintained Rails + React + SSR + HMR walkthrough repo that backs the tutorial and Webpack configuration guidance. -### React on Rails Pro + RSC Starter +### React on Rails Pro + RSC Starter (Pro) - Repo: [shakacode/react-on-rails-rsc-demo](https://github.com/shakacode/react-on-rails-rsc-demo) - Use it when you want a minimal public sample for React Server Components with React on Rails Pro. - Note: this repo uses React on Rails Pro. See [OSS vs Pro](./oss-vs-pro.md) for evaluation guidance. -- Note: this slug predates the `react-on-rails-demo-*` naming convention used - by the other demos on this page. It may be renamed to - `react-on-rails-demo-rsc` in a future cleanup, so prefer linking to this - docs page rather than the repo URL directly. ## In-Repo Reference @@ -43,17 +42,11 @@ starting from. For detailed proof criteria and migration contribution guidance, see [Example Migrations](../migrating/example-migrations.md). -### Migrate from `react-rails` - -- Repo: [shakacode/react-on-rails-example-migration](https://github.com/shakacode/react-on-rails-example-migration) -- Use it when you want a focused before/after migration reference instead of - reconstructing the upgrade from older blog posts. - -### Open Flights Migration Example - -- Repo: [shakacode/react-on-rails-example-open-flights](https://github.com/shakacode/react-on-rails-example-open-flights) -- Use it when you want a larger example app that shows React on Rails replacing - `react-rails` in a more realistic codebase. +- [shakacode/react-on-rails-example-migration](https://github.com/shakacode/react-on-rails-example-migration) — + focused before/after `react-rails` → React on Rails migration reference. +- [shakacode/react-on-rails-example-open-flights](https://github.com/shakacode/react-on-rails-example-open-flights) — + larger example app that shows React on Rails replacing `react-rails` in a + more realistic codebase. ## React on Rails Pro + RSC Demos @@ -80,13 +73,20 @@ For detailed proof criteria and migration contribution guidance, see - Note: this is a ShakaCode-built demo modeled on a Gumroad-style UI, not an official Gumroad product or integration. +## Live Demos + +- [reactrails.com](https://reactrails.com) — production-style React on Rails app + you can click through in your browser without any local setup. Backed by the + legacy [shakacode/react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial) + source. + ## Legacy Repos Version-specific demos, `test-*` repos, generator snapshots, and older tutorial repos are useful historical references, but they are not the primary starting point for new evaluations. -- Legacy full app: [shakacode/react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial) — older production-style app with a [live demo at reactrails.com](https://reactrails.com). Still useful as a historical reference, but not the recommended starting point for new projects. +- Legacy full app: [shakacode/react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial) — older production-style app (see Live Demos above for the running site at reactrails.com). Still useful as a historical reference, but not the recommended starting point for new projects. If you are choosing a public reference repo for docs, talks, or adoption work, start with the repos above. diff --git a/docs/oss/introduction.md b/docs/oss/introduction.md index 3d2ca91e50..f8e2d41d80 100644 --- a/docs/oss/introduction.md +++ b/docs/oss/introduction.md @@ -73,6 +73,7 @@ Step-by-step walkthrough building a full app with Redux, routing, and deployment - **[Spec/Dummy App](https://github.com/shakacode/react_on_rails/tree/main/react_on_rails/spec/dummy)** - Simple example in this repo - **[Examples and migration references](./getting-started/examples-and-references.md)** - Maintained starters, migration references, and Pro + RSC demos +- **[Live demo at reactrails.com](https://reactrails.com)** - Running React on Rails app you can click through without local setup ## Popular Use Cases diff --git a/internal/planning/examples-catalog-and-repo-naming-plan.md b/internal/planning/examples-catalog-and-repo-naming-plan.md index 37719690d1..61400e4df1 100644 --- a/internal/planning/examples-catalog-and-repo-naming-plan.md +++ b/internal/planning/examples-catalog-and-repo-naming-plan.md @@ -42,7 +42,6 @@ to from the docs: | `react-on-rails-demo-gumroad-rsc` | Feature | Rename completed | (current) | Inertia vs React on Rails Pro benchmark | | `react-on-rails-example-migration` | Feature | Rename completed | (current) | Focused `react-rails` migration reference | | `react-on-rails-example-open-flights` | Feature | Rename completed | (current) | Larger migration reference | -| `react-on-rails-demos` | Feature | Rename completed | (current) | Shared infrastructure repo for demo apps | ## Repos to De-emphasize or Archive @@ -81,6 +80,10 @@ Operational or private repos can matter for maintenance work, but they should not appear in public catalogs or public-facing docs. Keep those references in private planning material only. +- `react-on-rails-demos` — shared infrastructure repo for demo apps. Rename + completed, but it is not a stand-alone evaluation target, so it stays out of + the public examples page. + ## Docs and Site Follow-up 1. Keep a canonical examples/reference page in `react_on_rails/docs/`. From e397f66f2750990057f6833625996d786a8a2b13 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Tue, 28 Apr 2026 22:43:41 -1000 Subject: [PATCH 22/22] Address round 5 review nits on examples catalog - Add react-on-rails-example-open-flights to example-migrations.md so the migration page matches the catalog. - Add a "See also" cross-link from example-migrations.md back to the new examples-and-references catalog page. - Drop the hardcoded "one OSS / one Pro" starter count and lead with the per-entry note guidance so the prose does not silently go stale. - Note the pending react-on-rails-rsc-demo slug rename inline so anyone editing the catalog later sees the tracking pointer alongside the link. - Manually wrap the long Legacy Repos line at ~80 chars to match the rest of the file. - Move examples-and-references right after quick-start in the sidebar so early-evaluation users see the index before the deeper getting-started pages. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/oss/getting-started/examples-and-references.md | 10 +++++++--- docs/oss/migrating/example-migrations.md | 8 ++++++++ docs/sidebars.ts | 2 +- 3 files changed, 16 insertions(+), 4 deletions(-) diff --git a/docs/oss/getting-started/examples-and-references.md b/docs/oss/getting-started/examples-and-references.md index ef7997f179..65397362c9 100644 --- a/docs/oss/getting-started/examples-and-references.md +++ b/docs/oss/getting-started/examples-and-references.md @@ -10,8 +10,8 @@ starting from. ## Starter Repos -One starter repo is fully open source; one requires React on Rails Pro — -check each entry's note before evaluating. +Check each entry's note before evaluating — some starters are fully open +source, while others require React on Rails Pro. ### SSR + HMR Tutorial Demo (open source) @@ -22,6 +22,8 @@ check each entry's note before evaluating. ### React on Rails Pro + RSC Starter (Pro) - Repo: [shakacode/react-on-rails-rsc-demo](https://github.com/shakacode/react-on-rails-rsc-demo) + _(slug rename to `react-on-rails-demo-rsc` pending — update this line when the + rename completes)_ - Use it when you want a minimal public sample for React Server Components with React on Rails Pro. - Note: this repo uses React on Rails Pro. See [OSS vs Pro](./oss-vs-pro.md) @@ -86,7 +88,9 @@ Version-specific demos, `test-*` repos, generator snapshots, and older tutorial repos are useful historical references, but they are not the primary starting point for new evaluations. -- Legacy full app: [shakacode/react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial) — older production-style app (see Live Demos above for the running site at reactrails.com). Still useful as a historical reference, but not the recommended starting point for new projects. +- Legacy full app: [shakacode/react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial) — + older production-style app (see Live Demos above for the running site at reactrails.com). + Still useful as a historical reference, but not the recommended starting point for new projects. If you are choosing a public reference repo for docs, talks, or adoption work, start with the repos above. diff --git a/docs/oss/migrating/example-migrations.md b/docs/oss/migrating/example-migrations.md index 7d64c71eac..20c36b0182 100644 --- a/docs/oss/migrating/example-migrations.md +++ b/docs/oss/migrating/example-migrations.md @@ -1,5 +1,9 @@ # Example Migrations +> **See also:** [Examples and Migration References](../getting-started/examples-and-references.md) +> for the broader index of public reference repos (starters, in-repo samples, RSC demos, +> and live demos). This page focuses specifically on migration references. + Teams evaluating React on Rails are usually not starting from a blank Rails app. They already have one of these: @@ -39,6 +43,10 @@ examples here after they have landed or stabilized enough to inspect. 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) +3. [react-on-rails-example-open-flights](https://github.com/shakacode/react-on-rails-example-open-flights) — + larger example app that shows React on Rails replacing `react-rails` in a + more realistic codebase, useful when the smaller migration above does not + match the scale of your application ### In-progress migration work diff --git a/docs/sidebars.ts b/docs/sidebars.ts index 97c7904097..55845db0f0 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -27,9 +27,9 @@ const sidebars: SidebarsConfig = { collapsed: false, items: [ 'getting-started/quick-start', + 'getting-started/examples-and-references', 'getting-started/create-react-on-rails-app', 'getting-started/tutorial', - 'getting-started/examples-and-references', 'getting-started/installation-into-an-existing-rails-app', 'getting-started/project-structure', 'getting-started/using-react-on-rails',