shakacode · justin808 · Apr 19, 2026 · Apr 19, 2026 · Apr 19, 2026 · Apr 19, 2026
diff --git 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) — 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
@@ -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 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

diff --git 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?
 

diff --git 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 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.
 

diff --git a/docs/oss/getting-started/examples-and-references.md b/docs/oss/getting-started/examples-and-references.md
@@ -0,0 +1,92 @@
+# 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.
+
+Some public repos still use older slugs with underscores or legacy wording.
+This page is 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.
+- 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
+
+### Spec Dummy App
+
+- 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
+  starter repository.
+
+## 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-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.
+
+## 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-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-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
+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.
diff --git 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._
 
 ---
 

diff --git a/docs/oss/introduction.md b/docs/oss/introduction.md
@@ -72,8 +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
-- **[Live Demo with Source](https://github.com/shakacode/react-webpack-rails-tutorial)** - Full production app at [reactrails.com](https://reactrails.com)
+- **[Examples and migration references](./getting-started/examples-and-references.md)** - Maintained starters, migration references, and Pro + RSC demos
 
 ## Popular Use Cases
 

diff --git 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',

diff --git a/internal/planning/examples-catalog-and-repo-naming-plan.md b/internal/planning/examples-catalog-and-repo-naming-plan.md
@@ -0,0 +1,105 @@
+# 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:
+
+| 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
+
+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 |
+
+## Internal Repos
+
+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
+
+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. 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.