tanstack-integration-best-practices

This skill provides a structured set of guidelines for developers building full-stack applications with the TanStack ecosystem. It focuses on the crucial integration points between TanStack Query for state management, TanStack Router for navigation and data loading, and TanStack Start for server-side rendering and full-stack capabilities. The primary goal is to eliminate common pitfalls such as hydration mismatches, data waterfalls, and inconsistent caching strategies that arise when these powerful libraries are used in isolation. By following these rules, developers can establish a robust, type-safe architecture that handles complex data requirements from the server to the client with minimal friction. This skill is ideal for software engineers, full-stack developers, and AI coding assistants tasked with configuring modern React applications that prioritize performance, search engine optimization (SEO), and maintainable codebase structures. Whether you are migrating an existing project or scaffolding a new high-performance web application, these integration patterns help maintain a clean separation of concerns while leveraging the specific strengths of each TanStack library.

• Orchestrates effective data fetching patterns by coordinating loaders with query caching mechanisms.

• Ensures type safety across the full stack through shared context and router-integrated data providers.

• Optimizes server-side rendering (SSR) and hydration performance by providing unified configuration patterns.

• Manages cache synchronization, avoiding conflicts between router preloading and query stale-time configurations.

• Provides clear guidelines for implementing suspense-based data loading and mutation invalidation workflows.

• Standardizes error boundaries and loading states in complex application architectures.

• Designed for applications utilizing TypeScript to maximize the benefits of TanStack Router's type-safe routing.

• Requires careful setup of the QueryClient within the router's context to facilitate proper SSR streaming.

• Use this skill to debug issues related to double-fetching, stale data, or incorrect hydration during page transitions.

• Input for the agent includes the application's router and query configuration files; output provides refactored code snippets, structural suggestions, and architectural alignment checks.

• Adheres to the Agent Skills format, making it directly compatible with AI coding agents like Claude Code, which can automatically verify these integration rules during codebase analysis.