TanStack Router Best Practices

If the user is mainly solving local component state, form validation, or server-cache ownership, keep Router advice brief and push the problem toward the right abstraction.

Working Style

1. Prefer file-based routing unless the project has a concrete reason to keep routes in code or to use virtual file routes.
2. Keep route concerns in routes: matching, params, search validation, guards, loaders, and route-level boundaries.
3. Default to React examples, but lead with shared TanStack Router rules when the behavior is framework-agnostic.
4. Prefer typed route APIs, from narrowing, and reusable option builders over raw strings and ad hoc URL assembly.
5. Separate Router cache guidance from TanStack Query guidance before recommending a loader strategy.
6. Call out deprecated or stale patterns directly when they appear in user code.

Reference Map

• references/router-setup-and-route-organization.md
  • Use for file-based routing, route-tree design, pathless layouts, route directories, and virtual routes.
• references/navigation-links-and-ux.md
  • Use for Link, useNavigate, relative navigation, active states, preloading, masking, blocking, and scroll behavior.
• references/search-params-and-url-state.md
  • Use for validateSearch, schema adapters, URL-state boundaries, serializers, and search-driven loader keys.
• references/loaders-deferred-data-and-query-integration.md
  • Use for beforeLoad, loaders, loaderDeps, Router cache vs Query cache, deferred data, and SSR-oriented Query integration.
• references/errors-not-found-and-route-context.md
  • Use for auth guards, redirects, notFoundComponent, route errors, root defaults, and typed router context.
• references/typing-rendering-and-code-splitting.md
  • Use for router registration, getRouteApi, from and strict, render optimizations, useRouterState, and lazy route setup.

Response Requirements

• Say when file-based routing is the simpler and safer choice.
• Prefer current v1 APIs over deprecated route classes, NotFoundRoute, or stale React Router habits.
• Prefer TypeScript examples unless the user explicitly wants plain JavaScript.
• Keep route matching, URL validation, guards, and loaders in routes instead of burying them in page components.
• When reviewing code, separate correctness issues from optional ergonomics improvements.
• If the user is using TanStack Query, explain whether the route should return loader data, prewarm the query cache, or do both.

Core Defaults

• Prefer file-based routing with the Router plugin for new React apps.
• Prefer mixed flat and directory route organization over forcing a fully flat or fully nested convention everywhere.
• Prefer pathless layouts for shared UI or guard boundaries that should not add a URL segment.
• Prefer Link for user-driven navigation and useNavigate or redirects only for event-driven or lifecycle-driven navigation.
• Prefer linkOptions for reusable navigation objects instead of untyped object literals.
• Prefer validated, typed search params with sensible fallbacks before consuming URL state.
• Prefer loaderDeps that list only the params or search fields the loader actually uses.
• Prefer beforeLoad for auth and route middleware, and loader for data acquisition.
• Prefer notFoundComponent plus notFound() over deprecated NotFoundRoute.
• Prefer createRootRouteWithContext when routes need injected dependencies such as auth or a QueryClient.
• Prefer useRouterState, route hooks, or getRouteApi in components instead of reading router.state directly.
• Prefer automatic code splitting when supported; otherwise split non-critical route UI into .lazy.tsx files.

Provenance

This skill is authored from the bundled TanStack Router materials centered on @tanstack/react-router v1.168.10.