@tanstack/react-query 5.0.0-beta.25 → 5.0.0-beta.28

package/build/legacy/HydrationBoundary.cjs

@@ -44,13 +44,48 @@ var HydrationBoundary = ({
   queryClient
 }) => {
   const client = (0, import_QueryClientProvider.useQueryClient)(queryClient);
+  const [hydrationQueue, setHydrationQueue] = React.useState();
   const optionsRef = React.useRef(options);
   optionsRef.current = options;
   React.useMemo(() => {
     if (state) {
-      (0, import_query_core.hydrate)(client, state, optionsRef.current);
+      if (typeof state !== "object") {
+        return;
+      }
+      const queryCache = client.getQueryCache();
+      const queries = state.queries || [];
+      const newQueries = [];
+      const existingQueries = [];
+      for (const dehydratedQuery of queries) {
+        const existingQuery = queryCache.get(dehydratedQuery.queryHash);
+        if (!existingQuery) {
+          newQueries.push(dehydratedQuery);
+        } else {
+          const hydrationIsNewer = dehydratedQuery.state.dataUpdatedAt > existingQuery.state.dataUpdatedAt;
+          const queryAlreadyQueued = hydrationQueue == null ? void 0 : hydrationQueue.find(
+            (query) => query.queryHash === dehydratedQuery.queryHash
+          );
+          if (hydrationIsNewer && (!queryAlreadyQueued || dehydratedQuery.state.dataUpdatedAt > queryAlreadyQueued.state.dataUpdatedAt)) {
+            existingQueries.push(dehydratedQuery);
+          }
+        }
+      }
+      if (newQueries.length > 0) {
+        (0, import_query_core.hydrate)(client, { queries: newQueries }, optionsRef.current);
+      }
+      if (existingQueries.length > 0) {
+        setHydrationQueue(
+          (prev) => prev ? [...prev, ...existingQueries] : existingQueries
+        );
+      }
     }
-  }, [client, state]);
+  }, [client, hydrationQueue, state]);
+  React.useEffect(() => {
+    if (hydrationQueue) {
+      (0, import_query_core.hydrate)(client, { queries: hydrationQueue }, optionsRef.current);
+      setHydrationQueue(void 0);
+    }
+  }, [client, hydrationQueue]);
   return children;
 };
 // Annotate the CommonJS export names for ESM import in node:

package/build/legacy/HydrationBoundary.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/HydrationBoundary.tsx"],"sourcesContent":["'use client'\nimport * as React from 'react'\n\nimport { hydrate } from '@tanstack/query-core'\nimport { useQueryClient } from './QueryClientProvider'\nimport type { HydrateOptions, QueryClient } from '@tanstack/query-core'\n\nexport interface HydrationBoundaryProps {\n  state?: unknown\n  options?: HydrateOptions\n  children?: React.ReactNode\n  queryClient?: QueryClient\n}\n\nexport const HydrationBoundary = ({\n  children,\n  options = {},\n  state,\n  queryClient,\n}: HydrationBoundaryProps) => {\n  const client = useQueryClient(queryClient)\n\n  const optionsRef = React.useRef(options)\n  optionsRef.current = options\n\n  // Running hydrate again with the same queries is safe,\n  // it wont overwrite or initialize existing queries,\n  // relying on useMemo here is only a performance optimization.\n  // hydrate can and should be run *during* render here for SSR to work properly\n  React.useMemo(() => {\n    if (state) {\n      hydrate(client, state, optionsRef.current)\n    }\n  }, [client, state])\n\n  return children as React.ReactElement\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AACA,YAAuB;AAEvB,wBAAwB;AACxB,iCAA+B;AAUxB,IAAM,oBAAoB,CAAC;AAAA,EAChC;AAAA,EACA,UAAU,CAAC;AAAA,EACX;AAAA,EACA;AACF,MAA8B;AAC5B,QAAM,aAAS,2CAAe,WAAW;AAEzC,QAAM,aAAmB,aAAO,OAAO;AACvC,aAAW,UAAU;AAMrB,EAAM,cAAQ,MAAM;AAClB,QAAI,OAAO;AACT,qCAAQ,QAAQ,OAAO,WAAW,OAAO;AAAA,IAC3C;AAAA,EACF,GAAG,CAAC,QAAQ,KAAK,CAAC;AAElB,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../../src/HydrationBoundary.tsx"],"sourcesContent":["'use client'\nimport * as React from 'react'\n\nimport { hydrate } from '@tanstack/query-core'\nimport { useQueryClient } from './QueryClientProvider'\nimport type {\n  DehydratedState,\n  HydrateOptions,\n  QueryClient,\n} from '@tanstack/query-core'\n\nexport interface HydrationBoundaryProps {\n  state?: unknown\n  options?: Omit<HydrateOptions, 'defaultOptions'> & {\n    defaultOptions?: Omit<HydrateOptions['defaultOptions'], 'mutations'>\n  }\n  children?: React.ReactNode\n  queryClient?: QueryClient\n}\n\nexport const HydrationBoundary = ({\n  children,\n  options = {},\n  state,\n  queryClient,\n}: HydrationBoundaryProps) => {\n  const client = useQueryClient(queryClient)\n  const [hydrationQueue, setHydrationQueue] = React.useState<\n    DehydratedState['queries'] | undefined\n  >()\n\n  const optionsRef = React.useRef(options)\n  optionsRef.current = options\n\n  // This useMemo is for performance reasons only, everything inside it _must_\n  // be safe to run in every render and code here should be read as \"in render\".\n  //\n  // This code needs to happen during the render phase, because after initial\n  // SSR, hydration needs to happen _before_ children render. Also, if hydrating\n  // during a transition, we want to hydrate as much as is safe in render so\n  // we can prerender as much as possible.\n  //\n  // For any queries that already exist in the cache, we want to hold back on\n  // hydrating until _after_ the render phase. The reason for this is that during\n  // transitions, we don't want the existing queries and observers to update to\n  // the new data on the current page, only _after_ the transition is committed.\n  // If the transition is aborted, we will have hydrated any _new_ queries, but\n  // we throw away the fresh data for any existing ones to avoid unexpectedly\n  // updating the UI.\n  React.useMemo(() => {\n    if (state) {\n      if (typeof state !== 'object') {\n        return\n      }\n\n      const queryCache = client.getQueryCache()\n      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n      const queries = (state as DehydratedState).queries || []\n\n      const newQueries: DehydratedState['queries'] = []\n      const existingQueries: DehydratedState['queries'] = []\n      for (const dehydratedQuery of queries) {\n        const existingQuery = queryCache.get(dehydratedQuery.queryHash)\n\n        if (!existingQuery) {\n          newQueries.push(dehydratedQuery)\n        } else {\n          const hydrationIsNewer =\n            dehydratedQuery.state.dataUpdatedAt >\n            existingQuery.state.dataUpdatedAt\n          const queryAlreadyQueued = hydrationQueue?.find(\n            (query) => query.queryHash === dehydratedQuery.queryHash,\n          )\n\n          if (\n            hydrationIsNewer &&\n            (!queryAlreadyQueued ||\n              dehydratedQuery.state.dataUpdatedAt >\n                queryAlreadyQueued.state.dataUpdatedAt)\n          ) {\n            existingQueries.push(dehydratedQuery)\n          }\n        }\n      }\n\n      if (newQueries.length > 0) {\n        // It's actually fine to call this with queries/state that already exists\n        // in the cache, or is older. hydrate() is idempotent for queries.\n        hydrate(client, { queries: newQueries }, optionsRef.current)\n      }\n      if (existingQueries.length > 0) {\n        setHydrationQueue((prev) =>\n          prev ? [...prev, ...existingQueries] : existingQueries,\n        )\n      }\n    }\n  }, [client, hydrationQueue, state])\n\n  React.useEffect(() => {\n    if (hydrationQueue) {\n      hydrate(client, { queries: hydrationQueue }, optionsRef.current)\n      setHydrationQueue(undefined)\n    }\n  }, [client, hydrationQueue])\n\n  return children as React.ReactElement\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AACA,YAAuB;AAEvB,wBAAwB;AACxB,iCAA+B;AAgBxB,IAAM,oBAAoB,CAAC;AAAA,EAChC;AAAA,EACA,UAAU,CAAC;AAAA,EACX;AAAA,EACA;AACF,MAA8B;AAC5B,QAAM,aAAS,2CAAe,WAAW;AACzC,QAAM,CAAC,gBAAgB,iBAAiB,IAAU,eAEhD;AAEF,QAAM,aAAmB,aAAO,OAAO;AACvC,aAAW,UAAU;AAiBrB,EAAM,cAAQ,MAAM;AAClB,QAAI,OAAO;AACT,UAAI,OAAO,UAAU,UAAU;AAC7B;AAAA,MACF;AAEA,YAAM,aAAa,OAAO,cAAc;AAExC,YAAM,UAAW,MAA0B,WAAW,CAAC;AAEvD,YAAM,aAAyC,CAAC;AAChD,YAAM,kBAA8C,CAAC;AACrD,iBAAW,mBAAmB,SAAS;AACrC,cAAM,gBAAgB,WAAW,IAAI,gBAAgB,SAAS;AAE9D,YAAI,CAAC,eAAe;AAClB,qBAAW,KAAK,eAAe;AAAA,QACjC,OAAO;AACL,gBAAM,mBACJ,gBAAgB,MAAM,gBACtB,cAAc,MAAM;AACtB,gBAAM,qBAAqB,iDAAgB;AAAA,YACzC,CAAC,UAAU,MAAM,cAAc,gBAAgB;AAAA;AAGjD,cACE,qBACC,CAAC,sBACA,gBAAgB,MAAM,gBACpB,mBAAmB,MAAM,gBAC7B;AACA,4BAAgB,KAAK,eAAe;AAAA,UACtC;AAAA,QACF;AAAA,MACF;AAEA,UAAI,WAAW,SAAS,GAAG;AAGzB,uCAAQ,QAAQ,EAAE,SAAS,WAAW,GAAG,WAAW,OAAO;AAAA,MAC7D;AACA,UAAI,gBAAgB,SAAS,GAAG;AAC9B;AAAA,UAAkB,CAAC,SACjB,OAAO,CAAC,GAAG,MAAM,GAAG,eAAe,IAAI;AAAA,QACzC;AAAA,MACF;AAAA,IACF;AAAA,EACF,GAAG,CAAC,QAAQ,gBAAgB,KAAK,CAAC;AAElC,EAAM,gBAAU,MAAM;AACpB,QAAI,gBAAgB;AAClB,qCAAQ,QAAQ,EAAE,SAAS,eAAe,GAAG,WAAW,OAAO;AAC/D,wBAAkB,MAAS;AAAA,IAC7B;AAAA,EACF,GAAG,CAAC,QAAQ,cAAc,CAAC;AAE3B,SAAO;AACT;","names":[]}

package/build/legacy/HydrationBoundary.d.cts

@@ -3,7 +3,9 @@ import { HydrateOptions, QueryClient } from '@tanstack/query-core';
 
 interface HydrationBoundaryProps {
     state?: unknown;
-    options?: HydrateOptions;
+    options?: Omit<HydrateOptions, 'defaultOptions'> & {
+        defaultOptions?: Omit<HydrateOptions['defaultOptions'], 'mutations'>;
+    };
     children?: React.ReactNode;
     queryClient?: QueryClient;
 }

package/build/legacy/HydrationBoundary.d.ts

@@ -3,7 +3,9 @@ import { HydrateOptions, QueryClient } from '@tanstack/query-core';
 
 interface HydrationBoundaryProps {
     state?: unknown;
-    options?: HydrateOptions;
+    options?: Omit<HydrateOptions, 'defaultOptions'> & {
+        defaultOptions?: Omit<HydrateOptions['defaultOptions'], 'mutations'>;
+    };
     children?: React.ReactNode;
     queryClient?: QueryClient;
 }

package/build/legacy/HydrationBoundary.js

@@ -11,13 +11,48 @@ var HydrationBoundary = ({
   queryClient
 }) => {
   const client = useQueryClient(queryClient);
+  const [hydrationQueue, setHydrationQueue] = React.useState();
   const optionsRef = React.useRef(options);
   optionsRef.current = options;
   React.useMemo(() => {
     if (state) {
-      hydrate(client, state, optionsRef.current);
+      if (typeof state !== "object") {
+        return;
+      }
+      const queryCache = client.getQueryCache();
+      const queries = state.queries || [];
+      const newQueries = [];
+      const existingQueries = [];
+      for (const dehydratedQuery of queries) {
+        const existingQuery = queryCache.get(dehydratedQuery.queryHash);
+        if (!existingQuery) {
+          newQueries.push(dehydratedQuery);
+        } else {
+          const hydrationIsNewer = dehydratedQuery.state.dataUpdatedAt > existingQuery.state.dataUpdatedAt;
+          const queryAlreadyQueued = hydrationQueue == null ? void 0 : hydrationQueue.find(
+            (query) => query.queryHash === dehydratedQuery.queryHash
+          );
+          if (hydrationIsNewer && (!queryAlreadyQueued || dehydratedQuery.state.dataUpdatedAt > queryAlreadyQueued.state.dataUpdatedAt)) {
+            existingQueries.push(dehydratedQuery);
+          }
+        }
+      }
+      if (newQueries.length > 0) {
+        hydrate(client, { queries: newQueries }, optionsRef.current);
+      }
+      if (existingQueries.length > 0) {
+        setHydrationQueue(
+          (prev) => prev ? [...prev, ...existingQueries] : existingQueries
+        );
+      }
     }
-  }, [client, state]);
+  }, [client, hydrationQueue, state]);
+  React.useEffect(() => {
+    if (hydrationQueue) {
+      hydrate(client, { queries: hydrationQueue }, optionsRef.current);
+      setHydrationQueue(void 0);
+    }
+  }, [client, hydrationQueue]);
   return children;
 };
 export {

package/build/legacy/HydrationBoundary.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/HydrationBoundary.tsx"],"sourcesContent":["'use client'\nimport * as React from 'react'\n\nimport { hydrate } from '@tanstack/query-core'\nimport { useQueryClient } from './QueryClientProvider'\nimport type { HydrateOptions, QueryClient } from '@tanstack/query-core'\n\nexport interface HydrationBoundaryProps {\n  state?: unknown\n  options?: HydrateOptions\n  children?: React.ReactNode\n  queryClient?: QueryClient\n}\n\nexport const HydrationBoundary = ({\n  children,\n  options = {},\n  state,\n  queryClient,\n}: HydrationBoundaryProps) => {\n  const client = useQueryClient(queryClient)\n\n  const optionsRef = React.useRef(options)\n  optionsRef.current = options\n\n  // Running hydrate again with the same queries is safe,\n  // it wont overwrite or initialize existing queries,\n  // relying on useMemo here is only a performance optimization.\n  // hydrate can and should be run *during* render here for SSR to work properly\n  React.useMemo(() => {\n    if (state) {\n      hydrate(client, state, optionsRef.current)\n    }\n  }, [client, state])\n\n  return children as React.ReactElement\n}\n"],"mappings":";;;AACA,YAAY,WAAW;AAEvB,SAAS,eAAe;AACxB,SAAS,sBAAsB;AAUxB,IAAM,oBAAoB,CAAC;AAAA,EAChC;AAAA,EACA,UAAU,CAAC;AAAA,EACX;AAAA,EACA;AACF,MAA8B;AAC5B,QAAM,SAAS,eAAe,WAAW;AAEzC,QAAM,aAAmB,aAAO,OAAO;AACvC,aAAW,UAAU;AAMrB,EAAM,cAAQ,MAAM;AAClB,QAAI,OAAO;AACT,cAAQ,QAAQ,OAAO,WAAW,OAAO;AAAA,IAC3C;AAAA,EACF,GAAG,CAAC,QAAQ,KAAK,CAAC;AAElB,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../../src/HydrationBoundary.tsx"],"sourcesContent":["'use client'\nimport * as React from 'react'\n\nimport { hydrate } from '@tanstack/query-core'\nimport { useQueryClient } from './QueryClientProvider'\nimport type {\n  DehydratedState,\n  HydrateOptions,\n  QueryClient,\n} from '@tanstack/query-core'\n\nexport interface HydrationBoundaryProps {\n  state?: unknown\n  options?: Omit<HydrateOptions, 'defaultOptions'> & {\n    defaultOptions?: Omit<HydrateOptions['defaultOptions'], 'mutations'>\n  }\n  children?: React.ReactNode\n  queryClient?: QueryClient\n}\n\nexport const HydrationBoundary = ({\n  children,\n  options = {},\n  state,\n  queryClient,\n}: HydrationBoundaryProps) => {\n  const client = useQueryClient(queryClient)\n  const [hydrationQueue, setHydrationQueue] = React.useState<\n    DehydratedState['queries'] | undefined\n  >()\n\n  const optionsRef = React.useRef(options)\n  optionsRef.current = options\n\n  // This useMemo is for performance reasons only, everything inside it _must_\n  // be safe to run in every render and code here should be read as \"in render\".\n  //\n  // This code needs to happen during the render phase, because after initial\n  // SSR, hydration needs to happen _before_ children render. Also, if hydrating\n  // during a transition, we want to hydrate as much as is safe in render so\n  // we can prerender as much as possible.\n  //\n  // For any queries that already exist in the cache, we want to hold back on\n  // hydrating until _after_ the render phase. The reason for this is that during\n  // transitions, we don't want the existing queries and observers to update to\n  // the new data on the current page, only _after_ the transition is committed.\n  // If the transition is aborted, we will have hydrated any _new_ queries, but\n  // we throw away the fresh data for any existing ones to avoid unexpectedly\n  // updating the UI.\n  React.useMemo(() => {\n    if (state) {\n      if (typeof state !== 'object') {\n        return\n      }\n\n      const queryCache = client.getQueryCache()\n      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n      const queries = (state as DehydratedState).queries || []\n\n      const newQueries: DehydratedState['queries'] = []\n      const existingQueries: DehydratedState['queries'] = []\n      for (const dehydratedQuery of queries) {\n        const existingQuery = queryCache.get(dehydratedQuery.queryHash)\n\n        if (!existingQuery) {\n          newQueries.push(dehydratedQuery)\n        } else {\n          const hydrationIsNewer =\n            dehydratedQuery.state.dataUpdatedAt >\n            existingQuery.state.dataUpdatedAt\n          const queryAlreadyQueued = hydrationQueue?.find(\n            (query) => query.queryHash === dehydratedQuery.queryHash,\n          )\n\n          if (\n            hydrationIsNewer &&\n            (!queryAlreadyQueued ||\n              dehydratedQuery.state.dataUpdatedAt >\n                queryAlreadyQueued.state.dataUpdatedAt)\n          ) {\n            existingQueries.push(dehydratedQuery)\n          }\n        }\n      }\n\n      if (newQueries.length > 0) {\n        // It's actually fine to call this with queries/state that already exists\n        // in the cache, or is older. hydrate() is idempotent for queries.\n        hydrate(client, { queries: newQueries }, optionsRef.current)\n      }\n      if (existingQueries.length > 0) {\n        setHydrationQueue((prev) =>\n          prev ? [...prev, ...existingQueries] : existingQueries,\n        )\n      }\n    }\n  }, [client, hydrationQueue, state])\n\n  React.useEffect(() => {\n    if (hydrationQueue) {\n      hydrate(client, { queries: hydrationQueue }, optionsRef.current)\n      setHydrationQueue(undefined)\n    }\n  }, [client, hydrationQueue])\n\n  return children as React.ReactElement\n}\n"],"mappings":";;;AACA,YAAY,WAAW;AAEvB,SAAS,eAAe;AACxB,SAAS,sBAAsB;AAgBxB,IAAM,oBAAoB,CAAC;AAAA,EAChC;AAAA,EACA,UAAU,CAAC;AAAA,EACX;AAAA,EACA;AACF,MAA8B;AAC5B,QAAM,SAAS,eAAe,WAAW;AACzC,QAAM,CAAC,gBAAgB,iBAAiB,IAAU,eAEhD;AAEF,QAAM,aAAmB,aAAO,OAAO;AACvC,aAAW,UAAU;AAiBrB,EAAM,cAAQ,MAAM;AAClB,QAAI,OAAO;AACT,UAAI,OAAO,UAAU,UAAU;AAC7B;AAAA,MACF;AAEA,YAAM,aAAa,OAAO,cAAc;AAExC,YAAM,UAAW,MAA0B,WAAW,CAAC;AAEvD,YAAM,aAAyC,CAAC;AAChD,YAAM,kBAA8C,CAAC;AACrD,iBAAW,mBAAmB,SAAS;AACrC,cAAM,gBAAgB,WAAW,IAAI,gBAAgB,SAAS;AAE9D,YAAI,CAAC,eAAe;AAClB,qBAAW,KAAK,eAAe;AAAA,QACjC,OAAO;AACL,gBAAM,mBACJ,gBAAgB,MAAM,gBACtB,cAAc,MAAM;AACtB,gBAAM,qBAAqB,iDAAgB;AAAA,YACzC,CAAC,UAAU,MAAM,cAAc,gBAAgB;AAAA;AAGjD,cACE,qBACC,CAAC,sBACA,gBAAgB,MAAM,gBACpB,mBAAmB,MAAM,gBAC7B;AACA,4BAAgB,KAAK,eAAe;AAAA,UACtC;AAAA,QACF;AAAA,MACF;AAEA,UAAI,WAAW,SAAS,GAAG;AAGzB,gBAAQ,QAAQ,EAAE,SAAS,WAAW,GAAG,WAAW,OAAO;AAAA,MAC7D;AACA,UAAI,gBAAgB,SAAS,GAAG;AAC9B;AAAA,UAAkB,CAAC,SACjB,OAAO,CAAC,GAAG,MAAM,GAAG,eAAe,IAAI;AAAA,QACzC;AAAA,MACF;AAAA,IACF;AAAA,EACF,GAAG,CAAC,QAAQ,gBAAgB,KAAK,CAAC;AAElC,EAAM,gBAAU,MAAM;AACpB,QAAI,gBAAgB;AAClB,cAAQ,QAAQ,EAAE,SAAS,eAAe,GAAG,WAAW,OAAO;AAC/D,wBAAkB,MAAS;AAAA,IAC7B;AAAA,EACF,GAAG,CAAC,QAAQ,cAAc,CAAC;AAE3B,SAAO;AACT;","names":[]}

package/build/modern/HydrationBoundary.cjs

@@ -44,13 +44,48 @@ var HydrationBoundary = ({
   queryClient
 }) => {
   const client = (0, import_QueryClientProvider.useQueryClient)(queryClient);
+  const [hydrationQueue, setHydrationQueue] = React.useState();
   const optionsRef = React.useRef(options);
   optionsRef.current = options;
   React.useMemo(() => {
     if (state) {
-      (0, import_query_core.hydrate)(client, state, optionsRef.current);
+      if (typeof state !== "object") {
+        return;
+      }
+      const queryCache = client.getQueryCache();
+      const queries = state.queries || [];
+      const newQueries = [];
+      const existingQueries = [];
+      for (const dehydratedQuery of queries) {
+        const existingQuery = queryCache.get(dehydratedQuery.queryHash);
+        if (!existingQuery) {
+          newQueries.push(dehydratedQuery);
+        } else {
+          const hydrationIsNewer = dehydratedQuery.state.dataUpdatedAt > existingQuery.state.dataUpdatedAt;
+          const queryAlreadyQueued = hydrationQueue?.find(
+            (query) => query.queryHash === dehydratedQuery.queryHash
+          );
+          if (hydrationIsNewer && (!queryAlreadyQueued || dehydratedQuery.state.dataUpdatedAt > queryAlreadyQueued.state.dataUpdatedAt)) {
+            existingQueries.push(dehydratedQuery);
+          }
+        }
+      }
+      if (newQueries.length > 0) {
+        (0, import_query_core.hydrate)(client, { queries: newQueries }, optionsRef.current);
+      }
+      if (existingQueries.length > 0) {
+        setHydrationQueue(
+          (prev) => prev ? [...prev, ...existingQueries] : existingQueries
+        );
+      }
     }
-  }, [client, state]);
+  }, [client, hydrationQueue, state]);
+  React.useEffect(() => {
+    if (hydrationQueue) {
+      (0, import_query_core.hydrate)(client, { queries: hydrationQueue }, optionsRef.current);
+      setHydrationQueue(void 0);
+    }
+  }, [client, hydrationQueue]);
   return children;
 };
 // Annotate the CommonJS export names for ESM import in node:

