jotai-tanstack-query

jotai-tanstack-query bridges Jotai’s atomic state model with TanStack Query’s data-fetching engine, exposing query and mutation state as regular Jotai atoms (atomWithQuery, atomWithMutation, atomWithInfiniteQuery, and their suspense variants) so query results can be composed with the rest of an app’s atom graph using useAtom/useAtomValue instead of a separate useQuery hook API. It supports Jotai v2 and TanStack Query v5, and can be adopted incrementally alongside existing useQuery calls as long as both share the same QueryClient instance.

What You Get

• atomWithQuery and atomWithSuspenseQuery atoms that mirror TanStack Query’s useQuery/useSuspenseQuery behavior
• atomWithMutation and atomWithMutationState for mutation state as atoms
• atomWithInfiniteQuery / atomWithSuspenseInfiniteQuery for paginated, load-more data
• atomWithQueries for running and optionally combining multiple parallel queries, plus a ready-made QueryClientAtomProvider

Common Use Cases

• Deriving other atoms directly from server data by composing atomWithQuery results with plain Jotai atoms
• Incrementally migrating a TanStack Query codebase to Jotai-based state without rewriting existing useQuery call sites
• Building SSR/Next.js App Router pages that hydrate a shared QueryClient across Jotai and TanStack Query
• Running dynamic parallel queries (e.g. one query per item in a list) via atomWithQueries with a combine function

Under The Hood

Architecture: Each atomWith* function (atomWithQuery.ts, atomWithMutation.ts, atomWithInfiniteQuery.ts, etc.) is a thin layer over a shared baseAtomWithQuery.ts, which constructs a TanStack Query QueryObserver/MutationObserver from options resolved via a getOptions(get) callback, subscribes to observer updates inside the atom’s onMount, and stores the QueryClient itself in a dedicated _queryClientAtom so all query atoms resolve the same client instance without prop drilling. Tech Stack: Written in TypeScript, built with a Rollup/Preconstruct-style multi-entry setup producing separate ESM/CJS/d.ts bundles for the root export and a react.ts subpath (for QueryClientAtomProvider), with peer dependencies on jotai v2 and @tanstack/react-query v5 and no other runtime dependencies. Code Quality: The tests directory covers each atomWith* function plus the provider component using vitest, verifying loading/success/error states and query-client sharing across atoms; the code is organized by one file per query variant, minimizing cross-file coupling and keeping each atom’s observer-subscription logic easy to audit in isolation. API Design: The API deliberately mirrors TanStack Query’s own hook signatures (same options objects, same result shape with data/isPending/isError) so existing TanStack Query knowledge transfers directly, and the library explicitly supports incremental adoption alongside plain useQuery calls sharing the same QueryClient.