Skip to content

docs(client): document the route-prefetch pattern for adding new pages #223

Description

@rongxin-liu

Context

The client now uses a tiered idle-time prefetch for lazy route chunks: factories and tier arrays live in standalone routePrefetch.ts modules (one per app), components import the tier arrays from those modules to avoid Component ↔ router static import cycles, and router.tsx keeps only the lazy() wrappers and the route tree. The pattern is described inline at the top of each routePrefetch.ts file, but the contributor-facing entry points (CONTRIBUTING.md, AGENTS.md) still describe the pre-prefetch world.

The failure mode this leaves open: a contributor or AI agent adding a new page reads router.tsx, sees existing lazy(...) wrappers, and writes a new inline lazy(() => import("...")) next to them. The chunk loads correctly but never lands in the prefetch tier — users hit a Suspense fallback on the first navigation to the new route, and a future merge conflict appears when the inline form collides with the tier-extraction pattern.

A recent merge from main (the fleet logs page) followed exactly this old pattern and required a small conflict resolution to relocate the new route into the appropriate tier.

Proposed change

Update the two contributor-facing surfaces so the prefetch protocol is discoverable before someone opens router.tsx:

  1. CONTRIBUTING.md — add an "Adding a New Route to the Client" subsection under the existing "Adding Features to the Client" section. Cover the three coordinated edits (factory in routePrefetch.ts → tier export → lazy() wrapper in router.tsx), the three tier choices (globalRoutePrefetch, settingsRoutePrefetch, and protoOS-only singleMinerRoutePrefetch), and the reason factories live in a neutral module (cycle avoidance through router.tsx).

  2. AGENTS.md — add a rule under "Rules that matter" pointing at the new CONTRIBUTING.md section. The rule names the three-step protocol and explicitly calls out that inline lazy(() => import("...")) in router.tsx bypasses the prefetch tier and causes a Suspense flash on first navigation.

The runbook comments inside routePrefetch.ts remain the source of truth; the additions above are entry-point pointers so contributors and AI agents find the pattern before falling into the trap.

Refs #211
Closes #58

Metadata

Metadata

Assignees

Labels

clientdocumentationImprovements or additions to documentation

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions