@tanstack/react-query 5.102.8 → 5.103.0

package/build/modern/useSuspenseQuery.d.ts

@@ -1,6 +1,73 @@
 import { UseSuspenseQueryOptions, UseSuspenseQueryResult } from "./types.js";
 import { DefaultError, QueryClient, QueryKey } from "@tanstack/query-core";
 //#region src/useSuspenseQuery.d.ts
+/**
+ * The options for `useSuspenseQuery` are the same as for `useQuery`, except for `throwOnError`, `enabled`, and
+ * `placeholderData` — and `queryFn` may not be `skipToken`, since Suspense hooks can't render a "disabled" state.
+ *
+ * Caveat: cancellation does not work.
+ *
+ * @remarks Multiple `useSuspenseQuery` calls in the same component suspend serially, causing a request
+ * waterfall — each one blocks rendering until it resolves, so the next doesn't even start fetching until then.
+ * Use {@link useSuspenseQueries} instead when you have more than one suspenseful query in a component, so they
+ * fetch in parallel.
+ * @param options - The {@link UseSuspenseQueryOptions} to use — the same options as `useQuery`, minus the ones listed above.
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns The same object as `useQuery`, except that `data` is guaranteed to be defined, `isPlaceholderData`
+ * is missing, and `status` is either `success` or `error` (with the derived flags set accordingly).
+ *
+ * @example
+ * The query error is thrown if the fetch fails and no cached data exists yet, so an error boundary is
+ * required around `<Suspense>`. A failed background refetch instead continues to render the cached data.
+ * Use {@link QueryErrorResetBoundary} to let the user retry after such an error:
+ * ```tsx
+ * import { Suspense } from 'react'
+ * import { ErrorBoundary } from 'react-error-boundary'
+ * import { QueryErrorResetBoundary, useSuspenseQuery } from '@tanstack/react-query'
+ *
+ * function Posts() {
+ *   // `data` is guaranteed to be defined here — no `isPending` check needed.
+ *   const { data, isFetching } = useSuspenseQuery({
+ *     queryKey: ['posts'],
+ *     queryFn: fetchPosts,
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <h1>Posts {isFetching ? '(refreshing...)' : null}</h1>
+ *       <ul>
+ *         {data.map((post) => (
+ *           <li key={post.id}>{post.title}</li>
+ *         ))}
+ *       </ul>
+ *     </div>
+ *   )
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <QueryErrorResetBoundary>
+ *       {({ reset }) => (
+ *         <ErrorBoundary
+ *           onReset={reset}
+ *           fallbackRender={({ resetErrorBoundary }) => (
+ *             <div>
+ *               There was an error!
+ *               <button onClick={() => resetErrorBoundary()}>Try again</button>
+ *             </div>
+ *           )}
+ *         >
+ *           <Suspense fallback={<h1>Loading posts...</h1>}>
+ *             <Posts />
+ *           </Suspense>
+ *         </ErrorBoundary>
+ *       )}
+ *     </QueryErrorResetBoundary>
+ *   )
+ * }
+ * ```
+ */
 declare function useSuspenseQuery<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(options: UseSuspenseQueryOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: QueryClient): UseSuspenseQueryResult<TData, TError>;
 //#endregion
 export { useSuspenseQuery };