package/build/modern/HydrationBoundary.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/HydrationBoundary.tsx"],"sourcesContent":["'use client'\nimport * as React from 'react'\n\nimport { hydrate } from '@tanstack/query-core'\nimport { useQueryClient } from './QueryClientProvider'\nimport type { HydrateOptions, QueryClient } from '@tanstack/query-core'\n\nexport interface HydrationBoundaryProps {\n  state?: unknown\n  options?: HydrateOptions\n  children?: React.ReactNode\n  queryClient?: QueryClient\n}\n\nexport const HydrationBoundary = ({\n  children,\n  options = {},\n  state,\n  queryClient,\n}: HydrationBoundaryProps) => {\n  const client = useQueryClient(queryClient)\n\n  const optionsRef = React.useRef(options)\n  optionsRef.current = options\n\n  // Running hydrate again with the same queries is safe,\n  // it wont overwrite or initialize existing queries,\n  // relying on useMemo here is only a performance optimization.\n  // hydrate can and should be run *during* render here for SSR to work properly\n  React.useMemo(() => {\n    if (state) {\n      hydrate(client, state, optionsRef.current)\n    }\n  }, [client, state])\n\n  return children as React.ReactElement\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AACA,YAAuB;AAEvB,wBAAwB;AACxB,iCAA+B;AAUxB,IAAM,oBAAoB,CAAC;AAAA,EAChC;AAAA,EACA,UAAU,CAAC;AAAA,EACX;AAAA,EACA;AACF,MAA8B;AAC5B,QAAM,aAAS,2CAAe,WAAW;AAEzC,QAAM,aAAmB,aAAO,OAAO;AACvC,aAAW,UAAU;AAMrB,EAAM,cAAQ,MAAM;AAClB,QAAI,OAAO;AACT,qCAAQ,QAAQ,OAAO,WAAW,OAAO;AAAA,IAC3C;AAAA,EACF,GAAG,CAAC,QAAQ,KAAK,CAAC;AAElB,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../../src/HydrationBoundary.tsx"],"sourcesContent":["'use client'\nimport * as React from 'react'\n\nimport { hydrate } from '@tanstack/query-core'\nimport { useQueryClient } from './QueryClientProvider'\nimport type {\n  DehydratedState,\n  HydrateOptions,\n  QueryClient,\n} from '@tanstack/query-core'\n\nexport interface HydrationBoundaryProps {\n  state?: unknown\n  options?: Omit<HydrateOptions, 'defaultOptions'> & {\n    defaultOptions?: Omit<HydrateOptions['defaultOptions'], 'mutations'>\n  }\n  children?: React.ReactNode\n  queryClient?: QueryClient\n}\n\nexport const HydrationBoundary = ({\n  children,\n  options = {},\n  state,\n  queryClient,\n}: HydrationBoundaryProps) => {\n  const client = useQueryClient(queryClient)\n  const [hydrationQueue, setHydrationQueue] = React.useState<\n    DehydratedState['queries'] | undefined\n  >()\n\n  const optionsRef = React.useRef(options)\n  optionsRef.current = options\n\n  // This useMemo is for performance reasons only, everything inside it _must_\n  // be safe to run in every render and code here should be read as \"in render\".\n  //\n  // This code needs to happen during the render phase, because after initial\n  // SSR, hydration needs to happen _before_ children render. Also, if hydrating\n  // during a transition, we want to hydrate as much as is safe in render so\n  // we can prerender as much as possible.\n  //\n  // For any queries that already exist in the cache, we want to hold back on\n  // hydrating until _after_ the render phase. The reason for this is that during\n  // transitions, we don't want the existing queries and observers to update to\n  // the new data on the current page, only _after_ the transition is committed.\n  // If the transition is aborted, we will have hydrated any _new_ queries, but\n  // we throw away the fresh data for any existing ones to avoid unexpectedly\n  // updating the UI.\n  React.useMemo(() => {\n    if (state) {\n      if (typeof state !== 'object') {\n        return\n      }\n\n      const queryCache = client.getQueryCache()\n      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n      const queries = (state as DehydratedState).queries || []\n\n      const newQueries: DehydratedState['queries'] = []\n      const existingQueries: DehydratedState['queries'] = []\n      for (const dehydratedQuery of queries) {\n        const existingQuery = queryCache.get(dehydratedQuery.queryHash)\n\n        if (!existingQuery) {\n          newQueries.push(dehydratedQuery)\n        } else {\n          const hydrationIsNewer =\n            dehydratedQuery.state.dataUpdatedAt >\n            existingQuery.state.dataUpdatedAt\n          const queryAlreadyQueued = hydrationQueue?.find(\n            (query) => query.queryHash === dehydratedQuery.queryHash,\n          )\n\n          if (\n            hydrationIsNewer &&\n            (!queryAlreadyQueued ||\n              dehydratedQuery.state.dataUpdatedAt >\n                queryAlreadyQueued.state.dataUpdatedAt)\n          ) {\n            existingQueries.push(dehydratedQuery)\n          }\n        }\n      }\n\n      if (newQueries.length > 0) {\n        // It's actually fine to call this with queries/state that already exists\n        // in the cache, or is older. hydrate() is idempotent for queries.\n        hydrate(client, { queries: newQueries }, optionsRef.current)\n      }\n      if (existingQueries.length > 0) {\n        setHydrationQueue((prev) =>\n          prev ? [...prev, ...existingQueries] : existingQueries,\n        )\n      }\n    }\n  }, [client, hydrationQueue, state])\n\n  React.useEffect(() => {\n    if (hydrationQueue) {\n      hydrate(client, { queries: hydrationQueue }, optionsRef.current)\n      setHydrationQueue(undefined)\n    }\n  }, [client, hydrationQueue])\n\n  return children as React.ReactElement\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AACA,YAAuB;AAEvB,wBAAwB;AACxB,iCAA+B;AAgBxB,IAAM,oBAAoB,CAAC;AAAA,EAChC;AAAA,EACA,UAAU,CAAC;AAAA,EACX;AAAA,EACA;AACF,MAA8B;AAC5B,QAAM,aAAS,2CAAe,WAAW;AACzC,QAAM,CAAC,gBAAgB,iBAAiB,IAAU,eAEhD;AAEF,QAAM,aAAmB,aAAO,OAAO;AACvC,aAAW,UAAU;AAiBrB,EAAM,cAAQ,MAAM;AAClB,QAAI,OAAO;AACT,UAAI,OAAO,UAAU,UAAU;AAC7B;AAAA,MACF;AAEA,YAAM,aAAa,OAAO,cAAc;AAExC,YAAM,UAAW,MAA0B,WAAW,CAAC;AAEvD,YAAM,aAAyC,CAAC;AAChD,YAAM,kBAA8C,CAAC;AACrD,iBAAW,mBAAmB,SAAS;AACrC,cAAM,gBAAgB,WAAW,IAAI,gBAAgB,SAAS;AAE9D,YAAI,CAAC,eAAe;AAClB,qBAAW,KAAK,eAAe;AAAA,QACjC,OAAO;AACL,gBAAM,mBACJ,gBAAgB,MAAM,gBACtB,cAAc,MAAM;AACtB,gBAAM,qBAAqB,gBAAgB;AAAA,YACzC,CAAC,UAAU,MAAM,cAAc,gBAAgB;AAAA,UACjD;AAEA,cACE,qBACC,CAAC,sBACA,gBAAgB,MAAM,gBACpB,mBAAmB,MAAM,gBAC7B;AACA,4BAAgB,KAAK,eAAe;AAAA,UACtC;AAAA,QACF;AAAA,MACF;AAEA,UAAI,WAAW,SAAS,GAAG;AAGzB,uCAAQ,QAAQ,EAAE,SAAS,WAAW,GAAG,WAAW,OAAO;AAAA,MAC7D;AACA,UAAI,gBAAgB,SAAS,GAAG;AAC9B;AAAA,UAAkB,CAAC,SACjB,OAAO,CAAC,GAAG,MAAM,GAAG,eAAe,IAAI;AAAA,QACzC;AAAA,MACF;AAAA,IACF;AAAA,EACF,GAAG,CAAC,QAAQ,gBAAgB,KAAK,CAAC;AAElC,EAAM,gBAAU,MAAM;AACpB,QAAI,gBAAgB;AAClB,qCAAQ,QAAQ,EAAE,SAAS,eAAe,GAAG,WAAW,OAAO;AAC/D,wBAAkB,MAAS;AAAA,IAC7B;AAAA,EACF,GAAG,CAAC,QAAQ,cAAc,CAAC;AAE3B,SAAO;AACT;","names":[]}

package/build/modern/HydrationBoundary.d.cts

@@ -3,7 +3,9 @@ import { HydrateOptions, QueryClient } from '@tanstack/query-core';
 
 interface HydrationBoundaryProps {
     state?: unknown;
-    options?: HydrateOptions;
+    options?: Omit<HydrateOptions, 'defaultOptions'> & {
+        defaultOptions?: Omit<HydrateOptions['defaultOptions'], 'mutations'>;
+    };
     children?: React.ReactNode;
     queryClient?: QueryClient;
 }

package/build/modern/HydrationBoundary.d.ts

@@ -3,7 +3,9 @@ import { HydrateOptions, QueryClient } from '@tanstack/query-core';
 
 interface HydrationBoundaryProps {
     state?: unknown;
-    options?: HydrateOptions;
+    options?: Omit<HydrateOptions, 'defaultOptions'> & {
+        defaultOptions?: Omit<HydrateOptions['defaultOptions'], 'mutations'>;
+    };
     children?: React.ReactNode;
     queryClient?: QueryClient;
 }

package/build/modern/HydrationBoundary.js

@@ -11,13 +11,48 @@ var HydrationBoundary = ({
   queryClient
 }) => {
   const client = useQueryClient(queryClient);
+  const [hydrationQueue, setHydrationQueue] = React.useState();
   const optionsRef = React.useRef(options);
   optionsRef.current = options;
   React.useMemo(() => {
     if (state) {
-      hydrate(client, state, optionsRef.current);
+      if (typeof state !== "object") {
+        return;
+      }
+      const queryCache = client.getQueryCache();
+      const queries = state.queries || [];
+      const newQueries = [];
+      const existingQueries = [];
+      for (const dehydratedQuery of queries) {
+        const existingQuery = queryCache.get(dehydratedQuery.queryHash);
+        if (!existingQuery) {
+          newQueries.push(dehydratedQuery);
+        } else {
+          const hydrationIsNewer = dehydratedQuery.state.dataUpdatedAt > existingQuery.state.dataUpdatedAt;
+          const queryAlreadyQueued = hydrationQueue?.find(
+            (query) => query.queryHash === dehydratedQuery.queryHash
+          );
+          if (hydrationIsNewer && (!queryAlreadyQueued || dehydratedQuery.state.dataUpdatedAt > queryAlreadyQueued.state.dataUpdatedAt)) {
+            existingQueries.push(dehydratedQuery);
+          }
+        }
+      }
+      if (newQueries.length > 0) {
+        hydrate(client, { queries: newQueries }, optionsRef.current);
+      }
+      if (existingQueries.length > 0) {
+        setHydrationQueue(
+          (prev) => prev ? [...prev, ...existingQueries] : existingQueries
+        );
+      }
     }
-  }, [client, state]);
+  }, [client, hydrationQueue, state]);
+  React.useEffect(() => {
+    if (hydrationQueue) {
+      hydrate(client, { queries: hydrationQueue }, optionsRef.current);
+      setHydrationQueue(void 0);
+    }
+  }, [client, hydrationQueue]);
   return children;
 };
 export {

package/build/modern/HydrationBoundary.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/HydrationBoundary.tsx"],"sourcesContent":["'use client'\nimport * as React from 'react'\n\nimport { hydrate } from '@tanstack/query-core'\nimport { useQueryClient } from './QueryClientProvider'\nimport type { HydrateOptions, QueryClient } from '@tanstack/query-core'\n\nexport interface HydrationBoundaryProps {\n  state?: unknown\n  options?: HydrateOptions\n  children?: React.ReactNode\n  queryClient?: QueryClient\n}\n\nexport const HydrationBoundary = ({\n  children,\n  options = {},\n  state,\n  queryClient,\n}: HydrationBoundaryProps) => {\n  const client = useQueryClient(queryClient)\n\n  const optionsRef = React.useRef(options)\n  optionsRef.current = options\n\n  // Running hydrate again with the same queries is safe,\n  // it wont overwrite or initialize existing queries,\n  // relying on useMemo here is only a performance optimization.\n  // hydrate can and should be run *during* render here for SSR to work properly\n  React.useMemo(() => {\n    if (state) {\n      hydrate(client, state, optionsRef.current)\n    }\n  }, [client, state])\n\n  return children as React.ReactElement\n}\n"],"mappings":";;;AACA,YAAY,WAAW;AAEvB,SAAS,eAAe;AACxB,SAAS,sBAAsB;AAUxB,IAAM,oBAAoB,CAAC;AAAA,EAChC;AAAA,EACA,UAAU,CAAC;AAAA,EACX;AAAA,EACA;AACF,MAA8B;AAC5B,QAAM,SAAS,eAAe,WAAW;AAEzC,QAAM,aAAmB,aAAO,OAAO;AACvC,aAAW,UAAU;AAMrB,EAAM,cAAQ,MAAM;AAClB,QAAI,OAAO;AACT,cAAQ,QAAQ,OAAO,WAAW,OAAO;AAAA,IAC3C;AAAA,EACF,GAAG,CAAC,QAAQ,KAAK,CAAC;AAElB,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../../src/HydrationBoundary.tsx"],"sourcesContent":["'use client'\nimport * as React from 'react'\n\nimport { hydrate } from '@tanstack/query-core'\nimport { useQueryClient } from './QueryClientProvider'\nimport type {\n  DehydratedState,\n  HydrateOptions,\n  QueryClient,\n} from '@tanstack/query-core'\n\nexport interface HydrationBoundaryProps {\n  state?: unknown\n  options?: Omit<HydrateOptions, 'defaultOptions'> & {\n    defaultOptions?: Omit<HydrateOptions['defaultOptions'], 'mutations'>\n  }\n  children?: React.ReactNode\n  queryClient?: QueryClient\n}\n\nexport const HydrationBoundary = ({\n  children,\n  options = {},\n  state,\n  queryClient,\n}: HydrationBoundaryProps) => {\n  const client = useQueryClient(queryClient)\n  const [hydrationQueue, setHydrationQueue] = React.useState<\n    DehydratedState['queries'] | undefined\n  >()\n\n  const optionsRef = React.useRef(options)\n  optionsRef.current = options\n\n  // This useMemo is for performance reasons only, everything inside it _must_\n  // be safe to run in every render and code here should be read as \"in render\".\n  //\n  // This code needs to happen during the render phase, because after initial\n  // SSR, hydration needs to happen _before_ children render. Also, if hydrating\n  // during a transition, we want to hydrate as much as is safe in render so\n  // we can prerender as much as possible.\n  //\n  // For any queries that already exist in the cache, we want to hold back on\n  // hydrating until _after_ the render phase. The reason for this is that during\n  // transitions, we don't want the existing queries and observers to update to\n  // the new data on the current page, only _after_ the transition is committed.\n  // If the transition is aborted, we will have hydrated any _new_ queries, but\n  // we throw away the fresh data for any existing ones to avoid unexpectedly\n  // updating the UI.\n  React.useMemo(() => {\n    if (state) {\n      if (typeof state !== 'object') {\n        return\n      }\n\n      const queryCache = client.getQueryCache()\n      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n      const queries = (state as DehydratedState).queries || []\n\n      const newQueries: DehydratedState['queries'] = []\n      const existingQueries: DehydratedState['queries'] = []\n      for (const dehydratedQuery of queries) {\n        const existingQuery = queryCache.get(dehydratedQuery.queryHash)\n\n        if (!existingQuery) {\n          newQueries.push(dehydratedQuery)\n        } else {\n          const hydrationIsNewer =\n            dehydratedQuery.state.dataUpdatedAt >\n            existingQuery.state.dataUpdatedAt\n          const queryAlreadyQueued = hydrationQueue?.find(\n            (query) => query.queryHash === dehydratedQuery.queryHash,\n          )\n\n          if (\n            hydrationIsNewer &&\n            (!queryAlreadyQueued ||\n              dehydratedQuery.state.dataUpdatedAt >\n                queryAlreadyQueued.state.dataUpdatedAt)\n          ) {\n            existingQueries.push(dehydratedQuery)\n          }\n        }\n      }\n\n      if (newQueries.length > 0) {\n        // It's actually fine to call this with queries/state that already exists\n        // in the cache, or is older. hydrate() is idempotent for queries.\n        hydrate(client, { queries: newQueries }, optionsRef.current)\n      }\n      if (existingQueries.length > 0) {\n        setHydrationQueue((prev) =>\n          prev ? [...prev, ...existingQueries] : existingQueries,\n        )\n      }\n    }\n  }, [client, hydrationQueue, state])\n\n  React.useEffect(() => {\n    if (hydrationQueue) {\n      hydrate(client, { queries: hydrationQueue }, optionsRef.current)\n      setHydrationQueue(undefined)\n    }\n  }, [client, hydrationQueue])\n\n  return children as React.ReactElement\n}\n"],"mappings":";;;AACA,YAAY,WAAW;AAEvB,SAAS,eAAe;AACxB,SAAS,sBAAsB;AAgBxB,IAAM,oBAAoB,CAAC;AAAA,EAChC;AAAA,EACA,UAAU,CAAC;AAAA,EACX;AAAA,EACA;AACF,MAA8B;AAC5B,QAAM,SAAS,eAAe,WAAW;AACzC,QAAM,CAAC,gBAAgB,iBAAiB,IAAU,eAEhD;AAEF,QAAM,aAAmB,aAAO,OAAO;AACvC,aAAW,UAAU;AAiBrB,EAAM,cAAQ,MAAM;AAClB,QAAI,OAAO;AACT,UAAI,OAAO,UAAU,UAAU;AAC7B;AAAA,MACF;AAEA,YAAM,aAAa,OAAO,cAAc;AAExC,YAAM,UAAW,MAA0B,WAAW,CAAC;AAEvD,YAAM,aAAyC,CAAC;AAChD,YAAM,kBAA8C,CAAC;AACrD,iBAAW,mBAAmB,SAAS;AACrC,cAAM,gBAAgB,WAAW,IAAI,gBAAgB,SAAS;AAE9D,YAAI,CAAC,eAAe;AAClB,qBAAW,KAAK,eAAe;AAAA,QACjC,OAAO;AACL,gBAAM,mBACJ,gBAAgB,MAAM,gBACtB,cAAc,MAAM;AACtB,gBAAM,qBAAqB,gBAAgB;AAAA,YACzC,CAAC,UAAU,MAAM,cAAc,gBAAgB;AAAA,UACjD;AAEA,cACE,qBACC,CAAC,sBACA,gBAAgB,MAAM,gBACpB,mBAAmB,MAAM,gBAC7B;AACA,4BAAgB,KAAK,eAAe;AAAA,UACtC;AAAA,QACF;AAAA,MACF;AAEA,UAAI,WAAW,SAAS,GAAG;AAGzB,gBAAQ,QAAQ,EAAE,SAAS,WAAW,GAAG,WAAW,OAAO;AAAA,MAC7D;AACA,UAAI,gBAAgB,SAAS,GAAG;AAC9B;AAAA,UAAkB,CAAC,SACjB,OAAO,CAAC,GAAG,MAAM,GAAG,eAAe,IAAI;AAAA,QACzC;AAAA,MACF;AAAA,IACF;AAAA,EACF,GAAG,CAAC,QAAQ,gBAAgB,KAAK,CAAC;AAElC,EAAM,gBAAU,MAAM;AACpB,QAAI,gBAAgB;AAClB,cAAQ,QAAQ,EAAE,SAAS,eAAe,GAAG,WAAW,OAAO;AAC/D,wBAAkB,MAAS;AAAA,IAC7B;AAAA,EACF,GAAG,CAAC,QAAQ,cAAc,CAAC;AAE3B,SAAO;AACT;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/react-query",
-  "version": "5.0.0-beta.25",
+  "version": "5.0.0-beta.28",
   "description": "Hooks for managing, caching and syncing asynchronous and remote data in React",
   "author": "tannerlinsley",
   "license": "MIT",
@@ -42,7 +42,7 @@
   ],
   "dependencies": {
     "client-only": "0.0.1",
-    "@tanstack/query-core": "5.0.0-beta.23"
+    "@tanstack/query-core": "5.0.0-beta.28"
   },
   "devDependencies": {
     "@types/react": "^18.2.4",

package/src/HydrationBoundary.tsx

@@ -3,11 +3,17 @@ import * as React from 'react'
 
 import { hydrate } from '@tanstack/query-core'
 import { useQueryClient } from './QueryClientProvider'
-import type { HydrateOptions, QueryClient } from '@tanstack/query-core'
+import type {
+  DehydratedState,
+  HydrateOptions,
+  QueryClient,
+} from '@tanstack/query-core'
 
 export interface HydrationBoundaryProps {
   state?: unknown
-  options?: HydrateOptions
+  options?: Omit<HydrateOptions, 'defaultOptions'> & {
+    defaultOptions?: Omit<HydrateOptions['defaultOptions'], 'mutations'>
+  }
   children?: React.ReactNode
   queryClient?: QueryClient
 }
@@ -19,19 +25,83 @@ export const HydrationBoundary = ({
   queryClient,
 }: HydrationBoundaryProps) => {
   const client = useQueryClient(queryClient)
+  const [hydrationQueue, setHydrationQueue] = React.useState<
+    DehydratedState['queries'] | undefined
+  >()
 
   const optionsRef = React.useRef(options)
   optionsRef.current = options
 
-  // Running hydrate again with the same queries is safe,
-  // it wont overwrite or initialize existing queries,
-  // relying on useMemo here is only a performance optimization.
-  // hydrate can and should be run *during* render here for SSR to work properly
+  // This useMemo is for performance reasons only, everything inside it _must_
+  // be safe to run in every render and code here should be read as "in render".
+  //
+  // This code needs to happen during the render phase, because after initial
+  // SSR, hydration needs to happen _before_ children render. Also, if hydrating
+  // during a transition, we want to hydrate as much as is safe in render so
+  // we can prerender as much as possible.
+  //
+  // For any queries that already exist in the cache, we want to hold back on
+  // hydrating until _after_ the render phase. The reason for this is that during
+  // transitions, we don't want the existing queries and observers to update to
+  // the new data on the current page, only _after_ the transition is committed.
+  // If the transition is aborted, we will have hydrated any _new_ queries, but
+  // we throw away the fresh data for any existing ones to avoid unexpectedly
+  // updating the UI.
   React.useMemo(() => {
     if (state) {
-      hydrate(client, state, optionsRef.current)
+      if (typeof state !== 'object') {
+        return
+      }
+
+      const queryCache = client.getQueryCache()
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      const queries = (state as DehydratedState).queries || []
+
+      const newQueries: DehydratedState['queries'] = []
+      const existingQueries: DehydratedState['queries'] = []
+      for (const dehydratedQuery of queries) {
+        const existingQuery = queryCache.get(dehydratedQuery.queryHash)
+
+        if (!existingQuery) {
+          newQueries.push(dehydratedQuery)
+        } else {
+          const hydrationIsNewer =
+            dehydratedQuery.state.dataUpdatedAt >
+            existingQuery.state.dataUpdatedAt
+          const queryAlreadyQueued = hydrationQueue?.find(
+            (query) => query.queryHash === dehydratedQuery.queryHash,
+          )
+
+          if (
+            hydrationIsNewer &&
+            (!queryAlreadyQueued ||
+              dehydratedQuery.state.dataUpdatedAt >
+                queryAlreadyQueued.state.dataUpdatedAt)
+          ) {
+            existingQueries.push(dehydratedQuery)
+          }
+        }
+      }
+
+      if (newQueries.length > 0) {
+        // It's actually fine to call this with queries/state that already exists
+        // in the cache, or is older. hydrate() is idempotent for queries.
+        hydrate(client, { queries: newQueries }, optionsRef.current)
+      }
+      if (existingQueries.length > 0) {
+        setHydrationQueue((prev) =>
+          prev ? [...prev, ...existingQueries] : existingQueries,
+        )
+      }
+    }
+  }, [client, hydrationQueue, state])
+
+  React.useEffect(() => {
+    if (hydrationQueue) {
+      hydrate(client, { queries: hydrationQueue }, optionsRef.current)
+      setHydrationQueue(undefined)
     }
-  }, [client, state])
+  }, [client, hydrationQueue])
 
   return children as React.ReactElement
 }

