Add jsdoc annotations to public api

[tannerlinsley]

Add JSDoc annotations to key public APIs in @tanstack/router-core and @tanstack/react-router for improved self-documentation.

This PR annotates over 20 core router functions, path utilities, search param helpers, rewrite logic, scroll restoration, and React hooks/components. The JSDoc focuses on describing behavior and options, complementing existing TypeScript types.

---

 

Summary by CodeRabbit

Release Notes

• New Features

  • Added Await component for handling deferred promises with suspense support
  • Added path normalization utilities: trimPathLeft, trimPathRight, trimPath
  • Added redirect parsing and validation utilities
  • Added rewrite composition and execution utilities for advanced routing scenarios
  • Enhanced scroll restoration with new configuration options

• Improvements

  • Path joining now gracefully handles undefined segments
  • Deprecated component notices updated for clarity

• Documentation

  • Comprehensive documentation added across routing and utility APIs

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

This PR enhances documentation and expands public APIs across react-router and router-core packages. It adds JSDoc comments throughout, introduces new utility functions (path trimming, redirect parsing, rewrite composition, scroll handling), exports existing internal utilities, and adds a new Await component for handling deferred promises.

Changes

Cohort / File(s)	Summary
React Router Documentation Updates packages/react-router/src/Scripts.tsx, packages/react-router/src/ScrollRestoration.tsx, packages/react-router/src/useRouter.tsx, packages/react-router/src/route.tsx	Added and updated JSDoc comments; removed duplicate JSDoc block; updated deprecation notice wording. No functional changes to exports or signatures.
React Router New Components packages/react-router/src/awaited.tsx	Introduced new public Await component that suspends on deferred promises with optional Suspense fallback; added JSDoc documentation for useAwaited hook.
Router Core Path Utilities packages/router-core/src/path.ts	Added three new path normalization functions (trimPathLeft, trimPathRight, trimPath); modified joinPaths to filter undefined segments; added comprehensive JSDoc for resolvePath, interpolatePath, matchPathname, and matchByPath.
Router Core Search & Query Utilities packages/router-core/src/qss.ts, packages/router-core/src/searchMiddleware.ts, packages/router-core/src/searchParams.ts	Added JSDoc documentation to encode/decode query string functions, retainSearchParams/stripSearchParams search middleware, and search parsing/stringifying utilities. No functional changes.
Router Core Redirect Utilities packages/router-core/src/redirect.ts	Added isResolvedRedirect type guard and parseRedirect function to reconstruct redirects from serialized objects.
Router Core Rewrite Utilities packages/router-core/src/rewrite.ts	Added four new functions: composeRewrites for combining rewrite rules, rewriteBasepath for basepath stripping/adding, and executeRewriteInput/executeRewriteOutput for applying rewrites to URLs.
Router Core Navigation & Scroll APIs packages/router-core/src/router.ts, packages/router-core/src/scroll-restoration.ts	Added extensive JSDoc documentation for RouterCore methods; exported storageKey, scrollRestorationCache, and defaultGetScrollRestorationKey; added setupScrollRestoration and handleHashScroll public functions alongside documentation for existing APIs.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

The changes span multiple files with a mix of documentation additions (low complexity) and new functional APIs (moderate complexity). Most of the heterogeneity comes from documentation improvements, which are repetitive and straightforward. However, the new rewrite utilities, redirect parsing functions, and scroll restoration exports require careful logic review. The router.ts file's potential method duplication warrants particular attention.

Possibly related PRs

• fix: basepath #5345 — Adds rewriteBasepath and related rewrite utilities alongside basepath runtime handling modifications
• refactor(router-core): scroll-restoration minor performance cleanup #4990 — Modifies scroll-restoration functions (getCssSelector, restoreScroll, setupScrollRestoration) in the same file
• Add core api jsdoc annotations #5550 — Updates JSDoc and documentation for the same router-core search and redirect APIs

Suggested reviewers

• schiller-manuel
• SeanCassiere
• Sheraff

Poem

🐰 A hop through the docs, a dance through the code,
New paths trimmed and rewrites composed by the road,
Await components suspended with promises held tight,
Scroll restoration restored—the router takes flight!
✨📚🛣️

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch cursor/add-jsdoc-annotations-to-public-api-c5e3

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d6a4352 and af3d35a.

📒 Files selected for processing (13)

• packages/react-router/src/Scripts.tsx (1 hunks)
• packages/react-router/src/ScrollRestoration.tsx (1 hunks)
• packages/react-router/src/awaited.tsx (2 hunks)
• packages/react-router/src/route.tsx (0 hunks)
• packages/react-router/src/useRouter.tsx (0 hunks)
• packages/router-core/src/path.ts (6 hunks)
• packages/router-core/src/qss.ts (2 hunks)
• packages/router-core/src/redirect.ts (1 hunks)
• packages/router-core/src/rewrite.ts (4 hunks)
• packages/router-core/src/router.ts (8 hunks)
• packages/router-core/src/scroll-restoration.ts (6 hunks)
• packages/router-core/src/searchMiddleware.ts (2 hunks)
• packages/router-core/src/searchParams.ts (3 hunks)

