tanstack-router-best-practices

Files (1)

• SKILL.md

SKILL.md (first lines)

# TanStack Router

Use this skill whenever working with `@tanstack/react-router` or routing inside a TanStack Start application.

## Core Principles

Write routing code that is:

- Type-safe
- Predictable
- URL-driven
- Easy to navigate and maintain
- Compatible with the project's installed TanStack Router version
- Consistent with the project's existing routing approach

Prefer simple TanStack Router primitives over custom abstractions.

Do not introduce wrappers, helpers, route factories, or routing abstractions unless they remove real repeated complexity.

## Before Changing Routes

Inspect the existing project first.

Check:

- installed TanStack Router version
- file-based vs code-based routing
- route directory structure
- router creation/configuration
- root route
- route context
- authentication approach
- existing loaders
- search-param validation
- TanStack Query usage
- existing error/pending/not-found handling

Do not rewrite an existing routing architecture simply because a newer pattern exists.

For new projects, prefer file-based routing unless there is a concrete reason not to.

## File-Based Routing

When the project uses file-based routing:

- Use `createFileRoute`.
- Follow TanStack Router file naming conventions.
- Let the route hierarchy express layouts and nesting.
- Use pathless layout routes for shared behavior/layouts that should not add URL segments.
- Keep routes focused on route responsibilities.
- Never manually edit generated route-tree files such as `routeTree.gen.ts`.

Avoid duplicating the filesystem route hierarchy in custom configuration.

## Route Components

Keep route files readable.

A route may coordinate:

- params
- search validation
- loader dependencies
- loaders
- authentication/authorization routing
- route context
- metadata
- pending/error/not-found behavior
- the route component

Do not put large amounts of unrelated business logic directly into the route definition.

Extract domain logic into appropriate modules while keeping route-specific coordination in the route.

## Path Parameters

Use TanStack Router's typed params APIs.

Prefer:

```tsx
const { postId } = Route.useParams()
```

Do not manually parse the pathname.

When navigating, provide dynamic values using `params`.

Prefer:

```tsx
navigate({
  to: "/posts/$postId",
  params: { postId },
})
```

Do not manually interpolate URLs such as:

```tsx
navigate({
  to: `/posts/${postId}`,
})
```

when TanStack Router can type the route.

## Search Parameters

Treat search params as typed URL state.

Use them for state that should survive:

- refreshes
- browser back/forward
- bookmarking
- sharing URLs

Examples:

From Jack-WebDev/skills, MIT.

More from Jack-WebDev/skills