package/src/__tests__/HydrationBoundary.test.tsx

@@ -137,8 +137,8 @@ describe('React hydration', () => {
         queryFn: () => dataQuery(['should change']),
       })
       await intermediateClient.prefetchQuery({
-        queryKey: ['added string'],
-        queryFn: () => dataQuery(['added string']),
+        queryKey: ['added'],
+        queryFn: () => dataQuery(['added']),
       })
       const dehydrated = dehydrate(intermediateClient)
       intermediateClient.clear()
@@ -147,17 +147,121 @@ describe('React hydration', () => {
         <QueryClientProvider client={queryClient}>
           <HydrationBoundary state={dehydrated}>
             <Page queryKey={['string']} />
-            <Page queryKey={['added string']} />
+            <Page queryKey={['added']} />
           </HydrationBoundary>
         </QueryClientProvider>,
       )
 
-      // Existing query data should be overwritten if older,
-      // so this should have changed
+      // Existing observer should not have updated at this point,
+      // as that would indicate a side effect in the render phase
+      rendered.getByText('string')
+      // New query data should be available immediately
+      rendered.getByText('added')
+
       await sleep(10)
+      // After effects phase has had time to run, the observer should have updated
+      expect(rendered.queryByText('string')).toBeNull()
       rendered.getByText('should change')
-      // New query data should be available immediately
-      rendered.getByText('added string')
+
+      queryClient.clear()
+    })
+
+    // When we hydrate in transitions that are later aborted, it could be
+    // confusing to both developers and users if we suddenly updated existing
+    // state on the screen (why did this update when it was not stale, nothing
+    // remounted, I didn't change tabs etc?).
+    // Any queries that does not exist in the cache yet can still be hydrated
+    // since they don't have any observers on the current page that would update.
+    test('should hydrate new but not existing queries if transition is aborted', async () => {
+      const initialDehydratedState = JSON.parse(stringifiedState)
+      const queryCache = new QueryCache()
+      const queryClient = createQueryClient({ queryCache })
+
+      function Page({ queryKey }: { queryKey: [string] }) {
+        const { data } = useQuery({
+          queryKey,
+          queryFn: () => dataQuery(queryKey),
+        })
+        return (
+          <div>
+            <h1>{data}</h1>
+          </div>
+        )
+      }
+
+      const rendered = render(
+        <QueryClientProvider client={queryClient}>
+          <HydrationBoundary state={initialDehydratedState}>
+            <Page queryKey={['string']} />
+          </HydrationBoundary>
+        </QueryClientProvider>,
+      )
+
+      await rendered.findByText('string')
+
+      const intermediateCache = new QueryCache()
+      const intermediateClient = createQueryClient({
+        queryCache: intermediateCache,
+      })
+      await intermediateClient.prefetchQuery({
+        queryKey: ['string'],
+        queryFn: () => dataQuery(['should not change']),
+      })
+      await intermediateClient.prefetchQuery({
+        queryKey: ['added'],
+        queryFn: () => dataQuery(['added']),
+      })
+      const newDehydratedState = dehydrate(intermediateClient)
+      intermediateClient.clear()
+
+      function Thrower() {
+        throw new Promise(() => {
+          // Never resolve
+        })
+
+        // @ts-ignore
+        return null
+      }
+
+      React.startTransition(() => {
+        rendered.rerender(
+          <React.Suspense fallback="loading">
+            <QueryClientProvider client={queryClient}>
+              <HydrationBoundary state={newDehydratedState}>
+                <Page queryKey={['string']} />
+                <Page queryKey={['added']} />
+                <Thrower />
+              </HydrationBoundary>
+            </QueryClientProvider>
+          </React.Suspense>,
+        )
+
+        rendered.getByText('loading')
+      })
+
+      React.startTransition(() => {
+        rendered.rerender(
+          <QueryClientProvider client={queryClient}>
+            <HydrationBoundary state={initialDehydratedState}>
+              <Page queryKey={['string']} />
+              <Page queryKey={['added']} />
+            </HydrationBoundary>
+          </QueryClientProvider>,
+        )
+
+        // This query existed before the transition so it should stay the same
+        rendered.getByText('string')
+        expect(rendered.queryByText('should not change')).toBeNull()
+        // New query data should be available immediately because it was
+        // hydrated in the previous transition, even though the new dehydrated
+        // state did not contain it
+        rendered.getByText('added')
+      })
+
+      await sleep(10)
+      // It should stay the same even after effects have had a chance to run
+      rendered.getByText('string')
+      expect(rendered.queryByText('should not change')).toBeNull()
 
       queryClient.clear()
     })

