internal/analysis/hichee-9513-rsc-backport-matrix.md
This matrix triages lessons from shakacode/hichee#9513 before any React on Rails contributor
copies app code. The core rule: treat HiChee #9513 as a case study, not a source patch. Its
controllers, routes, CMS data, ReScript modules, image signing setup, Rspack split behavior, local
scripts, auth/currency/search side effects, and visual parity fixtures are HiChee-specific unless a
follow-up issue designs a portable abstraction.
react_on_rails_rsc.| HiChee #9513 artifact | Classification | Target issue/repo | Why | Risks if copied directly | Suggested next action | Verification |
|---|---|---|---|---|---|---|
optimize-rsc-performance skill from shakacode/hichee#9544 | Portable docs/skill | #4298 | The evidence loop is reusable: local control/experiment runs, visual checks, archived benchmark output, and package-stack discipline. | HiChee commands, routes, and secret/image setup would confuse React on Rails contributors. | Adapt to React on Rails terminology, link related issues, and validate the skill in this repo. | Skill validator when available, plus git diff --check. |
| ShakaPerf visual and performance validation workflow | Portable docs/skill | #4299 | The validation method is portable docs guidance even if ShakaPerf is an internal tool. | Reviewers may infer ShakaPerf is mandatory, or that production/review-app Lighthouse is never useful context. | Document tool-aware but tool-agnostic methodology with visual parity, local A/B caveats, and required metrics. | Docs formatter and git diff --check; no runtime tests unless examples are added. |
| Static RSC shell plus tiny sidecar architecture | Framework API candidate | #4300, #4297, react_on_rails_rsc#145 | The pattern is broadly useful for mostly-static public pages that need tiny progressive enhancement, starting as docs. | HiChee auth, search, currency, navbar, CSS, and vendor split assumptions would become misleading framework guidance. | Write generic docs first; separately decide whether React on Rails or the RSC package should expose helpers. | Formatting checks for docs; targeted dummy-app/E2E checks only if an executable example is introduced. |
clientReferences = [] / narrow client-reference discovery workaround | RSC package candidate | #4301, react_on_rails_rsc#134, react_on_rails_rsc#145 | Static pages need route-scoped manifests or another scoped discovery mechanism; this repo should carry the docs warning first. | Future RSC client islands can fail because the manifest lacks required client references. | Document the trap in this repo, then implement route/page/entry-scoped manifests in react_on_rails_rsc. | Docs formatter and manifest/client-island smoke coverage for package work. |
config/initializers/static_rsc_component_rendering.rb | Do not copy until designed | #4295 | Cached static RSC output could be a future Framework API candidate after cache and payload design. | The initializer depends on private Pro behavior, app cache keys, payload stripping, release invalidation, and page metadata assumptions. | Design a first-class cached RSC helper or documented pattern with cache-key, payload, metadata, and asset invalidation semantics. | API docs plus focused specs/benchmarks once behavior is implemented. |
withRscServerLayout and initLayoutState | HiChee-only | Existing context/concurrency discussion; #4265 is closed | The framework lesson is that RSC entries may need per-request layout context. | Module-level mutable state can become unsafe under future concurrent renderers and is tied to HiChee ReScript initialization. | Do not copy; document the principle only if context/concurrency guidance is reopened. | Documentation review; runtime tests only for a designed context API. |
PublicPageStaticChrome and static navbar/search components | HiChee-only | #4300 as conceptual source only | Static chrome is a useful concept, but the actual UI is product-specific; it could inform a rewritten fixture later. | A copied example would include irrelevant branding, search behavior, CSS, and product flows. | If executable docs are desired, rewrite a tiny generic static shell from scratch. | Visual and interaction smoke checks for any rewritten fixture. |
public-page-client-effects sidecar implementation | Example/fixture candidate | #4300, react_on_rails_rsc#145 | Intent hydration and JSON props handoff are reusable ideas, but only after a generic rewrite. | App-specific selectors, auth/currency/search flows, and dependency graph would mislead users. | Document the generic sidecar pattern; optionally add a tiny fixture with one lazy client island. | Docs formatting; targeted E2E or system spec only if a fixture lands. |
Rspack splitChunks and vendor sidecar tweaks | Do not copy until designed | #4111, #4301, react_on_rails_rsc#134 | #9513 exposed that split strategies can affect RSC hydration and client-reference cost. | Ad hoc vendor changes can produce hydration/runtime failures such as missing chunk module calls. | Preserve as diagnostic evidence; do not turn into generator defaults without package-level design and tests. | Bundler fixtures and hydration tests when implemented. |
script/prod-local and Procfile.prod.local | HiChee-only | #4299 if anything | Local production-like twin stacks are a reusable validation method, but the scripts are operationally app-specific. | Direct scripts would bake in HiChee env vars, database names, renderer ports, and secret assumptions. | Document the methodology, not the scripts. | Docs formatter and git diff --check. |
| Home/FAQ controllers, routes, Slim views, CMS models, and specs | HiChee-only | None, except as case-study links in docs | These implement HiChee pages, not React on Rails behavior. | Copying them would add irrelevant app code and misleading examples. | Do not backport. Use only as context for why portable docs/API issues exist. | No React on Rails verification because no backport should occur. |
react_on_rails_rsc#134 and
react_on_rails_rsc#145: implement
package-level support after the desired docs and API boundaries are clear.react_on_rails_rsc issues from this matrix.