tanstack-router-best-practices
TanStack Router best practices for type-safe routing, data loading, search params, and navigation. Activate when building React applications with complex routing needs.
- License 许可
- MIT
- 最近更新
- 2026-07-16
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- tanstack-router-best-practices
- description
- TanStack Router best practices for type-safe routing, data loading, search params, and navigation. Activate when building React applications with complex routing needs.
02 资源文件 15
- 参考文档rules/ctx-root-context.md4.6 KB
- 参考文档rules/err-not-found.md4.6 KB
- 参考文档rules/load-ensure-query-data.md4.2 KB
- 参考文档rules/load-parallel.md5.3 KB
- 参考文档rules/load-use-loaders.md3.8 KB
- 参考文档rules/nav-link-component.md3.9 KB
- 参考文档rules/nav-route-masks.md4.4 KB
- 参考文档rules/org-virtual-routes.md4.2 KB
- 参考文档rules/preload-intent.md3.5 KB
- 参考文档rules/router-default-options.md4.8 KB
- 参考文档rules/search-custom-serializer.md5.3 KB
- 参考文档rules/search-validation.md4.1 KB
- 参考文档rules/split-lazy-routes.md3.9 KB
- 参考文档rules/ts-register-router.md3.0 KB
- 参考文档rules/ts-use-from-param.md3.6 KB
03 SKILL.md 正文
TanStack Router Best Practices
Comprehensive guidelines for implementing TanStack Router patterns in React applications. These rules optimize type safety, data loading, navigation, and code organization.
When to Apply
- Setting up application routing
- Creating new routes and layouts
- Implementing search parameter handling
- Configuring data loaders
- Setting up code splitting
- Integrating with TanStack Query
- Refactoring navigation patterns
Rule Categories by Priority
| Priority | Category | Rules | Impact |
|---|---|---|---|
| CRITICAL | Type Safety | 4 rules | Prevents runtime errors and enables refactoring |
| CRITICAL | Route Organization | 5 rules | Ensures maintainable route structure |
| HIGH | Router Config | 1 rule | Global router defaults |
| HIGH | Data Loading | 6 rules | Optimizes data fetching and caching |
| HIGH | Search Params | 5 rules | Enables type-safe URL state |
| HIGH | Error Handling | 1 rule | Handles 404 and errors gracefully |
| MEDIUM | Navigation | 5 rules | Improves UX and accessibility |
| MEDIUM | Code Splitting | 3 rules | Reduces bundle size |
| MEDIUM | Preloading | 3 rules | Improves perceived performance |
| LOW | Route Context | 3 rules | Enables dependency injection |
Quick Reference
Type Safety (Prefix: ts-)
ts-register-router— Register router type for global inferencets-use-from-param— Usefromparameter for type narrowingts-route-context-typing— Type route context with createRootRouteWithContextts-query-options-loader— Use queryOptions in loaders for type inference
Router Config (Prefix: router-)
router-default-options— Configure router defaults (scrollRestoration, defaultErrorComponent, etc.)
Route Organization (Prefix: org-)
org-file-based-routing— Prefer file-based routing for conventionsorg-route-tree-structure— Follow hierarchical route tree patternsorg-pathless-layouts— Use pathless routes for shared layoutsorg-index-routes— Understand index vs layout routesorg-virtual-routes— Understand virtual file routes
Data Loading (Prefix: load-)
load-use-loaders— Use route loaders for data fetchingload-loader-deps— Define loaderDeps for cache controlload-ensure-query-data— Use ensureQueryData with TanStack Queryload-deferred-data— Split critical and non-critical dataload-error-handling— Handle loader errors appropriatelyload-parallel— Leverage parallel route loading
Search Params (Prefix: search-)
search-validation— Always validate search paramssearch-type-inheritance— Leverage parent search param typessearch-middleware— Use search param middlewaresearch-defaults— Provide sensible defaultssearch-custom-serializer— Configure custom search param serializers
Error Handling (Prefix: err-)
err-not-found— Handle not-found routes properly
Navigation (Prefix: nav-)
nav-link-component— Prefer Link component for navigationnav-active-states— Configure active link statesnav-use-navigate— Use useNavigate for programmatic navigationnav-relative-paths— Understand relative path navigationnav-route-masks— Use route masks for modal URLs
Code Splitting (Prefix: split-)
split-lazy-routes— Use .lazy.tsx for code splittingsplit-critical-path— Keep critical config in main route filesplit-auto-splitting— Enable autoCodeSplitting when possible
Preloading (Prefix: preload-)
preload-intent— Enable intent-based preloadingpreload-stale-time— Configure preload stale timepreload-manual— Use manual preloading strategically
Route Context (Prefix: ctx-)
ctx-root-context— Define context at root routectx-before-load— Extend context in beforeLoadctx-dependency-injection— Use context for dependency injection
How to Use
Each rule file in the rules/ directory contains:
- Explanation — Why this pattern matters
- Bad Example — Anti-pattern to avoid
- Good Example — Recommended implementation
- Context — When to apply or skip this rule
Full Reference
See individual rule files in rules/ directory for detailed guidance and code examples.
04 同仓库更多 Skills
to-prompt-opus
Use when preparing or rewriting prompts for Claude Opus 4.8, Anthropic API agents, XML-structured prompts, long-context document work, coding agents, research synthesis, frontend/design tasks, or model-specific prompt optimization. Do not use for GPT/OpenAI prompts or raw context packaging without Opus-specific tuning.
to-prompt-gpt
Use when preparing or rewriting prompts for GPT-5.5, OpenAI API agents, Responses workflows, coding agents, research synthesis, support assistants, or model-specific prompt optimization. Do not use for Claude/Opus prompts or raw context packaging without GPT-specific tuning.
plan-refactor-qa
Plans and runs qa-report before executing Compozy refactor tasks. Use when the user provides a refactor or issue slug and wants Codex to inspect the matching .compozy/tasks directory, related PRD/TechSpec/ADR/task artifacts, affected code, and existing tests, then invoke $qa-report with a repository-grounded prompt. Do not use to run tests, execute qa-execution, implement code, or perform post-refactor verification.
multi-tool-branch-review
Orchestrates a multi-tool branch review of the current git branch against a base branch. By default it runs two independent thermo-nuclear maintainability audits, one on Codex GPT-5.5 xhigh and one on Claude Opus xhigh, then consolidates the findings into a single remediation plan via writing-plans. If the user explicitly asks for native reviews, it can add the Claude native review pass, the Codex native review pass, or both. Use when the user wants a deep cross-model review of a branch or PR before merge, or asks to review this branch with multiple tools or models. Encodes known infra failure modes and their fixes (missing Claude ACP adapter, Codex MCP auth hangs, false-positive report files, long jobs orphaned inside subagents). Do not use for reviewing a single uncommitted snippet, for non-git work, for running only one reviewer, or when the user only wants a quick lint or test run.
create-pr-with-template
Create a GitHub Pull Request with gh CLI and prefer repository PR templates automatically. Use this whenever the user asks to open/create a PR, especially when template compliance is needed. If multiple templates exist, ask the user which template to use.
ui-craft
Provides guardrails for user-facing UI work: usability heuristics, accessibility floors, design-system discipline, component states, microcopy, motion, dark mode, responsive behavior, and human-AI UX. Use when designing, generating, reviewing, or refactoring visible product surfaces such as components, pages, dashboards, forms, dialogs, loading/empty/error states, or AI interfaces. Do not use for backend-only work, infrastructure, CLI/TUI design, or pure documentation editing.