diff --git a/docs/README.md b/docs/README.md index 1dcfdafae8..e4fddb9f72 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) — 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 ab6fd62f3d..b74f44764e 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 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 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? diff --git a/docs/oss/core-concepts/webpack-configuration.md b/docs/oss/core-concepts/webpack-configuration.md index 9397727c3e..1136a93e1e 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 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 new file mode 100644 index 0000000000..65397362c9 --- /dev/null +++ b/docs/oss/getting-started/examples-and-references.md @@ -0,0 +1,96 @@ +# 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 + +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) + +- 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 (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) + for evaluation guidance. + +## 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). + +- [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 + +> **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. + +## 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 (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/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._ --- diff --git a/docs/oss/introduction.md b/docs/oss/introduction.md index c2030ff42c..f8e2d41d80 100644 --- a/docs/oss/introduction.md +++ b/docs/oss/introduction.md @@ -72,8 +72,8 @@ 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 +- **[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/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 8797720bab..55845db0f0 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -27,6 +27,7 @@ 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/installation-into-an-existing-rails-app', 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..61400e4df1 --- /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: + +| 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 | + +## 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. + +- `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/`. +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.