TanStack Router Runtime Behavior and SSR

Use this skill when the task is primarily about what happens after a route matches: loading, failure, recovery, navigation side effects, or Router SSR.

Scope

• pending, error, and not-found boundaries
• retry and recovery behavior
• scroll restoration and navigation blocking
• document head and script emission
• Router SSR and hydration guardrails

Routing cues

• pendingComponent, errorComponent, notFoundComponent, router.invalidate(), scroll restoration, navigation blocking, head(), HeadContent, Scripts, or Router SSR -> use this skill
• route trees, params, Link, Navigate, or route masking -> use tanstack-router-route-trees-and-navigation
• validateSearch, loaderDeps, loader, beforeLoad, auth, route context, or preloading -> use tanstack-router-search-params-and-loaders
• generated route trees, plugin config, .lazy.tsx, or ESLint Router tooling -> use tanstack-router-file-based-routing-and-tooling

Workflow

1. Read references/runtime-lifecycle-and-recovery.md first.
2. If the task touches scroll restoration, head management, blocking, or Router SSR, read references/scroll-head-and-ssr.md.
3. Treat pending, error, not-found, and retry paths as route-owned behavior, not app-global decoration.
4. Keep TanStack Start concerns out unless the request explicitly moves beyond Router SSR into Start features.

Quick example

import { createRouter } from '@tanstack/react-router'

export const router = createRouter({
  routeTree,
  scrollRestoration: true,
  defaultPendingComponent: () => <div>Loading...</div>,
  defaultErrorComponent: ({ error }) => <div>{error.message}</div>,
  defaultNotFoundComponent: () => <div>Not found</div>,
})

Guardrails

• The route lifecycle is ordered. Search parsing and beforeLoad happen before loader, and pending UI appears only after the configured threshold.
• Retry loader-driven failures with router.invalidate() instead of only resetting the nearest render boundary.
• Not-found handling is its own route boundary system. Prefer notFound() and notFoundComponent over ad hoc 404 branches.
• Scroll behavior is router-owned when enabled. Only opt out per navigation when the UX truly needs it.
• Head and script output belong to route configuration, rendered with HeadContent and Scripts.
• Router SSR is not TanStack Start. Keep Start-only concepts like server functions, static prerendering, and ISR out of router-only fixes.

Canonical APIs

• pendingComponent
• errorComponent
• notFoundComponent
• router.invalidate
• useBlocker
• useElementScrollRestoration
• HeadContent
• Scripts

Maintenance

• Snapshot date: 2026-03-24
• Package snapshot: @tanstack/react-router@1.168.3

References

• references/runtime-lifecycle-and-recovery.md
• references/scroll-head-and-ssr.md