tanstack-router
Type-safe, file-based React routing with route loaders, search params validation, code splitting, preloading, navigation, route context, and TanStack Query integration. Use when setting up file-based routing, adding search params validation, implementing route loaders, code splitting routes, configuring virtual file routes, protecting routes with auth guards, or fixing type registration errors. Use for router setup, navigation patterns, URL state management, data loading.
- Installs
- 136
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/oakoss/agent-skills --skill tanstack-router- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads tanstack-router automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
TanStack Router
Type-safe, file-based routing for React with route-level data loading, search params validation, code splitting, and TanStack Query integration.
Package: @tanstack/react-router | Plugin: @tanstack/router-plugin
Quick Reference
| Pattern | Usage |
|---|---|
createFileRoute('/path') | Define file-based route |
createRootRouteWithContext<T>() | Root route with typed context |
createLazyFileRoute('/path') | Code-split route component |
zodValidator(schema) | Search params validation |
Route.useLoaderData() | Access loader data in component |
Route.useParams() | Type-safe route params |
Route.useSearch() | Type-safe search params |
useNavigate() | Programmatic navigation |
useBlocker() | Block navigation (dirty forms) |
notFound() | Throw 404 from loader |
getRouteApi('/path') | Type-safe hooks in split files |
stripSearchParams(defaults) | Clean default values from URLs |
retainSearchParams(['key']) | Preserve params across navs |
useAwaited({ promise }) | Suspend until deferred promise resolves |
useCanGoBack() | Check if router can go back safely |
Data Loading
| Method | Returns | Throws | Use Case |
|---|---|---|---|
ensureQueryData | Data | Yes | Route loaders (recommended) |
prefetchQuery | void | No | Background prefetching |
fetchQuery | Data | Yes | Immediate data need |
defer() (optional) | Promise | No | Stream non-critical data (promises auto-handled) |
Preloading
| Strategy | Behavior | Use Case |
|---|---|---|
'intent' | Preload on hover/focus | Default for most links |
'render' | Preload when Link mounts | Critical next pages |
'viewport' | Preload when Link in view | Below-fold content |
false | No preloading | Heavy, rarely-visited pages |
File Organization
| File | Purpose |
|---|---|
__root.tsx | Root route with <Outlet /> |
index.tsx | Index route for / |
posts.$postId.tsx | Dynamic param route |
_authenticated.tsx | Pathless layout (auth guard) |
dashboard.lazy.tsx | Code-split component |
Common Mistakes
| Mistake | Fix |
|---|---|
| Missing router type registration | Add declare module with Register interface |
useParams() without from | Always pass from: '/route/path' for exact types |
useNavigate() for regular links | Use <Link> for <a> tags, a11y, preloading |
prefetchQuery in loaders | Use ensureQueryData (returns data, throws errors) |
Fetching in useEffect | Use route loaders (prevents waterfalls) |
| Sequential fetches in loader | Use Promise.all for parallel requests |
| Missing leading slash | Always '/about' not 'about' |
| TanStackRouterVite after react() | Plugin MUST come before react() in Vite config |
strict: false params unparsed | Use strict mode or manually parse after navigation |
| Pathless route notFoundComponent | Define notFoundComponent on child routes instead |
| Aborted loader undefined error | Guard errorComponent with if (!error) return null |
No loaderDeps declared | Declare deps so loader only re-runs when they change |
Delegation
- TanStack Query patterns — data fetching, caching, mutations: use
tanstack-queryskill - TanStack Start — server functions, SSR, server-side auth: use
tanstack-startskill - TanStack Table — table rendering with router search params: use
tanstack-tableskill - Router + Query integration — loader data flow, preloading: see Loader Data Flow Patterns
If the
tanstack-devtoolsskill is available, delegate router state debugging and route tree inspection to it.
References
- Setup — installation, Vite config, file structure, app setup, router default options
- Type Safety — register router,
fromparam,strict: false, type utilities, getRouteApi - Data Loading — route loaders, Query integration, parallel loading, streaming, deferred data, abort signal, loaderDeps
- Search Params — validation, strip/retain middleware, fine-grained subscriptions, debounce, custom serializers
- Navigation — Link, active styling, relative navigation, hash, route masks, blocker, scroll restoration
- Auth and Context — beforeLoad, context inheritance, pathless layouts, dependency injection, error handling
- Code Splitting — lazy routes, auto splitting, preloading strategies, programmatic preloading
- Virtual File Routes — rootRoute, route, index, layout, physical builders, mixing file-based and code-based routing
- Known Issues — 20 documented issues with fixes, anti-patterns
- Loader+Query Patterns — ensureQueryData in loaders, parallel loading, critical vs non-critical data, search-param-dependent loaders
FAQ
What does the tanstack-router skill do?
Type-safe, file-based React routing with route loaders, search params validation, code splitting, preloading, navigation, route context, and TanStack Query integration. Use when setting up file-based routing, adding search params validation, implementing route loaders, code splitting routes, configuring virtual file routes, protecting routes with auth guards, or fixing type registration errors. Use for router setup, navigation patterns, URL state management, data loading.
How do I install tanstack-router?
Run npx skills add https://github.com/oakoss/agent-skills --skill tanstack-router in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/tanstack-router/ (personal) or .claude/skills/tanstack-router/ (project).
Which AI agents can use tanstack-router?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is tanstack-router safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains tanstack-router?
It is published by oakoss in oakoss/agent-skills. It has 136 recorded installs.
More from oakoss/agent-skills
ui-ux-polish
oakoss/agent-skills
Iterative UI/UX polishing workflow for web applications. Use when improving visual polish, refining desktop and mobile UX separately, running iterative enhancement cycles, applying design patterns like glassmorphism or bento grids, or auditing accessibility and WCAG compliance. Use for Stripe-level visual quality, responsive optimization, and design system alignment.
playwright
oakoss/agent-skills
Open the skill to read its SKILL.md instructions.
coolify
oakoss/agent-skills
Coolify self-hosted PaaS for deploying applications, databases, and services via REST API and Git integration. Covers API authentication, deployment triggers, build packs (Nixpacks, Dockerfile, Compose), CI/CD with GitHub Actions webhooks, environment management, and Traefik proxy configuration. Use when deploying apps to Coolify, triggering deployments via API, configuring build packs, setting up GitHub Actions CI/CD pipelines, managing environment variables, or troubleshooting deployment failures.
application-security
oakoss/agent-skills
Application security covering threat modeling (STRIDE), OWASP Top 10 (2025), OWASP API Security Top 10 (2023), secure coding review, authentication/authorization patterns, input validation, encryption, security headers, supply chain security, compliance (GDPR/HIPAA/SOC2/PCI-DSS), and security monitoring. Use when reviewing code for vulnerabilities, implementing auth patterns, securing APIs, configuring security headers, hardening supply chain, preventing injection attacks, or preparing for compliance audits.
find-skills
oakoss/agent-skills
Discovers and installs agent skills from the open ecosystem. Enriches search results with descriptions fetched from skills.sh. Use when a user asks "how do I do X", "find a skill for X", "is there a skill that can...", or wants to extend agent capabilities. Use for skill discovery, skill search, skill install, finding tools.
drizzle-orm
oakoss/agent-skills
Drizzle ORM for type-safe SQL with PostgreSQL, MySQL, and SQLite. Use when defining schemas, writing queries, managing relations, running migrations, or using drizzle-kit. Use for drizzle, orm, schema, query, migration, pgTable, relations, drizzle-kit, drizzle-zod.
Popular frontend & design skills
setup-matt-pocock-skills
mattpocock/skills
Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.
frontend-design
anthropics/skills
Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.
hyperframes-animation
heygen-com/hyperframes
All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.
prototype
mattpocock/skills
Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
hyperframes-core
heygen-com/hyperframes
The HyperFrames composition contract — build one renderable project. Use for composition structure, the data- timing attributes, class="clip", tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.
vercel-react-best-practices
vercel-labs/agent-skills
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.