AGENT SKILL

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

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 inference
  • ts-use-from-param — Use from parameter for type narrowing
  • ts-route-context-typing — Type route context with createRootRouteWithContext
  • ts-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 conventions
  • org-route-tree-structure — Follow hierarchical route tree patterns
  • org-pathless-layouts — Use pathless routes for shared layouts
  • org-index-routes — Understand index vs layout routes
  • org-virtual-routes — Understand virtual file routes

Data Loading (Prefix: load-)

  • load-use-loaders — Use route loaders for data fetching
  • load-loader-deps — Define loaderDeps for cache control
  • load-ensure-query-data — Use ensureQueryData with TanStack Query
  • load-deferred-data — Split critical and non-critical data
  • load-error-handling — Handle loader errors appropriately
  • load-parallel — Leverage parallel route loading

Search Params (Prefix: search-)

  • search-validation — Always validate search params
  • search-type-inheritance — Leverage parent search param types
  • search-middleware — Use search param middleware
  • search-defaults — Provide sensible defaults
  • search-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 navigation
  • nav-active-states — Configure active link states
  • nav-use-navigate — Use useNavigate for programmatic navigation
  • nav-relative-paths — Understand relative path navigation
  • nav-route-masks — Use route masks for modal URLs

Code Splitting (Prefix: split-)

  • split-lazy-routes — Use .lazy.tsx for code splitting
  • split-critical-path — Keep critical config in main route file
  • split-auto-splitting — Enable autoCodeSplitting when possible

Preloading (Prefix: preload-)

  • preload-intent — Enable intent-based preloading
  • preload-stale-time — Configure preload stale time
  • preload-manual — Use manual preloading strategically

Route Context (Prefix: ctx-)

  • ctx-root-context — Define context at root route
  • ctx-before-load — Extend context in beforeLoad
  • ctx-dependency-injection — Use context for dependency injection

How to Use

Each rule file in the rules/ directory contains:

  1. Explanation — Why this pattern matters
  2. Bad Example — Anti-pattern to avoid
  3. Good Example — Recommended implementation
  4. 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

haryelramalho
haryelramalho/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.

★ 0
haryelramalho
haryelramalho/skills

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.

★ 0
haryelramalho
haryelramalho/skills

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.

★ 0
haryelramalho
haryelramalho/skills

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.

★ 0
haryelramalho
haryelramalho/skills

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.

★ 0
haryelramalho
haryelramalho/skills

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.

★ 0