[kentcdodds]

Summary

Track A (web routing consolidation), PR 4 of 4: contributing docs for the reduced add-a-page surface.

• Add an Adding a page checklist to docs/contributing/remix.md (5 core files; document-head as the optional 6th).
• Update request-lifecycle.md so client registries/document-head are described as keyed by routePattern(routes.*) (with oauthPaths for authorize/callback).
• Point the contributing index at the Remix page checklist.

Risk: LOW — docs only.

Test plan

• Docs review against Track A PRs Key client route registries off routes.ts patterns #869, Extract shared page auth and request-body helpers #871, Import loader-data types in client routes #873
• CI npm run validate

System recap — composes existing primitives (low risk)

Mode: recap · Base: main @ f2f137e7 · Head: 24fc5eb3

Classification: composes — documentation only; no runtime code changes.

Primitives touched

None matched by code roots (docs-only).

System map

Contributing docs now describe the post–Track A page-wiring path: routes.ts → handler with page-auth → client route + routePattern registries.

Legend: green = composes (wiring only) · amber = extended by this PR · red = new primitive · gray = context (unchanged, included only when an edge crosses it).

flowchart LR
	docs["contributing docs"]:::touched
	docs -->|"add-a-page checklist"| docs
	classDef touched fill:#1a7f37,color:#fff
	classDef extended fill:#9a6700,color:#fff
	classDef added fill:#cf222e,color:#fff
	classDef untouched fill:#57606a,color:#fff

Loading

  

Summary by CodeRabbit

• Documentation
  • Clarified how SPA route loaders are registered, matched, redirected, and handled during errors and navigation.
  • Added a checklist for adding new pages, including route wiring, client loaders, authentication, and document head updates.
  • Documented OAuth route exceptions and their path configuration.
  • Added a Remix page checklist resource to the contributing documentation index.

[coderabbitai]

📝 Walkthrough

Walkthrough

Contributing documentation now explains the canonical process for adding Remix pages, links to that checklist, and details SPA route-loader registration and preload-then-commit navigation behavior.

Changes

Contributing documentation

Layer / File(s)	Summary
Page creation guidance docs/contributing/remix.md, docs/contributing/index.md	Adds a five-file page-wiring checklist, document-head and OAuth exceptions, and a link to the checklist from the contributing index.
Request lifecycle clarification docs/contributing/architecture/request-lifecycle.md	Documents client loader registration and matching, redirect handling, loader errors, stale data, hash-only changes, and POST navigation ordering.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Possibly related PRs

• kentcdodds/kody#608: Documents the same client route-loader registration and preload-then-commit behavior.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main documentation change: adding the five-file add-a-page checklist.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/kody-track-a-web-routing-b796

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🔎 Preview deployed: https://kody-pr-878.kody-a99.workers.dev

Worker: kody-pr-878
D1: kody-pr-878-db
KV: kody-pr-878-oauth-kv

Mocks:

• cloudflare: https://kody-pr-878-mock-cloudflare.kody-a99.workers.dev/__mocks (kody-pr-878-mock-cloudflare)

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/contributing/architecture/request-lifecycle.md`:
- Around line 128-131: Revise the request-lifecycle documentation around
RouteLoaderRedirect and routeLoaderRedirect to state explicitly that loaders
must remain side-effect-free because they may execute speculatively during
intent prefetch before navigation commits. Keep the router’s ownership of
redirect execution clear without implying that this mechanism makes loaders
side-effect-free.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 3603fd6a-af04-4391-9ae4-dc23dadf4233

📥 Commits

Reviewing files that changed from the base of the PR and between f2f137e and 24fc5eb.

📒 Files selected for processing (3)

• docs/contributing/architecture/request-lifecycle.md
• docs/contributing/index.md
• docs/contributing/remix.md

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Do not imply that the router makes loaders side-effect-free.

The router owns redirect execution, but loaders can still run speculatively during intent prefetch. State the requirement explicitly: loaders must remain side-effect-free because they may execute before navigation commits.

Suggested wording

- The router performs the redirect, never the loader itself, so speculative loader runs stay side-effect free.
+ The router performs the redirect, never the loader itself. Loaders must remain side-effect free because they may run speculatively.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	`RouteLoaderRedirect` (via `routeLoaderRedirect`) to abort the SPA navigation
	with a full-document redirect (for example, `401` → login). The router performs
	the redirect, never the loader itself, so speculative loader runs stay side-
	effect free. Loader errors still commit the navigation so the destination route
	`RouteLoaderRedirect` (via `routeLoaderRedirect`) to abort the SPA navigation
	with a full-document redirect (for example, `401` → login). The router performs
	the redirect, never the loader itself. Loaders must remain side-effect free
	because they may run speculatively. Loader errors still commit the navigation so
	the destination route

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/contributing/architecture/request-lifecycle.md` around lines 128 - 131,
Revise the request-lifecycle documentation around RouteLoaderRedirect and
routeLoaderRedirect to state explicitly that loaders must remain
side-effect-free because they may execute speculatively during intent prefetch
before navigation commits. Keep the router’s ownership of redirect execution
clear without implying that this mechanism makes loaders side-effect-free.