Add JSDoc comments to React Router components and hooks

cursoragent · tannerlinsley · cursoragent · commit dd73fdd27c9b · 2025-10-21T17:03:37.000Z
Co-authored-by: tannerlinsley &lt;tannerlinsley@gmail.com&gt;
diff --git a/packages/react-router/src/Asset.tsx b/packages/react-router/src/Asset.tsx
@@ -8,6 +8,10 @@ interface ScriptAttrs {
   suppressHydrationWarning?: boolean
 }
 
+/**
+ * Render a managed head/body tag from a router-managed descriptor.
+ * Used internally by `HeadContent` and `Scripts` to materialize tags.
+ */
 export function Asset({
   tag,
   attrs,
diff --git a/packages/react-router/src/HeadContent.tsx b/packages/react-router/src/HeadContent.tsx
@@ -4,6 +4,10 @@ import { useRouter } from './useRouter'
 import { useRouterState } from './useRouterState'
 import type { RouterManagedTag } from '@tanstack/router-core'
 
+/**
+ * Compute the deduped, ordered set of head tags derived from active matches
+ * and SSR manifest, including title/meta/links/styles/head scripts.
+ */
 export const useTags = () => {
   const router = useRouter()
   const nonce = router.options.ssr?.nonce
@@ -187,6 +191,10 @@ export const useTags = () => {
  * @description The `HeadContent` component is used to render meta tags, links, and scripts for the current route.
  * It should be rendered in the `<head>` of your document.
  */
+/**
+ * Render head tags for the current route tree. Place this in your document
+ * `<head>` (or as high as possible) to manage title/meta/links/styles.
+ */
 export function HeadContent() {
   const tags = useTags()
   const router = useRouter()
diff --git a/packages/react-router/src/ScriptOnce.tsx b/packages/react-router/src/ScriptOnce.tsx
@@ -1,5 +1,9 @@
 import { useRouter } from './useRouter'
 
+/**
+ * SSR-only utility component to emit a single inline script once per request.
+ * Appends an internal callback marker to signal SSR completion.
+ */
 export function ScriptOnce({ children }: { children: string }) {
   const router = useRouter()
   if (!router.isServer) {
diff --git a/packages/react-router/src/Scripts.tsx b/packages/react-router/src/Scripts.tsx
@@ -3,6 +3,10 @@ import { useRouterState } from './useRouterState'
 import { useRouter } from './useRouter'
 import type { RouterManagedTag } from '@tanstack/router-core'
 
+/**
+ * Render body scripts derived from route `scripts` and SSR manifest assets.
+ * Place this near the end of your document body.
+ */
 export const Scripts = () => {
   const router = useRouter()
   const nonce = router.options.ssr?.nonce
diff --git a/packages/react-router/src/fileRoute.ts b/packages/react-router/src/fileRoute.ts
@@ -57,6 +57,17 @@ import type { UseRouteContextRoute } from './useRouteContext'
  * @returns A function that accepts Route options and returns a Route instance.
  * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createFileRouteFunction
  */
+/**
+ * Creates a file-based Route factory for a given path.
+ *
+ * Used by TanStack Router's file-based routing to associate a file with a
+ * route. The returned function accepts standard route options. In normal usage
+ * the `path` string is inserted and maintained by the `tsr` generator.
+ *
+ * @param path File path literal for the route (usually auto-generated).
+ * @returns A function that accepts Route options and returns a Route instance.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createFileRouteFunction
+ */
 export function createFileRoute<
   TFilePath extends keyof FileRoutesByPath,
   TParentRoute extends AnyRoute = FileRoutesByPath[TFilePath]['parentRoute'],
@@ -85,6 +96,10 @@ export function createFileRoute<
   @deprecated It's no longer recommended to use the `FileRoute` class directly.
   Instead, use `createFileRoute('/path/to/file')(options)` to create a file route.
 */
+/** 
+  @deprecated It's no longer recommended to use the `FileRoute` class directly.
+  Instead, use `createFileRoute('/path/to/file')(options)` to create a file route.
+*/
 export class FileRoute<
   TFilePath extends keyof FileRoutesByPath,
   TParentRoute extends AnyRoute = FileRoutesByPath[TFilePath]['parentRoute'],
@@ -184,6 +199,11 @@ export class FileRoute<
   Instead, place the loader function in the the main route file, inside the
   `createFileRoute('/path/to/file)(options)` options.
 */
+/** 
+  @deprecated It's recommended not to split loaders into separate files.
+  Instead, place the loader function in the the main route file, inside the
+  `createFileRoute('/path/to/file)(options)` options.
+*/
 export function FileRouteLoader<
   TFilePath extends keyof FileRoutesByPath,
   TRoute extends FileRoutesByPath[TFilePath]['preLoaderRoute'],
@@ -308,6 +328,18 @@ export class LazyRoute<TRoute extends AnyRoute> {
  * @returns A function that accepts lazy route options and returns a `LazyRoute`.
  * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createLazyRouteFunction
  */
+/**
+ * Creates a lazily-configurable code-based route stub by ID.
+ *
+ * Use this for code-splitting with code-based routes. The returned function
+ * accepts only non-critical route options like `component`, `pendingComponent`,
+ * `errorComponent`, and `notFoundComponent` which are applied when the route
+ * is matched.
+ *
+ * @param id Route ID string literal to associate with the lazy route.
+ * @returns A function that accepts lazy route options and returns a `LazyRoute`.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createLazyRouteFunction
+ */
 export function createLazyRoute<
   TRouter extends AnyRouter = RegisteredRouter,
   TId extends string = string,
@@ -343,6 +375,17 @@ export function createLazyRoute<
  * @returns A function that accepts lazy route options and returns a `LazyRoute`.
  * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createLazyFileRouteFunction
  */
+/**
+ * Creates a lazily-configurable file-based route stub by file path.
+ *
+ * Use this for code-splitting with file-based routes (eg. `.lazy.tsx` files).
+ * The returned function accepts only non-critical route options like
+ * `component`, `pendingComponent`, `errorComponent`, and `notFoundComponent`.
+ *
+ * @param id File path literal for the route file.
+ * @returns A function that accepts lazy route options and returns a `LazyRoute`.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createLazyFileRouteFunction
+ */
 export function createLazyFileRoute<
   TFilePath extends keyof FileRoutesByPath,
   TRoute extends FileRoutesByPath[TFilePath]['preLoaderRoute'],
diff --git a/packages/react-router/src/lazyRouteComponent.tsx b/packages/react-router/src/lazyRouteComponent.tsx
@@ -2,6 +2,15 @@ import * as React from 'react'
 import { isModuleNotFoundError } from '@tanstack/router-core'
 import type { AsyncRouteComponent } from './route'
 
+/**
+ * Wrap a dynamic import to create a route component that supports
+ * `.preload()` and friendly reload-on-module-missing behavior.
+ *
+ * @param importer Function returning a module promise
+ * @param exportName Named export to use (default: `default`)
+ * @returns A lazy route component compatible with TanStack Router
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/lazyRouteComponentFunction
+ */
 /**
  * Wrap a dynamic import to create a route component that supports
  * `.preload()` and friendly reload-on-module-missing behavior.
diff --git a/packages/react-router/src/router.ts b/packages/react-router/src/router.ts
@@ -105,6 +105,12 @@ export class Router<
   TRouterHistory,
   TDehydrated
 > {
+  /**
+   * React-specific Router implementation extending the framework-agnostic core.
+   *
+   * Use {@link createRouter} to construct instances.
+   * Pass this instance to {@link RouterProvider} to enable routing.
+   */
   constructor(
     options: RouterConstructorOptions<
       TRouteTree,
diff --git a/packages/react-router/src/useCanGoBack.ts b/packages/react-router/src/useCanGoBack.ts
@@ -1,5 +1,12 @@
 import { useRouterState } from './useRouterState'
 
+/**
+ * Returns whether the router history can safely go back without exiting
+ * the application. Useful for render-time UI decisions.
+ *
+ * @returns boolean indicating back navigation availability.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useCanGoBack
+ */
 export function useCanGoBack() {
   return useRouterState({ select: (s) => s.location.state.__TSR_index !== 0 })
 }
diff --git a/packages/react-router/src/useNavigate.tsx b/packages/react-router/src/useNavigate.tsx
@@ -7,6 +7,18 @@ import type {
   RegisteredRouter,
   UseNavigateResult,
 } from '@tanstack/router-core'
+/**
+ * Programmatic navigation hook.
+ *
+ * Returns a stable `navigate` function that updates the current location
+ * (pathname, search, hash, state) using TanStack Router semantics.
+ *
+ * Options:
+ * - `from`: Base path to resolve relative navigations from (defaults to current route).
+ *
+ * @returns A `navigate` function.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useNavigateHook
+ */
 export function useNavigate<
   TRouter extends AnyRouter = RegisteredRouter,
   TDefaultFrom extends string = string,
diff --git a/packages/react-router/src/useRouter.tsx b/packages/react-router/src/useRouter.tsx
@@ -3,16 +3,6 @@ import warning from 'tiny-warning'
 import { getRouterContext } from './routerContext'
 import type { AnyRouter, RegisteredRouter } from '@tanstack/router-core'
 
-/**
- * Access the current TanStack Router instance from React context.
- * Must be used within a `RouterProvider`.
- *
- * Options:
- * - `warn`: Log a warning if no router context is found (default: true).
- *
- * @returns The registered router instance.
- * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useRouterHook
- */
 /**
  * Access the current TanStack Router instance from React context.
  * Must be used within a `RouterProvider`.
diff --git a/packages/router-core/src/searchParams.ts b/packages/router-core/src/searchParams.ts
@@ -1,7 +1,9 @@
 import { decode, encode } from './qss'
 import type { AnySchema } from './validators'
 
+/** Default `parseSearch` implementation using JSON.parse for values. */
 export const defaultParseSearch = parseSearchWith(JSON.parse)
+/** Default `stringifySearch` implementation using JSON.stringify for objects. */
 export const defaultStringifySearch = stringifySearchWith(
   JSON.stringify,
   JSON.parse,
