Fix legacy docs URL redirects

[tannerlinsley]

Summary

• Add a shared docs route loader and pure redirect resolver for legacy framework docs URLs.
• Redirect legacy docs/react/overview and missing framework overview paths before markdown loading, while keeping canonical docs URLs unchanged.
• Bound GitHub docs fetches with the existing timeout helper so bad docs paths do not hang forever.
• Add resolver coverage for every public library and an opt-in route smoke test matrix.

Root Cause

Legacy docs URLs could miss the canonical docs/framework/:framework/* manifest path and continue into markdown/GitHub fetch behavior instead of resolving quickly to a redirect or not-found result.

Validation

• pnpm test
• Commit hook: pnpm run format && pnpm run test
• Earlier local preview smoke run with TANSTACK_DOCS_SMOKE_BASE_URL across every public library passed under the 5s per-request timeout.

Summary by CodeRabbit

• New Features

  • Improved docs navigation so more docs URLs resolve to the correct page or redirect to the right framework-specific location.
  • Added support for cleaner markdown docs links and filename handling.

• Bug Fixes

  • Removed broken root-level docs redirects and streamlined docs page loading.
  • Improved handling for missing docs by returning the proper not-found result or redirecting when a valid target exists.

• Tests

  • Added coverage for docs redirect behavior and end-to-end route responses.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 804ebb4a-c393-4792-8dbc-0b49b5edfaf4

📥 Commits

Reviewing files that changed from the base of the PR and between 2da2d79 and 94ad5c0.

📒 Files selected for processing (11)

• src/routes/__root.tsx
• src/routes/_library/$libraryId/$version.docs.$.tsx
• src/routes/_library/$libraryId/$version.docs.framework.$framework.$.tsx
• src/routes/_library/$libraryId/$version.docs.framework.$framework.{$}[.]md.tsx
• src/routes/_library/$libraryId/$version.docs.{$}[.]md.tsx
• src/utils/docs-redirects.ts
• src/utils/docs.functions.ts
• src/utils/docs.ts
• src/utils/documents.server.ts
• tests/docs-redirects.test.ts
• tests/docs-route-smoke.test.ts

---

📝 Walkthrough

Walkthrough

A new manifest-based docs redirect resolution system is introduced via docs-redirects.ts, exposing types and helpers for resolving docs paths to render/redirect/not-found outcomes. A loadDocsRoute orchestration function is added to docs.ts and fetchDocsPathManifest to docs.functions.ts. All four docs route loaders are migrated to use loadDocsRoute, removing legacy try/catch redirect logic. The root route's URL-pattern redirect is removed. GitHub fetches gain timeout support via fetchWithTimeout.

Changes

Docs Redirect Resolution System

Layer / File(s)	Summary
Redirect manifest types and path resolver src/utils/docs-redirects.ts	Defines DocsRedirectManifest, DocsPathResolution, resolveDocsPathRedirect, and URL builders (buildDocsRedirectHref, buildDocsMarkdownRedirectHref) with internal normalization and framework-aware candidate resolution.
fetchDocsPathManifest server function src/utils/docs.functions.ts	Aliases DocsManifest to DocsRedirectManifest, adds buildDocsPathManifest (directory tree → .md paths, empty redirects), and exposes it as a cached fetchDocsPathManifest server function.
loadDocsRoute and resolveDocsRoutePath orchestration src/utils/docs.ts	Adds resolveDocsRoutePath, getDefaultDocsResolution, LoadDocsRouteResult union, loadDocsRoute (resolve → load → redirect-from-paths fallback), and supporting helpers; re-exports redirect URL builders.
Route loaders migrated to loadDocsRoute src/routes/__root.tsx, src/routes/_library/$libraryId/$version.docs.$.tsx, src/routes/_library/$libraryId/$version.docs.framework.$framework.$.tsx, src/routes/_library/$libraryId/$version.docs.framework.$framework.{$}[.]md.tsx, src/routes/_library/$libraryId/$version.docs.{$}[.]md.tsx	Root loader drops legacy /docs/* URL redirect. All four docs route loaders replace direct loadDocs + try/catch with loadDocsRoute and switch on result.type for 308 redirect, notFound, or doc return.
fetchWithTimeout for GitHub fetches src/utils/documents.server.ts	Applies fetchWithTimeout to authenticated and unauthenticated retry paths in fetchRemote and fetchGitHubApiJson.
Unit and smoke tests tests/docs-redirects.test.ts, tests/docs-route-smoke.test.ts	Unit tests cover resolveDocsPathRedirect and URL builders across publicLibraries and scenarios. Smoke test issues live HTTP requests with manual redirect chasing to assert 200/404 for legacy and canonical docs paths.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐇 Hopping through paths once tangled and snarled,
The manifest maps where the old routes had gnarled.
loadDocsRoute now leads with a confident bound,
308 redirects where lost docs are found.
No more bare fetch left dangling in time—
Every request gets a timeout sublime! ✨

✨ 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 taren/fix-legacy-docs-urls

---

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

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	tanstack-com	94ad5c0	Commit Preview URL Branch Preview URL	Jun 27 2026, 06:12 PM