package/src/__tests__/fine-grained-persister.test.tsx

@@ -0,0 +1,163 @@
+import { waitFor } from '@testing-library/react'
+import '@testing-library/jest-dom'
+import * as React from 'react'
+import { QueryCache, hashKey } from '@tanstack/query-core'
+import { vi } from 'vitest'
+import { useQuery } from '..'
+import {
+  PERSISTER_KEY_PREFIX,
+  experimental_createPersister,
+} from '../../../query-persist-client-core/src'
+import { createQueryClient, queryKey, renderWithClient, sleep } from './utils'
+
+describe('fine grained persister', () => {
+  const queryCache = new QueryCache()
+  const queryClient = createQueryClient({ queryCache })
+
+  it('should restore query state from persister and not refetch', async () => {
+    const key = queryKey()
+    const hash = hashKey(key)
+    const spy = vi.fn(() => Promise.resolve('Works from queryFn'))
+
+    const mapStorage = new Map()
+    const storage = {
+      getItem: (itemKey: string) => Promise.resolve(mapStorage.get(itemKey)),
+      setItem: async (itemKey: string, value: unknown) => {
+        mapStorage.set(itemKey, value)
+      },
+      removeItem: async (itemKey: string) => {
+        mapStorage.delete(itemKey)
+      },
+    }
+
+    await storage.setItem(
+      `${PERSISTER_KEY_PREFIX}-${hash}`,
+      JSON.stringify({
+        buster: '',
+        queryHash: hash,
+        queryKey: key,
+        state: {
+          dataUpdatedAt: Date.now(),
+          data: 'Works from persister',
+        },
+      }),
+    )
+
+    function Test() {
+      const [_, setRef] = React.useState<HTMLDivElement | null>()
+
+      const { data } = useQuery({
+        queryKey: key,
+        queryFn: spy,
+        persister: experimental_createPersister({
+          storage,
+        }),
+        staleTime: 5000,
+      })
+
+      return <div ref={(value) => setRef(value)}>{data}</div>
+    }
+
+    const rendered = renderWithClient(queryClient, <Test />)
+
+    await waitFor(() => rendered.getByText('Works from persister'))
+    expect(spy).not.toHaveBeenCalled()
+  })
+
+  it('should restore query state from persister and refetch', async () => {
+    const key = queryKey()
+    const hash = hashKey(key)
+    const spy = vi.fn(async () => {
+      await sleep(5)
+
+      return 'Works from queryFn'
+    })
+
+    const mapStorage = new Map()
+    const storage = {
+      getItem: (itemKey: string) => Promise.resolve(mapStorage.get(itemKey)),
+      setItem: async (itemKey: string, value: unknown) => {
+        mapStorage.set(itemKey, value)
+      },
+      removeItem: async (itemKey: string) => {
+        mapStorage.delete(itemKey)
+      },
+    }
+
+    await storage.setItem(
+      `${PERSISTER_KEY_PREFIX}-${hash}`,
+      JSON.stringify({
+        buster: '',
+        queryHash: hash,
+        queryKey: key,
+        state: {
+          dataUpdatedAt: Date.now(),
+          data: 'Works from persister',
+        },
+      }),
+    )
+
+    function Test() {
+      const [_, setRef] = React.useState<HTMLDivElement | null>()
+
+      const { data } = useQuery({
+        queryKey: key,
+        queryFn: spy,
+        persister: experimental_createPersister({
+          storage,
+        }),
+      })
+
+      return <div ref={(value) => setRef(value)}>{data}</div>
+    }
+
+    const rendered = renderWithClient(queryClient, <Test />)
+
+    await waitFor(() => rendered.getByText('Works from persister'))
+    await waitFor(() => rendered.getByText('Works from queryFn'))
+    expect(spy).toHaveBeenCalledTimes(1)
+  })
+
+  it('should store query state to persister after fetch', async () => {
+    const key = queryKey()
+    const hash = hashKey(key)
+    const spy = vi.fn(() => Promise.resolve('Works from queryFn'))
+
+    const mapStorage = new Map()
+    const storage = {
+      getItem: (itemKey: string) => Promise.resolve(mapStorage.get(itemKey)),
+      setItem: async (itemKey: string, value: unknown) => {
+        mapStorage.set(itemKey, value)
+      },
+      removeItem: async (itemKey: string) => {
+        mapStorage.delete(itemKey)
+      },
+    }
+
+    function Test() {
+      const [_, setRef] = React.useState<HTMLDivElement | null>()
+
+      const { data } = useQuery({
+        queryKey: key,
+        queryFn: spy,
+        persister: experimental_createPersister({
+          storage,
+        }),
+      })
+
+      return <div ref={(value) => setRef(value)}>{data}</div>
+    }
+
+    const rendered = renderWithClient(queryClient, <Test />)
+
+    await waitFor(() => rendered.getByText('Works from queryFn'))
+    expect(spy).toHaveBeenCalledTimes(1)
+
+    const storedItem = await storage.getItem(`${PERSISTER_KEY_PREFIX}-${hash}`)
+    expect(JSON.parse(storedItem)).toMatchObject({
+      state: {
+        data: 'Works from queryFn',
+      },
+    })
+  })
+})