package/build/modern/useSuspenseQuery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useSuspenseQuery.d.ts","names":[],"sources":["../../src/useSuspenseQuery.ts"],"mappings":";;;iBAOgB,iBACd,wBACA,SAAS,cACT,QAAQ,cACR,kBAAkB,WAAW,UAE7B,SAAS,wBAAwB,cAAc,QAAQ,OAAO,YAC9D,cAAc,cACb,uBAAuB,OAAO"}
+{"version":3,"file":"useSuspenseQuery.d.ts","names":[],"sources":["../../src/useSuspenseQuery.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0EgB,iBACd,wBACA,SAAS,cACT,QAAQ,cACR,kBAAkB,WAAW,UAE7B,SAAS,wBAAwB,cAAc,QAAQ,OAAO,YAC9D,cAAc,cACb,uBAAuB,OAAO"}

package/build/modern/useSuspenseQuery.js

@@ -3,6 +3,73 @@ import { defaultThrowOnError } from "./suspense.js";
 import { useBaseQuery } from "./useBaseQuery.js";
 import { QueryObserver, skipToken } from "@tanstack/query-core";
 //#region src/useSuspenseQuery.ts
+/**
+* The options for `useSuspenseQuery` are the same as for `useQuery`, except for `throwOnError`, `enabled`, and
+* `placeholderData` — and `queryFn` may not be `skipToken`, since Suspense hooks can't render a "disabled" state.
+*
+* Caveat: cancellation does not work.
+*
+* @remarks Multiple `useSuspenseQuery` calls in the same component suspend serially, causing a request
+* waterfall — each one blocks rendering until it resolves, so the next doesn't even start fetching until then.
+* Use {@link useSuspenseQueries} instead when you have more than one suspenseful query in a component, so they
+* fetch in parallel.
+* @param options - The {@link UseSuspenseQueryOptions} to use — the same options as `useQuery`, minus the ones listed above.
+* @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+* be used.
+* @returns The same object as `useQuery`, except that `data` is guaranteed to be defined, `isPlaceholderData`
+* is missing, and `status` is either `success` or `error` (with the derived flags set accordingly).
+*
+* @example
+* The query error is thrown if the fetch fails and no cached data exists yet, so an error boundary is
+* required around `<Suspense>`. A failed background refetch instead continues to render the cached data.
+* Use {@link QueryErrorResetBoundary} to let the user retry after such an error:
+* ```tsx
+* import { Suspense } from 'react'
+* import { ErrorBoundary } from 'react-error-boundary'
+* import { QueryErrorResetBoundary, useSuspenseQuery } from '@tanstack/react-query'
+*
+* function Posts() {
+*   // `data` is guaranteed to be defined here — no `isPending` check needed.
+*   const { data, isFetching } = useSuspenseQuery({
+*     queryKey: ['posts'],
+*     queryFn: fetchPosts,
+*   })
+*
+*   return (
+*     <div>
+*       <h1>Posts {isFetching ? '(refreshing...)' : null}</h1>
+*       <ul>
+*         {data.map((post) => (
+*           <li key={post.id}>{post.title}</li>
+*         ))}
+*       </ul>
+*     </div>
+*   )
+* }
+*
+* function App() {
+*   return (
+*     <QueryErrorResetBoundary>
+*       {({ reset }) => (
+*         <ErrorBoundary
+*           onReset={reset}
+*           fallbackRender={({ resetErrorBoundary }) => (
+*             <div>
+*               There was an error!
+*               <button onClick={() => resetErrorBoundary()}>Try again</button>
+*             </div>
+*           )}
+*         >
+*           <Suspense fallback={<h1>Loading posts...</h1>}>
+*             <Posts />
+*           </Suspense>
+*         </ErrorBoundary>
+*       )}
+*     </QueryErrorResetBoundary>
+*   )
+* }
+* ```
+*/
 function useSuspenseQuery(options, queryClient) {
 	if (process.env.NODE_ENV !== "production") {
 		if (options.queryFn === skipToken) console.error("skipToken is not allowed for useSuspenseQuery");

package/build/modern/useSuspenseQuery.js.map

@@ -1 +1 @@
-{"version":3,"file":"useSuspenseQuery.js","names":[],"sources":["../../src/useSuspenseQuery.ts"],"sourcesContent":["'use client'\nimport { QueryObserver, skipToken } from '@tanstack/query-core'\nimport { useBaseQuery } from './useBaseQuery'\nimport { defaultThrowOnError } from './suspense'\nimport type { UseSuspenseQueryOptions, UseSuspenseQueryResult } from './types'\nimport type { DefaultError, QueryClient, QueryKey } from '@tanstack/query-core'\n\nexport function useSuspenseQuery<\n  TQueryFnData = unknown,\n  TError = DefaultError,\n  TData = TQueryFnData,\n  TQueryKey extends QueryKey = QueryKey,\n>(\n  options: UseSuspenseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,\n  queryClient?: QueryClient,\n): UseSuspenseQueryResult<TData, TError> {\n  if (process.env.NODE_ENV !== 'production') {\n    if ((options.queryFn as any) === skipToken) {\n      console.error('skipToken is not allowed for useSuspenseQuery')\n    }\n  }\n\n  return useBaseQuery(\n    {\n      ...options,\n      enabled: true,\n      suspense: true,\n      throwOnError: defaultThrowOnError,\n      placeholderData: undefined,\n    },\n    QueryObserver,\n    queryClient,\n  ) as UseSuspenseQueryResult<TData, TError>\n}\n"],"mappings":";;;;;AAOA,SAAgB,iBAMd,SACA,aACuC;CACvC,IAAI,QAAQ,IAAI,aAAa,cACtB;MAAA,QAAQ,YAAoB,WAC/B,QAAQ,MAAM,+CAA+C;CAAA;CAIjE,OAAO,aACL;EACE,GAAG;EACH,SAAS;EACT,UAAU;EACV,cAAc;EACd,iBAAiB,KAAA;CACnB,GACA,eACA,WACF;AACF"}
+{"version":3,"file":"useSuspenseQuery.js","names":[],"sources":["../../src/useSuspenseQuery.ts"],"sourcesContent":["'use client'\nimport { QueryObserver, skipToken } from '@tanstack/query-core'\nimport { useBaseQuery } from './useBaseQuery'\nimport { defaultThrowOnError } from './suspense'\nimport type { UseSuspenseQueryOptions, UseSuspenseQueryResult } from './types'\nimport type { DefaultError, QueryClient, QueryKey } from '@tanstack/query-core'\n\n/**\n * The options for `useSuspenseQuery` are the same as for `useQuery`, except for `throwOnError`, `enabled`, and\n * `placeholderData` — and `queryFn` may not be `skipToken`, since Suspense hooks can't render a \"disabled\" state.\n *\n * Caveat: cancellation does not work.\n *\n * @remarks Multiple `useSuspenseQuery` calls in the same component suspend serially, causing a request\n * waterfall — each one blocks rendering until it resolves, so the next doesn't even start fetching until then.\n * Use {@link useSuspenseQueries} instead when you have more than one suspenseful query in a component, so they\n * fetch in parallel.\n * @param options - The {@link UseSuspenseQueryOptions} to use — the same options as `useQuery`, minus the ones listed above.\n * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will\n * be used.\n * @returns The same object as `useQuery`, except that `data` is guaranteed to be defined, `isPlaceholderData`\n * is missing, and `status` is either `success` or `error` (with the derived flags set accordingly).\n *\n * @example\n * The query error is thrown if the fetch fails and no cached data exists yet, so an error boundary is\n * required around `<Suspense>`. A failed background refetch instead continues to render the cached data.\n * Use {@link QueryErrorResetBoundary} to let the user retry after such an error:\n * ```tsx\n * import { Suspense } from 'react'\n * import { ErrorBoundary } from 'react-error-boundary'\n * import { QueryErrorResetBoundary, useSuspenseQuery } from '@tanstack/react-query'\n *\n * function Posts() {\n *   // `data` is guaranteed to be defined here — no `isPending` check needed.\n *   const { data, isFetching } = useSuspenseQuery({\n *     queryKey: ['posts'],\n *     queryFn: fetchPosts,\n *   })\n *\n *   return (\n *     <div>\n *       <h1>Posts {isFetching ? '(refreshing...)' : null}</h1>\n *       <ul>\n *         {data.map((post) => (\n *           <li key={post.id}>{post.title}</li>\n *         ))}\n *       </ul>\n *     </div>\n *   )\n * }\n *\n * function App() {\n *   return (\n *     <QueryErrorResetBoundary>\n *       {({ reset }) => (\n *         <ErrorBoundary\n *           onReset={reset}\n *           fallbackRender={({ resetErrorBoundary }) => (\n *             <div>\n *               There was an error!\n *               <button onClick={() => resetErrorBoundary()}>Try again</button>\n *             </div>\n *           )}\n *         >\n *           <Suspense fallback={<h1>Loading posts...</h1>}>\n *             <Posts />\n *           </Suspense>\n *         </ErrorBoundary>\n *       )}\n *     </QueryErrorResetBoundary>\n *   )\n * }\n * ```\n */\nexport function useSuspenseQuery<\n  TQueryFnData = unknown,\n  TError = DefaultError,\n  TData = TQueryFnData,\n  TQueryKey extends QueryKey = QueryKey,\n>(\n  options: UseSuspenseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,\n  queryClient?: QueryClient,\n): UseSuspenseQueryResult<TData, TError> {\n  if (process.env.NODE_ENV !== 'production') {\n    if ((options.queryFn as any) === skipToken) {\n      console.error('skipToken is not allowed for useSuspenseQuery')\n    }\n  }\n\n  return useBaseQuery(\n    {\n      ...options,\n      enabled: true,\n      suspense: true,\n      throwOnError: defaultThrowOnError,\n      placeholderData: undefined,\n    },\n    QueryObserver,\n    queryClient,\n  ) as UseSuspenseQueryResult<TData, TError>\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0EA,SAAgB,iBAMd,SACA,aACuC;CACvC,IAAI,QAAQ,IAAI,aAAa,cACtB;MAAA,QAAQ,YAAoB,WAC/B,QAAQ,MAAM,+CAA+C;CAAA;CAIjE,OAAO,aACL;EACE,GAAG;EACH,SAAS;EACT,UAAU;EACV,cAAc;EACd,iBAAiB,KAAA;CACnB,GACA,eACA,WACF;AACF"}

package/build/query-codemods/eslint.config.js

@@ -15,4 +15,11 @@ export default [
       'sort-imports': 'off',
     },
   },
+  {
+    files: ['src/**/__testfixtures__/**'],
+    rules: {
+      // Codemod fixtures intentionally preserve historical QueryClient syntax.
+      'no-restricted-syntax': 'off',
+    },
+  },
 ]

package/build/query-codemods/root.eslint.config.js

@@ -44,6 +44,51 @@ export default [
       '@typescript-eslint/no-empty-function': 'off',
       '@typescript-eslint/no-unsafe-function-type': 'off',
       'no-case-declarations': 'off',
+      /**
+       * Disallows direct calls to deprecated imperative query methods of `QueryClient`
+       * for new tests and code
+       *
+       * Existing tests that directly test the methods from before the refactoring
+       * will be grandfathered in and allowed to continue using the deprecated methods.
+       * They should not be removed, but new tests should use the new methods instead.
+       */
+      'no-restricted-syntax': [
+        'error',
+        {
+          selector:
+            'CallExpression[callee.type="MemberExpression"]:matches([callee.property.name="fetchQuery"], [callee.computed=true][callee.property.value="fetchQuery"])',
+          message: 'Use queryClient.query(options) instead.',
+        },
+        {
+          selector:
+            'CallExpression[callee.type="MemberExpression"]:matches([callee.property.name="prefetchQuery"], [callee.computed=true][callee.property.value="prefetchQuery"])',
+          message:
+            'Use queryClient.query(options).catch(noop) instead if errors should be swallowed.',
+        },
+        {
+          selector:
+            'CallExpression[callee.type="MemberExpression"]:matches([callee.property.name="ensureQueryData"], [callee.computed=true][callee.property.value="ensureQueryData"])',
+          message:
+            "Use queryClient.query({ ...options, staleTime: 'static' }) instead.",
+        },
+        {
+          selector:
+            'CallExpression[callee.type="MemberExpression"]:matches([callee.property.name="fetchInfiniteQuery"], [callee.computed=true][callee.property.value="fetchInfiniteQuery"])',
+          message: 'Use queryClient.infiniteQuery(options) instead.',
+        },
+        {
+          selector:
+            'CallExpression[callee.type="MemberExpression"]:matches([callee.property.name="prefetchInfiniteQuery"], [callee.computed=true][callee.property.value="prefetchInfiniteQuery"])',
+          message:
+            'Use queryClient.infiniteQuery(options).catch(noop) instead if errors should be swallowed.',
+        },
+        {
+          selector:
+            'CallExpression[callee.type="MemberExpression"]:matches([callee.property.name="ensureInfiniteQueryData"], [callee.computed=true][callee.property.value="ensureInfiniteQueryData"])',
+          message:
+            "Use queryClient.infiniteQuery({ ...options, staleTime: 'static' }) instead.",
+        },
+      ],
       'prefer-const': 'off',
     },
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/react-query",
-  "version": "5.102.8",
+  "version": "5.103.0",
   "description": "Hooks for managing, caching and syncing asynchronous and remote data in React",
   "author": "tannerlinsley",
   "license": "MIT",
@@ -44,7 +44,7 @@
     "!build/codemods/**/__tests__"
   ],
   "dependencies": {
-    "@tanstack/query-core": "5.102.8"
+    "@tanstack/query-core": "5.103.0"
   },
   "devDependencies": {
     "@testing-library/react": "^16.1.0",
@@ -57,23 +57,23 @@
     "react": "^19.2.1",
     "react-dom": "^19.2.1",
     "react-error-boundary": "^4.1.2",
-    "@tanstack/query-persist-client-core": "5.102.8",
+    "@tanstack/query-persist-client-core": "5.103.0",
     "@tanstack/query-test-utils": "0.0.0"
   },
   "peerDependencies": {
     "react": "^18 || ^19"
   },
   "scripts": {
-    "clean": "premove ./build ./coverage ./dist-ts",
-    "compile": "tsc --build",
+    "clean": "premove ./build ./coverage ./dist-ts ./.cache/test-types",
+    "compile": "tsc --project tsconfig.json",
     "test:eslint": "eslint --concurrency=auto ./src",
     "test:types": "npm-run-all --serial test:types:*",
-    "test:types:ts56": "node ../../node_modules/typescript56/lib/tsc.js --build tsconfig.legacy.json",
-    "test:types:ts57": "node ../../node_modules/typescript57/lib/tsc.js --build tsconfig.legacy.json",
-    "test:types:ts58": "node ../../node_modules/typescript58/lib/tsc.js --build tsconfig.legacy.json",
-    "test:types:ts59": "node ../../node_modules/typescript59/lib/tsc.js --build tsconfig.legacy.json",
-    "test:types:tscurrent": "tsc --build",
-    "test:types:ts70": "node ../../node_modules/typescript70/lib/tsc.js --build",
+    "test:types:ts56": "node ../../node_modules/typescript56/lib/tsc.js --project tsconfig.legacy.json --outDir .cache/test-types/ts56 --tsBuildInfoFile .cache/test-types/ts56.tsbuildinfo",
+    "test:types:ts57": "node ../../node_modules/typescript57/lib/tsc.js --project tsconfig.legacy.json --outDir .cache/test-types/ts57 --tsBuildInfoFile .cache/test-types/ts57.tsbuildinfo",
+    "test:types:ts58": "node ../../node_modules/typescript58/lib/tsc.js --project tsconfig.legacy.json --outDir .cache/test-types/ts58 --tsBuildInfoFile .cache/test-types/ts58.tsbuildinfo",
+    "test:types:ts59": "node ../../node_modules/typescript59/lib/tsc.js --project tsconfig.legacy.json --outDir .cache/test-types/ts59 --tsBuildInfoFile .cache/test-types/ts59.tsbuildinfo",
+    "test:types:tscurrent": "tsc --project tsconfig.json --outDir .cache/test-types/tscurrent --tsBuildInfoFile .cache/test-types/tscurrent.tsbuildinfo",
+    "test:types:ts70": "node ../../node_modules/typescript70/lib/tsc.js --project tsconfig.json --outDir .cache/test-types/ts70 --tsBuildInfoFile .cache/test-types/ts70.tsbuildinfo",
     "test:lib": "vitest",
     "test:lib:dev": "pnpm run test:lib --watch",
     "test:build": "publint --strict && attw --pack",

package/src/HydrationBoundary.tsx

@@ -10,18 +10,79 @@ import type {
   QueryClient,
 } from '@tanstack/query-core'
 
+/**
+ * The props accepted by `HydrationBoundary`.
+ */
 export interface HydrationBoundaryProps {
+  /**
+   * The state to hydrate.
+   */
   state: DehydratedState | null | undefined
+  /**
+   * Optional. Note: unlike `hydrate`, `mutations` cannot be set here.
+   */
   options?: OmitKeyof<HydrateOptions, 'defaultOptions'> & {
     defaultOptions?: OmitKeyof<
       Exclude<HydrateOptions['defaultOptions'], undefined>,
       'mutations'
     >
   }
+  /**
+   * The components to render — always rendered unconditionally, not gated on hydration. New queries are
+   * hydrated into the cache during render; for queries that already exist in the cache, only newer dehydrated
+   * data is hydrated, and that happens in an effect after commit, so `children` may render briefly before it
+   * lands.
+   */
   children?: React.ReactNode
+  /**
+   * Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will be used.
+   */
   queryClient?: QueryClient
 }
 
+/**
+ * `HydrationBoundary` adds a previously dehydrated state into the `queryClient` that would be returned by
+ * `useQueryClient()`. If the client already contains data, the new queries will be intelligently merged based on
+ * update timestamp.
+ *
+ * Note: Only `queries` can be dehydrated with an `HydrationBoundary`.
+ *
+ * @returns The provided `children`, rendered unconditionally. New queries in `state` are hydrated into the
+ * cache during render; for queries already in the cache, only newer dehydrated data is hydrated, in an effect
+ * after commit.
+ *
+ * @example
+ * ```tsx
+ * import { HydrationBoundary } from '@tanstack/react-query'
+ *
+ * function App() {
+ *   return <HydrationBoundary state={dehydratedState}>...</HydrationBoundary>
+ * }
+ * ```
+ *
+ * @example
+ * Server-side prefetch handed off to the client via `dehydrate`:
+ * ```tsx
+ * import { HydrationBoundary, dehydrate, noop } from '@tanstack/react-query'
+ *
+ * async function ServerComponent() {
+ *   const queryClient = getQueryClient()
+ *
+ *   await queryClient
+ *     .query({
+ *       queryKey: ['posts'],
+ *       queryFn: fetchPosts,
+ *     })
+ *     .catch(noop)
+ *
+ *   return (
+ *     <HydrationBoundary state={dehydrate(queryClient)}>
+ *       <Posts />
+ *     </HydrationBoundary>
+ *   )
+ * }
+ * ```
+ */
 export const HydrationBoundary = ({
   children,
   options = {},
@@ -78,7 +139,6 @@ export const HydrationBoundary = ({
               (dehydratedQuery.promise &&
                 existingQuery.state.status !== 'pending' &&
                 existingQuery.state.fetchStatus !== 'fetching' &&
-                dehydratedQuery.dehydratedAt !== undefined &&
                 dehydratedQuery.dehydratedAt >
                   existingQuery.state.dataUpdatedAt)
 

package/src/IsRestoringProvider.ts

@@ -3,5 +3,17 @@ import * as React from 'react'
 
 const IsRestoringContext = React.createContext(false)
 
+/**
+ * If you are using `PersistQueryClientProvider`, you can also use the `useIsRestoring` hook alongside it to
+ * check if a restore is currently in progress. `useQuery` and friends also check this internally to avoid
+ * race conditions between the restore and mounting queries.
+ *
+ * @returns `true` while a persisted client is being restored, `false` otherwise.
+ */
 export const useIsRestoring = () => React.useContext(IsRestoringContext)
+
+/**
+ * The Provider that `PersistQueryClientProvider` uses to signal whether a persisted client is currently
+ * being restored, read by `useIsRestoring`.
+ */
 export const IsRestoringProvider = IsRestoringContext.Provider

package/src/QueryClientProvider.tsx

@@ -3,10 +3,21 @@ import * as React from 'react'
 
 import type { QueryClient } from '@tanstack/query-core'
 
+/**
+ * The context that `useQueryClient` reads from. `QueryClientProvider` is the normal way to set it.
+ */
 export const QueryClientContext = React.createContext<QueryClient | undefined>(
   undefined,
 )
 
+/**
+ * The `useQueryClient` hook returns the current `QueryClient` instance.
+ *
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns The current `QueryClient` instance.
+ * @throws If no `queryClient` argument is passed and no `QueryClientProvider` is found in the component tree.
+ */
 export const useQueryClient = (queryClient?: QueryClient) => {
   const client = React.useContext(QueryClientContext)
 
@@ -21,11 +32,41 @@ export const useQueryClient = (queryClient?: QueryClient) => {
   return client
 }
 
+/**
+ * The props accepted by `QueryClientProvider`.
+ */
 export type QueryClientProviderProps = {
+  /**
+   * **Required**
+   *
+   * The `QueryClient` instance to provide.
+   */
   client: QueryClient
+  /**
+   * The components that get access to the provided `QueryClient`.
+   */
   children?: React.ReactNode
 }
 
+/**
+ * Use the `QueryClientProvider` component to connect and provide a `QueryClient` to your application. Also
+ * calls `client.mount()`/`client.unmount()` as this component mounts/unmounts, which subscribes the client to
+ * focus/online events (resuming any paused mutations and refetching as needed when the app regains focus or
+ * comes back online).
+ *
+ * @returns The provided `children`, wrapped so they can read the `QueryClient` via `useQueryClient`.
+ *
+ * @example
+ * ```tsx
+ * import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+ *
+ * const queryClient = new QueryClient()
+ *
+ * function App() {
+ *   return <QueryClientProvider client={queryClient}>...</QueryClientProvider>
+ * }
+ * ```
+ */
 export const QueryClientProvider = ({
   client,
   children,

package/src/QueryErrorResetBoundary.tsx

@@ -12,15 +12,27 @@ export interface QueryErrorResetBoundaryValue {
   reset: QueryErrorResetFunction
 }
 
+/**
+ * Resets any query errors within the boundary, so queries know they can try again.
+ */
 function createValue(): QueryErrorResetBoundaryValue {
   let isReset = false
   return {
+    /**
+     * Clears the reset state, so queries know not to try again until the boundary is reset again.
+     */
     clearReset: () => {
       isReset = false
     },
+    /**
+     * Resets any query errors within the boundary, so queries know they can try again.
+     */
     reset: () => {
       isReset = true
     },
+    /**
+     * Returns whether the boundary has been reset and not yet cleared.
+     */
     isReset: () => {
       return isReset
     },
@@ -31,19 +43,96 @@ const QueryErrorResetBoundaryContext = React.createContext(createValue())
 
 // HOOK
 
+/**
+ * This hook will reset any query errors within the closest `QueryErrorResetBoundary`. If there is no boundary
+ * defined it will reset them globally.
+ *
+ * @returns The boundary's {@link QueryErrorResetBoundaryValue}.
+ *
+ * @example
+ * ```tsx
+ * import { ErrorBoundary } from 'react-error-boundary'
+ * import { useQueryErrorResetBoundary } from '@tanstack/react-query'
+ *
+ * function App({ children }: { children: React.ReactNode }) {
+ *   const { reset } = useQueryErrorResetBoundary()
+ *
+ *   return (
+ *     <ErrorBoundary
+ *       onReset={reset}
+ *       fallbackRender={({ resetErrorBoundary }) => (
+ *         <div>
+ *           There was an error!
+ *           <button onClick={() => resetErrorBoundary()}>Try again</button>
+ *         </div>
+ *       )}
+ *     >
+ *       {children}
+ *     </ErrorBoundary>
+ *   )
+ * }
+ * ```
+ */
 export const useQueryErrorResetBoundary = () =>
   React.useContext(QueryErrorResetBoundaryContext)
 
 // COMPONENT
 
+/**
+ * A render-prop function usable as `children` on `QueryErrorResetBoundary`.
+ *
+ * @param value - The boundary's {@link QueryErrorResetBoundaryValue}.
+ * @returns The children to render.
+ */
 export type QueryErrorResetBoundaryFunction = (
   value: QueryErrorResetBoundaryValue,
 ) => React.ReactNode
 
+/**
+ * The props accepted by `QueryErrorResetBoundary`.
+ */
 export interface QueryErrorResetBoundaryProps {
+  /**
+   * Either a plain node, or a function that receives the boundary's {@link QueryErrorResetBoundaryValue} and
+   * returns a node.
+   */
   children: QueryErrorResetBoundaryFunction | React.ReactNode
 }
 
+/**
+ * When using `suspense` or `throwOnError` in your queries, you need a way to let queries know that you want to
+ * try again when re-rendering after some error occurred. With the `QueryErrorResetBoundary` component you can
+ * reset any query errors within the boundaries of the component.
+ *
+ * @returns The `children`, rendered as-is, or called with the boundary's {@link QueryErrorResetBoundaryValue}
+ * if `children` is a function.
+ *
+ * @example
+ * ```tsx
+ * import { ErrorBoundary } from 'react-error-boundary'
+ * import { QueryErrorResetBoundary } from '@tanstack/react-query'
+ *
+ * function App() {
+ *   return (
+ *     <QueryErrorResetBoundary>
+ *       {({ reset }) => (
+ *         <ErrorBoundary
+ *           onReset={reset}
+ *           fallbackRender={({ resetErrorBoundary }) => (
+ *             <div>
+ *               There was an error!
+ *               <button onClick={() => resetErrorBoundary()}>Try again</button>
+ *             </div>
+ *           )}
+ *         >
+ *           <Page />
+ *         </ErrorBoundary>
+ *       )}
+ *     </QueryErrorResetBoundary>
+ *   )
+ * }
+ * ```
+ */
 export const QueryErrorResetBoundary = ({
   children,
 }: QueryErrorResetBoundaryProps) => {