tanstack-query

This skill provides a comprehensive implementation guide for TanStack Query v5, focusing on efficient async state management in modern React applications. It is designed for engineers needing to handle complex server state, data fetching, and cache invalidation with production-ready standards. The skill covers the transition from v4 to v5, including the single-object hook signature, garbage collection (gcTime) configuration, and the removal of legacy callback props. It serves as a centralized source of truth for architectural patterns like query key factories, optimistic updates, and SSR integration, ensuring consistent performance across both SPA and meta-frameworks like Next.js or Remix.

• Implements standardized query key factories to prevent cache key collisions and ensure type safety.

• Configures production-hardened defaults for staleTime, gcTime, and retry logic to minimize server load and improve user experience.

• Provides patterns for advanced mutation workflows, including optimistic UI updates and robust error handling via QueryCache global callbacks.

• Facilitates server-side rendering (SSR) and streaming support using @tanstack/react-query-next-experimental.

• Enables first-class Suspense integration for declarative loading states and data fetching.

• Best for projects using React 18+ that require high-performance data synchronization and background refetching.

• Use this skill to migrate legacy implementations by executing the provided codemod commands for automatic import updates.

• Inputs typically include API endpoint definitions and data-fetching functions; outputs are structured React hooks configured for your specific architectural needs.

• Note that onSuccess, onError, and onSettled callbacks are removed from individual hooks in v5; utilize global queryCache handlers to avoid duplicate side-effect executions.

• Ensure strict adherence to the Server vs. Client configuration table provided to optimize for edge-case failures in SSR environments.