TanStack Query v5: A Deep Dive into the Changes and Features

Source: Excerpts from "All About TanStack Query v5" (Live Stream Transcript)

• Welcoming viewers and setting the stage: This section kicks off the live stream with a warm welcome, introduces the main focus on TanStack Query v5, and encourages viewer interaction through questions and feedback.
• Addressing early community feedback: Acknowledging the importance of user feedback, this section highlights the goal of addressing community concerns experienced during the version 4 release, aiming to improve the transition process for version 5.
• Rationale behind removing callbacks from queries: A central discussion revolves around the decision to remove callbacks (onSuccess, onError, onSettled) from useQuery. This section elaborates on the reasons behind this change, primarily focusing on the ambiguity and bugs surrounding callback triggers in queries.
• Contrasting queries and mutations: This section clarifies why callbacks remain in useMutation, distinguishing between the imperative nature of mutations and the automatic, cache-driven behavior of queries.
• Alternative approaches to callback functionality: The discussion explores alternative methods for achieving the same functionality as callbacks, like using mutateAsync with try-catch blocks, or leveraging libraries like react-hot-toast for promise-based interactions.
• Dedicated useSuspenseQuery Hook: This section introduces the new dedicated useSuspenseQuery hook, highlighting its advantages over the previous experimental flag approach. It emphasizes the hook's potential for future integration with React features like use hook and startTransition, and suspense cache management.
• Type safety improvements with suspense: The discussion explains how the removal of loading and error states within suspense boundaries ensures data is always defined, leading to improved type safety within useSuspenseQuery.
• Handling the enabled option with suspense: The lack of an enabled option in useSuspenseQuery is addressed, offering two solutions: 1) Component composition for scenarios like dependent queries, and 2) Leveraging the inherent fetch waterfall nature of suspense for dependent queries, effectively negating the need for enabled.
• Moving towards a single options argument: This section details the major shift from using separate arguments for query key, query function, and options to a unified options object across all TanStack Query functions.
• Historical context and the TypeScript challenge: This section explains the historical reasons for multiple argument syntax, its convenience in JavaScript, and the complexities it introduced with TypeScript.
• Benefits of the new syntax: This section emphasizes the benefits of the unified object syntax, including improved type error clarity, better compatibility with other adapters like SolidJS, and a reduction in runtime overhead.
• Preparing for version 5 with ESLint: The discussion encourages developers to prepare for this change by utilizing the ESLint plugin with the preferred-query-object-syntax rule, enabling automatic code refactoring for existing useQuery calls.
• Renaming cacheTime to gcTime: This section explains the rationale behind renaming cacheTime to gcTime (garbage collection time), aiming for a more intuitive naming convention that reflects the actual functionality.
• Defaulting to TypeScript Error for improved ergonomics: A key change involves defaulting the error type to TypeScript Error instead of unknown. This section explores the reasons, acknowledges the trade-offs, and provides a way to revert to the previous behavior using module augmentation.