TanStack Router Agent Rules

Type-safe routing and the TanStack Start full-stack framework for React and Solid.

Overview

TanStack Router covers the shared core, framework bindings, and Start packages. Its test process narrows from affected packages to focused cases, limits sandbox recovery to one reset and retry, and uses example apps for checks in context.

Documents

├── 
└──

Patterns in this file

Hard prohibitions Verification by change type Architecture as narrative

Keep test filters inside the task graph

Tests are narrowed by package, file, and test name through Nx. The guide explains that direct runners can skip task dependencies, including required builds.

50  - Prefer Nx targets over direct test runners so task dependencies (including required builds) remain in the graph.

02 / Hard prohibitions

Bound recovery from a stalled task runner

Sandbox instructions disable the daemon and remote cache, serialize Nx commands, and allow one reset and retry after a stall. Continued failure is surfaced instead of retried indefinitely.

51  - In sandbox, run Nx with `CI=1 NX_DAEMON=false pnpm nx run <project>:<target> --outputStyle=stream --skipRemoteCache`52  - Run only one Nx command at a time.53  - If an Nx command shows no output for ~20 seconds, stop, run `pnpm nx reset` once, and retry once.54  - Do not loop retries indefinitely. If it still hangs or sandbox blocks graph/daemon behavior, request escalation immediately.

03 / Verification by change type

Test both runtime behavior and types

Unit and type tests are required during development. The guide lists additional lint, build, end-to-end, and CI targets so different kinds of validation remain distinguishable.

58- **Critical**: Always run unit and type tests during development - do not proceed if they fail59- **Test types:** `pnpm test:unit`, `pnpm test:types`, `pnpm test:eslint`, `pnpm test:e2e`, `pnpm test:build`60- **Full CI suite:** `pnpm test:ci`61- **Fix formatting:** `pnpm format`

04 / Architecture as narrative

Keep framework-neutral logic separate from bindings

The package map places core routing and history beneath React and Solid bindings, with Start packages above them. It records the dependency direction to guide changes that cross package boundaries.

116**Dependencies:** Uses workspace protocol (`workspace:*`) - core → framework → start packages

Ideas for your repo

Keep filtered tests inside the build task graph.
Set a finite recovery policy for stalled development tools.
Treat public type behavior as a separate testing concern.
Record dependency direction between core logic and framework integrations.