---

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit af3d35a

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	✅ Succeeded	5m 13s	View ↗
nx run-many --target=build --exclude=examples/*...	✅ Succeeded	1m 22s	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-10-21 21:49:10 UTC

[pkg-pr-new]

More templates

• tanstack-router-solid-example-basic
• tanstack-router-solid-example-basic-devtools-panel
• tanstack-router-solid-example-basic-file-based
• tanstack-router-solid-example-basic-non-nested-devtools
• tanstack-router-solid-example-basic-solid-query
• tanstack-router-solid-example-basic-solid-query-file-based
• tanstack-router-solid-example-basic-ssr-streaming-file-based
• tanstack-router-solid-example-kitchen-sink-file-based
• tanstack-router-solid-example-kitchen-sink-solid-query
• tanstack-router-solid-example-kitchen-sink-solid-query-file-based
• tanstack-router-solid-example-quickstart-file-based
• tanstack-solid-start-example-bare
• tanstack-solid-start-example-basic
• tanstack-solid-start-example-basic-auth
• tanstack-solid-start-example-basic-cloudflare
• tanstack-start-example-basic-solid-query
• tanstack-solid-start-example-basic-static
• tanstack-router-react-example-authenticated-routes
• tanstack-router-react-example-authenticated-routes-firebase
• tanstack-router-react-example-basic
• tanstack-router-react-example-basic-default-search-params
• tanstack-router-react-example-basic-devtools-panel
• tanstack-router-react-example-basic-file-based
• tanstack-router-react-example-basic-non-nested-devtools
• tanstack-router-react-example-react-query
• tanstack-router-react-example-basic-react-query-file-based
• tanstack-router-react-example-basic-ssr-file-based
• tanstack-router-react-example-basic-ssr-streaming-file-based
• tanstack-router-react-example-basic-virtual-file-based
• tanstack-router-react-example-basic-virtual-inside-file-based
• tanstack-router-react-example-deferred-data
• tanstack-router-i18n-paraglide
• tanstack-router-react-example-kitchen-sink
• tanstack-router-react-example-kitchen-sink-file-based
• tanstack-router-react-example-kitchen-sink-react-query
• tanstack-router-react-example-kitchen-sink-react-query-file-based
• tanstack-router-react-example-large-file-based
• tanstack-router-react-example-location-masking
• tanstack-router-react-example-navigation-blocking
• tanstack-router-react-example-quickstart
• tanstack-router-react-example-quickstart-esbuild-file-based
• tanstack-router-react-example-quickstart-file-based
• tanstack-router-react-example-quickstart-rspack-file-based
• tanstack-router-react-example-quickstart-webpack-file-based
• router-monorepo-react-query
• router-mono-simple
• router-mono-simple-lazy
• tanstack-router-react-example-scroll-restoration
• tanstack-search-validator-adapters
• tanstack-start-example-bare
• tanstack-start-example-basic
• tanstack-start-example-basic-auth
• tanstack-start-example-basic-cloudflare
• tanstack-start-example-basic-react-query
• tanstack-start-example-basic-static
• tanstack-start-bun-hosting
• tanstack-start-example-clerk-basic
• tanstack-start-example-convex-trellaux
• tanstack-start-example-counter
• tanstack-start-i18n-paraglide
• tanstack-start-example-large
• tanstack-start-example-material-ui
• tanstack-start-streaming-data-from-server-functions
• tanstack-start-example-supabase-basic
• tanstack-start-tailwind-v4
• tanstack-start-example-trellaux
• tanstack-start-example-workos
• tanstack-router-react-example-view-transitions
• tanstack-router-react-example-with-framer-motion
• tanstack-router-react-example-with-trpc
• tanstack-router-react-example-with-trpc-react-query

@tanstack/arktype-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/arktype-adapter@5574

@tanstack/directive-functions-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/directive-functions-plugin@5574

@tanstack/eslint-plugin-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/eslint-plugin-router@5574

@tanstack/history

npm i https://pkg.pr.new/TanStack/router/@tanstack/history@5574

@tanstack/nitro-v2-vite-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/nitro-v2-vite-plugin@5574

@tanstack/react-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router@5574

@tanstack/react-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-devtools@5574

@tanstack/react-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-ssr-query@5574

@tanstack/react-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start@5574

@tanstack/react-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-client@5574

@tanstack/react-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-server@5574

@tanstack/router-cli

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-cli@5574

@tanstack/router-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-core@5574

@tanstack/router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools@5574

@tanstack/router-devtools-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools-core@5574

@tanstack/router-generator

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-generator@5574

@tanstack/router-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-plugin@5574

@tanstack/router-ssr-query-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-ssr-query-core@5574

@tanstack/router-utils

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-utils@5574

@tanstack/router-vite-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-vite-plugin@5574

@tanstack/server-functions-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/server-functions-plugin@5574

@tanstack/solid-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router@5574

@tanstack/solid-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-devtools@5574

@tanstack/solid-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-ssr-query@5574

@tanstack/solid-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start@5574

@tanstack/solid-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-client@5574

@tanstack/solid-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-server@5574

@tanstack/start-client-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-client-core@5574

@tanstack/start-plugin-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-plugin-core@5574

@tanstack/start-server-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-core@5574

@tanstack/start-static-server-functions

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-static-server-functions@5574

@tanstack/start-storage-context

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-storage-context@5574

@tanstack/valibot-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/valibot-adapter@5574

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/TanStack/router/@tanstack/virtual-file-routes@5574

@tanstack/zod-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/zod-adapter@5574

commit: af3d35a