@suspensive/react-query-4 3.15.1 → 3.17.0

package/dist/{useSuspenseQuery-BvMsQ1Ho.mjs.map → useSuspenseQuery-CVWQeHhd.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"useSuspenseQuery-BvMsQ1Ho.mjs","names":["useSuspenseQuery","original_useSuspenseQuery"],"sources":["../src/useSuspenseQuery.ts"],"sourcesContent":["'use client'\n\nimport {\n  type UseSuspenseQueryOptions as original_UseSuspenseQueryOptions,\n  type UseSuspenseQueryResult as original_UseSuspenseQueryResult,\n  useSuspenseQuery as original_useSuspenseQuery,\n} from '@tanstack/react-query'\n\n/**\n * This feature is officially supported in \\@tanstack/react-query@^4.40.0, You can proceed with the migration.\n * @deprecated Use `UseSuspenseQueryOptions` from \\@tanstack/react-query@^4.40.0\n * @example\n * ```diff\n * - import type { UseSuspenseQueryOptions } from '@suspensive/react-query'\n * + import type { UseSuspenseQueryOptions } from '@tanstack/react-query'\n * ```\n */\nexport type UseSuspenseQueryOptions = original_UseSuspenseQueryOptions\n\n/**\n * This feature is officially supported in \\@tanstack/react-query@^4.40.0, You can proceed with the migration.\n * @deprecated Use `UseSuspenseQueryResult` from \\@tanstack/react-query@^4.40.0\n * @example\n * ```diff\n * - import type { UseSuspenseQueryResult } from '@suspensive/react-query'\n * + import type { UseSuspenseQueryResult } from '@tanstack/react-query'\n * ```\n */\nexport type UseSuspenseQueryResult = original_UseSuspenseQueryResult\n\n/**\n * This feature is officially supported in \\@tanstack/react-query@^4.40.0, You can proceed with the migration.\n * @deprecated Use `useSuspenseQuery` from \\@tanstack/react-query@^4.40.0\n * @example\n * ```diff\n * - import { useSuspenseQuery } from '@suspensive/react-query'\n * + import { useSuspenseQuery } from '@tanstack/react-query'\n * ```\n */\nexport const useSuspenseQuery = original_useSuspenseQuery\n"],"mappings":";;;;;;;;;;;;AAuCA,MAAaA,qBAAmBC"}
+{"version":3,"file":"useSuspenseQuery-CVWQeHhd.mjs","names":["useSuspenseQuery","original_useSuspenseQuery"],"sources":["../src/useSuspenseQuery.ts"],"sourcesContent":["'use client'\n\nimport {\n  type UseSuspenseQueryOptions as original_UseSuspenseQueryOptions,\n  type UseSuspenseQueryResult as original_UseSuspenseQueryResult,\n  useSuspenseQuery as original_useSuspenseQuery,\n} from '@tanstack/react-query'\n\n/**\n * This feature is officially supported in \\@tanstack/react-query@^4.40.0, You can proceed with the migration.\n * @deprecated Use `UseSuspenseQueryOptions` from \\@tanstack/react-query@^4.40.0\n * @example\n * ```diff\n * - import type { UseSuspenseQueryOptions } from '@suspensive/react-query'\n * + import type { UseSuspenseQueryOptions } from '@tanstack/react-query'\n * ```\n */\nexport type UseSuspenseQueryOptions = original_UseSuspenseQueryOptions\n\n/**\n * This feature is officially supported in \\@tanstack/react-query@^4.40.0, You can proceed with the migration.\n * @deprecated Use `UseSuspenseQueryResult` from \\@tanstack/react-query@^4.40.0\n * @example\n * ```diff\n * - import type { UseSuspenseQueryResult } from '@suspensive/react-query'\n * + import type { UseSuspenseQueryResult } from '@tanstack/react-query'\n * ```\n */\nexport type UseSuspenseQueryResult = original_UseSuspenseQueryResult\n\n/**\n * This feature is officially supported in \\@tanstack/react-query@^4.40.0, You can proceed with the migration.\n * @deprecated Use `useSuspenseQuery` from \\@tanstack/react-query@^4.40.0\n * @example\n * ```diff\n * - import { useSuspenseQuery } from '@suspensive/react-query'\n * + import { useSuspenseQuery } from '@tanstack/react-query'\n * ```\n */\nexport const useSuspenseQuery = original_useSuspenseQuery\n"],"mappings":";;;;;;;;;;;;AAuCA,MAAaA,qBAAmBC"}

package/dist/{useSuspenseQuery-07kIGch-.d.cts → useSuspenseQuery-DG0Jz1Da.d.mts}

@@ -34,4 +34,4 @@ type UseSuspenseQueryResult$1 = UseSuspenseQueryResult;
 declare const useSuspenseQuery$1: typeof useSuspenseQuery;
 //#endregion
 export { UseSuspenseQueryResult$1 as n, useSuspenseQuery$1 as r, UseSuspenseQueryOptions$1 as t };
-//# sourceMappingURL=useSuspenseQuery-07kIGch-.d.cts.map
+//# sourceMappingURL=useSuspenseQuery-DG0Jz1Da.d.mts.map

package/dist/{useSuspenseQuery-07kIGch-.d.cts.map → useSuspenseQuery-DG0Jz1Da.d.mts.map}

@@ -1 +1 @@
-{"version":3,"file":"useSuspenseQuery-07kIGch-.d.cts","names":[],"sources":["../src/useSuspenseQuery.ts"],"sourcesContent":[],"mappings":";;;;;;AAiBA;AAWA;AAWA;;;;;KAtBY,yBAAA,GAA0B;;;;;;;;;;KAW1B,wBAAA,GAAyB;;;;;;;;;;cAWxB,2BAAgB"}
+{"version":3,"file":"useSuspenseQuery-DG0Jz1Da.d.mts","names":[],"sources":["../src/useSuspenseQuery.ts"],"sourcesContent":[],"mappings":";;;;;;AAiBA;AAWA;AAWA;;;;;KAtBY,yBAAA,GAA0B;;;;;;;;;;KAW1B,wBAAA,GAAyB;;;;;;;;;;cAWxB,2BAAgB"}

package/dist/{useSuspenseQuery-CMEH7kZ8.d.mts → useSuspenseQuery-DiNomNWA.d.cts}

@@ -34,4 +34,4 @@ type UseSuspenseQueryResult$1 = UseSuspenseQueryResult;
 declare const useSuspenseQuery$1: typeof useSuspenseQuery;
 //#endregion
 export { UseSuspenseQueryResult$1 as n, useSuspenseQuery$1 as r, UseSuspenseQueryOptions$1 as t };
-//# sourceMappingURL=useSuspenseQuery-CMEH7kZ8.d.mts.map
+//# sourceMappingURL=useSuspenseQuery-DiNomNWA.d.cts.map

package/dist/{useSuspenseQuery-CMEH7kZ8.d.mts.map → useSuspenseQuery-DiNomNWA.d.cts.map}

@@ -1 +1 @@
-{"version":3,"file":"useSuspenseQuery-CMEH7kZ8.d.mts","names":[],"sources":["../src/useSuspenseQuery.ts"],"sourcesContent":[],"mappings":";;;;;;AAiBA;AAWA;AAWA;;;;;KAtBY,yBAAA,GAA0B;;;;;;;;;;KAW1B,wBAAA,GAAyB;;;;;;;;;;cAWxB,2BAAgB"}
+{"version":3,"file":"useSuspenseQuery-DiNomNWA.d.cts","names":[],"sources":["../src/useSuspenseQuery.ts"],"sourcesContent":[],"mappings":";;;;;;AAiBA;AAWA;AAWA;;;;;KAtBY,yBAAA,GAA0B;;;;;;;;;;KAW1B,wBAAA,GAAyB;;;;;;;;;;cAWxB,2BAAgB"}

package/dist/useSuspenseQuery.cjs

@@ -1,6 +1,6 @@
 'use client';
 
 
-const require_useSuspenseQuery = require('./useSuspenseQuery-B7HJXyZL.cjs');
+const require_useSuspenseQuery = require('./useSuspenseQuery-41ONxa6i.cjs');
 
 exports.useSuspenseQuery = require_useSuspenseQuery.useSuspenseQuery;

package/dist/useSuspenseQuery.d.cts

@@ -1,2 +1,2 @@
-import { n as UseSuspenseQueryResult, r as useSuspenseQuery, t as UseSuspenseQueryOptions } from "./useSuspenseQuery-07kIGch-.cjs";
+import { n as UseSuspenseQueryResult, r as useSuspenseQuery, t as UseSuspenseQueryOptions } from "./useSuspenseQuery-DiNomNWA.cjs";
 export { UseSuspenseQueryOptions, UseSuspenseQueryResult, useSuspenseQuery };

package/dist/useSuspenseQuery.d.mts

@@ -1,2 +1,2 @@
-import { n as UseSuspenseQueryResult, r as useSuspenseQuery, t as UseSuspenseQueryOptions } from "./useSuspenseQuery-CMEH7kZ8.mjs";
+import { n as UseSuspenseQueryResult, r as useSuspenseQuery, t as UseSuspenseQueryOptions } from "./useSuspenseQuery-DG0Jz1Da.mjs";
 export { UseSuspenseQueryOptions, UseSuspenseQueryResult, useSuspenseQuery };

package/dist/useSuspenseQuery.mjs

@@ -1,6 +1,6 @@
 'use client';
 
 
-import { t as useSuspenseQuery } from "./useSuspenseQuery-BvMsQ1Ho.mjs";
+import { t as useSuspenseQuery } from "./useSuspenseQuery-CVWQeHhd.mjs";
 
 export { useSuspenseQuery };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suspensive/react-query-4",
-  "version": "3.15.1",
+  "version": "3.17.0",
   "description": "Suspensive interfaces for @tanstack/react-query@4",
   "keywords": [
     "suspensive",
@@ -40,8 +40,8 @@
   ],
   "devDependencies": {
     "@tanstack/react-query": "4.42.0",
-    "@types/react": "^19.1.6",
-    "react": "^19.1.0",
+    "@types/react": "^19.2.5",
+    "react": "^19.2.0",
     "@suspensive/eslint-config": "0.0.1",
     "@suspensive/tsconfig": "0.0.0-development",
     "@suspensive/tsdown": "0.0.0"

package/src/QueriesHydration.spec.tsx

@@ -0,0 +1,257 @@
+import { QueryClient, dehydrate } from '@tanstack/react-query'
+import { render, screen } from '@testing-library/react'
+import type { ComponentProps, ReactNode } from 'react'
+import { describe, expect, it, vi } from 'vitest'
+import { QueriesHydration } from './QueriesHydration'
+
+// Mock the ClientOnly component
+vi.mock('./components/ClientOnly', () => ({
+  ClientOnly: ({ children, fallback }: { children: ReactNode; fallback?: ReactNode }) => (
+    <div data-testid="client-only">{fallback || children}</div>
+  ),
+}))
+
+describe('<QueriesHydration/>', () => {
+  it('should fetch queries and hydrate them successfully', async () => {
+    const queryClient = new QueryClient()
+    const mockQueryFn = vi.fn().mockResolvedValue({ data: 'test-data' })
+
+    const queries = [
+      {
+        queryKey: ['test-query'],
+        queryFn: mockQueryFn,
+      },
+    ]
+
+    const result = await QueriesHydration({
+      queries,
+      queryClient,
+      children: <div>Test Children</div>,
+    })
+
+    expect(mockQueryFn).toHaveBeenCalledTimes(1)
+    expect(result).toBeDefined()
+    expect(result.type).toBeDefined()
+  })
+
+  it('should handle multiple queries', async () => {
+    const queryClient = new QueryClient()
+    const mockQueryFn1 = vi.fn().mockResolvedValue({ data: 'data-1' })
+    const mockQueryFn2 = vi.fn().mockResolvedValue({ data: 'data-2' })
+
+    const queries = [
+      {
+        queryKey: ['query-1'],
+        queryFn: mockQueryFn1,
+      },
+      {
+        queryKey: ['query-2'],
+        queryFn: mockQueryFn2,
+      },
+    ]
+
+    const result = await QueriesHydration({
+      queries,
+      queryClient,
+      children: <div>Test Children</div>,
+    })
+
+    expect(mockQueryFn1).toHaveBeenCalledTimes(1)
+    expect(mockQueryFn2).toHaveBeenCalledTimes(1)
+    expect(result).toBeDefined()
+  })
+
+  it('should skip SSR and render ClientOnly when query fails and skipSsrOnError is true (default)', async () => {
+    const queryClient = new QueryClient()
+    const mockQueryFn = vi.fn().mockRejectedValue(new Error('Query failed'))
+
+    const queries = [
+      {
+        queryKey: ['failing-query'],
+        queryFn: mockQueryFn,
+      },
+    ]
+
+    const result = await QueriesHydration({
+      queries,
+      queryClient,
+      children: <div>Test Children</div>,
+    })
+
+    expect(mockQueryFn).toHaveBeenCalledTimes(1)
+
+    // Render the result to verify it's ClientOnly
+    render(result as React.ReactElement)
+    expect(screen.getByTestId('client-only')).toBeInTheDocument()
+  })
+
+  it('should skip SSR and render ClientOnly when query fails and skipSsrOnError is explicitly true', async () => {
+    const queryClient = new QueryClient()
+    const mockQueryFn = vi.fn().mockRejectedValue(new Error('Query failed'))
+
+    const queries = [
+      {
+        queryKey: ['failing-query'],
+        queryFn: mockQueryFn,
+      },
+    ]
+
+    const result = await QueriesHydration({
+      queries,
+      queryClient,
+      skipSsrOnError: true,
+      children: <div>Test Children</div>,
+    })
+
+    expect(mockQueryFn).toHaveBeenCalledTimes(1)
+
+    render(result as React.ReactElement)
+    expect(screen.getByTestId('client-only')).toBeInTheDocument()
+  })
+
+  it('should show custom fallback when query fails and skipSsrOnError has fallback', async () => {
+    const queryClient = new QueryClient()
+    const mockQueryFn = vi.fn().mockRejectedValue(new Error('Query failed'))
+
+    const queries = [
+      {
+        queryKey: ['failing-query'],
+        queryFn: mockQueryFn,
+      },
+    ]
+
+    const customFallback = <div>Custom Fallback</div>
+
+    const result = await QueriesHydration({
+      queries,
+      queryClient,
+      skipSsrOnError: { fallback: customFallback },
+      children: <div>Test Children</div>,
+    })
+
+    expect(mockQueryFn).toHaveBeenCalledTimes(1)
+
+    render(result as React.ReactElement)
+    expect(screen.getByTestId('client-only')).toBeInTheDocument()
+  })
+
+  it('should proceed with SSR without hydration when query fails and skipSsrOnError is false', async () => {
+    const queryClient = new QueryClient()
+    const mockQueryFn = vi.fn().mockRejectedValue(new Error('Query failed'))
+
+    const queries = [
+      {
+        queryKey: ['failing-query'],
+        queryFn: mockQueryFn,
+      },
+    ]
+
+    const result = await QueriesHydration({
+      queries,
+      queryClient,
+      skipSsrOnError: false,
+      children: <div>Test Children</div>,
+    })
+
+    expect(mockQueryFn).toHaveBeenCalledTimes(1)
+
+    // When skipSsrOnError is false, it should still render Hydrate component
+    // even though the query failed
+    expect(result).toBeDefined()
+    expect(result.type).toBeDefined()
+  })
+
+  it('should handle partial query failures when skipSsrOnError is false', async () => {
+    const queryClient = new QueryClient()
+    const mockSuccessQueryFn = vi.fn().mockResolvedValue({ data: 'success' })
+    const mockFailQueryFn = vi.fn().mockRejectedValue(new Error('Query failed'))
+
+    const queries = [
+      {
+        queryKey: ['success-query'],
+        queryFn: mockSuccessQueryFn,
+      },
+      {
+        queryKey: ['fail-query'],
+        queryFn: mockFailQueryFn,
+      },
+    ]
+
+    const result = await QueriesHydration({
+      queries,
+      queryClient,
+      skipSsrOnError: false,
+      children: <div>Test Children</div>,
+    })
+
+    // Promise.all rejects if any promise rejects
+    expect(mockSuccessQueryFn).toHaveBeenCalledTimes(1)
+    expect(mockFailQueryFn).toHaveBeenCalledTimes(1)
+    expect(result).toBeDefined()
+  })
+
+  it('should use default QueryClient when queryClient prop is not provided', async () => {
+    const mockQueryFn = vi.fn().mockResolvedValue({ data: 'test-data' })
+
+    const queries = [
+      {
+        queryKey: ['test-query'],
+        queryFn: mockQueryFn,
+      },
+    ]
+
+    const result = await QueriesHydration({
+      queries,
+      children: <div>Test Children</div>,
+    })
+
+    expect(mockQueryFn).toHaveBeenCalledTimes(1)
+    expect(result).toBeDefined()
+  })
+
+  it('should pass additional Hydrate props through', async () => {
+    const queryClient = new QueryClient()
+    const mockQueryFn = vi.fn().mockResolvedValue({ data: 'test-data' })
+
+    const queries = [
+      {
+        queryKey: ['test-query'],
+        queryFn: mockQueryFn,
+      },
+    ]
+
+    const result = await QueriesHydration({
+      queries,
+      queryClient,
+      children: <div>Test Children</div>,
+      // Additional props that should be passed to Hydrate
+    } as ComponentProps<typeof QueriesHydration>)
+
+    expect(mockQueryFn).toHaveBeenCalledTimes(1)
+    expect(result).toBeDefined()
+  })
+
+  it('should dehydrate query state correctly', async () => {
+    const queryClient = new QueryClient()
+    const mockData = { data: 'test-data' }
+    const mockQueryFn = vi.fn().mockResolvedValue(mockData)
+
+    const queries = [
+      {
+        queryKey: ['test-query'],
+        queryFn: mockQueryFn,
+      },
+    ]
+
+    await QueriesHydration({
+      queries,
+      queryClient,
+      children: <div>Test Children</div>,
+    })
+
+    const dehydratedState = dehydrate(queryClient)
+    expect(dehydratedState.queries).toHaveLength(1)
+    expect(dehydratedState.queries[0].queryKey).toEqual(['test-query'])
+    expect(dehydratedState.queries[0].state.data).toEqual(mockData)
+  })
+})

package/src/QueriesHydration.test-d.tsx

@@ -0,0 +1,76 @@
+import { QueryClient, queryOptions } from '@tanstack/react-query'
+import { describe, expectTypeOf, it } from 'vitest'
+import { QueriesHydration } from './QueriesHydration'
+import { queryFn, queryKey } from './test-utils'
+
+describe('<QueriesHydration/>', () => {
+  it('type check', () => {
+    const options1 = queryOptions({
+      queryKey: ['query1'],
+      queryFn: queryFn,
+    })
+    const options2 = queryOptions({
+      queryKey: ['query2'],
+      queryFn: queryFn,
+    })
+
+    // Should accept queries array with queryKey
+    void (async () =>
+      await QueriesHydration({
+        queries: [
+          {
+            queryKey: queryKey,
+            queryFn: queryFn,
+          },
+        ],
+        children: <></>,
+      }))()
+
+    // Should accept multiple queries
+    void (async () =>
+      await QueriesHydration({
+        queries: [options1, options2],
+        children: <></>,
+      }))()
+
+    // Should accept skipSsrOnError as boolean
+    void (async () =>
+      await QueriesHydration({
+        queries: [options1],
+        skipSsrOnError: true,
+        children: <></>,
+      }))()
+
+    // Should accept skipSsrOnError with fallback
+    void (async () =>
+      await QueriesHydration({
+        queries: [options1],
+        skipSsrOnError: { fallback: <div>Loading...</div> },
+        children: <></>,
+      }))()
+
+    // Should accept undefined queryClient prop
+    void (async () =>
+      await QueriesHydration({
+        queries: [options1],
+        queryClient: undefined,
+        children: <></>,
+      }))()
+
+    // Should accept QueryClient instance for queryClient prop
+    void (async () =>
+      await QueriesHydration({
+        queries: [options1],
+        queryClient: new QueryClient(),
+        children: <></>,
+      }))()
+
+    // Return type should be JSX.Element (Promise<JSX.Element>)
+    expectTypeOf(
+      QueriesHydration({
+        queries: [options1],
+        children: <></>,
+      })
+    ).toEqualTypeOf<Promise<React.JSX.Element>>()
+  })
+})

package/src/createGetQueryClient.spec.tsx

@@ -0,0 +1,118 @@
+import { QueryClient } from '@tanstack/react-query'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+// Mock isServer from @tanstack/react-query
+vi.mock('@tanstack/react-query', async () => {
+  const actual = await vi.importActual('@tanstack/react-query')
+  return {
+    ...actual,
+    isServer: false,
+  }
+})
+
+describe('getQueryClient', () => {
+  beforeEach(() => {
+    // Reset modules to clear the browserQueryClient singleton
+    vi.resetModules()
+  })
+
+  it('should return a QueryClient instance', async () => {
+    const { createGetQueryClient } = await import('./createGetQueryClient')
+    const { getQueryClient } = createGetQueryClient()
+    const queryClient = getQueryClient()
+    expect(queryClient).toBeInstanceOf(QueryClient)
+  })
+
+  it('should return the same QueryClient instance on multiple calls in browser environment', async () => {
+    const { createGetQueryClient } = await import('./createGetQueryClient')
+    const { getQueryClient } = createGetQueryClient()
+    const queryClient1 = getQueryClient()
+    const queryClient2 = getQueryClient()
+    expect(queryClient1).toBe(queryClient2)
+  })
+
+  it('should apply config when creating initial QueryClient', async () => {
+    const { createGetQueryClient } = await import('./createGetQueryClient')
+    const { getQueryClient } = createGetQueryClient({
+      defaultOptions: {
+        queries: {
+          staleTime: 5000,
+          retry: 3,
+        },
+      },
+    })
+    const queryClient = getQueryClient()
+    expect(queryClient).toBeInstanceOf(QueryClient)
+    expect(queryClient.getDefaultOptions().queries?.staleTime).toBe(5000)
+    expect(queryClient.getDefaultOptions().queries?.retry).toBe(3)
+  })
+
+  it('should use provided cacheTime value in browser environment (not Infinity)', async () => {
+    const { createGetQueryClient } = await import('./createGetQueryClient')
+    const { getQueryClient } = createGetQueryClient({
+      defaultOptions: {
+        queries: {
+          cacheTime: 5000,
+        },
+      },
+    })
+    const queryClient = getQueryClient()
+    // In browser, cacheTime should use the provided value, not Infinity
+    expect(queryClient.getDefaultOptions().queries?.cacheTime).toBe(5000)
+    expect(queryClient.getDefaultOptions().queries?.cacheTime).not.toBe(Infinity)
+  })
+
+  it('should not set cacheTime to Infinity in browser environment when no config provided', async () => {
+    const { createGetQueryClient } = await import('./createGetQueryClient')
+    const { getQueryClient } = createGetQueryClient()
+    const queryClient = getQueryClient()
+    // In browser, cacheTime should use default value (not Infinity)
+    // Default cacheTime in React Query v4 is 5 minutes (300000ms)
+    expect(queryClient.getDefaultOptions().queries?.cacheTime).not.toBe(Infinity)
+  })
+})
+
+describe('getQueryClient (server environment)', () => {
+  beforeEach(() => {
+    vi.resetModules()
+    // Mock isServer as true for server tests
+    vi.doMock('@tanstack/react-query', async () => {
+      const actual = await vi.importActual('@tanstack/react-query')
+      return {
+        ...actual,
+        isServer: true,
+      }
+    })
+  })
+
+  it('should return new QueryClient instance on each call in server environment', async () => {
+    const { createGetQueryClient } = await import('./createGetQueryClient')
+    const { getQueryClient } = createGetQueryClient()
+    const queryClient1 = getQueryClient()
+    const queryClient2 = getQueryClient()
+    expect(queryClient1).toBeInstanceOf(QueryClient)
+    expect(queryClient2).toBeInstanceOf(QueryClient)
+    expect(queryClient1).not.toBe(queryClient2)
+  })
+
+  it('should set cacheTime to Infinity in server environment to prevent OOM', async () => {
+    const { createGetQueryClient } = await import('./createGetQueryClient')
+    const { getQueryClient } = createGetQueryClient()
+    const queryClient = getQueryClient()
+    expect(queryClient.getDefaultOptions().queries?.cacheTime).toBe(Infinity)
+  })
+
+  it('should override cacheTime to Infinity even if config provides different value in server environment', async () => {
+    const { createGetQueryClient } = await import('./createGetQueryClient')
+    const { getQueryClient } = createGetQueryClient({
+      defaultOptions: {
+        queries: {
+          cacheTime: 5000,
+        },
+      },
+    })
+    const queryClient = getQueryClient()
+    // cacheTime should be Infinity regardless of config to prevent OOM on server
+    expect(queryClient.getDefaultOptions().queries?.cacheTime).toBe(Infinity)
+  })
+})

package/src/createGetQueryClient.test-d.tsx

@@ -0,0 +1,14 @@
+import type { QueryClient } from '@tanstack/react-query'
+import { createGetQueryClient } from './createGetQueryClient'
+
+describe('getQueryClient', () => {
+  it('type check', () => {
+    const { getQueryClient } = createGetQueryClient({ defaultOptions: { queries: { staleTime: 5000 } } })
+
+    const queryClient = getQueryClient()
+    expectTypeOf(queryClient).toEqualTypeOf<QueryClient>()
+
+    const queryClientWithConfig = getQueryClient()
+    expectTypeOf(queryClientWithConfig).toEqualTypeOf<QueryClient>()
+  })
+})

package/src/createGetQueryClient.ts

@@ -0,0 +1,78 @@
+import { QueryClient, type QueryClientConfig, isServer } from '@tanstack/react-query'
+
+/**
+ * Creates a function that returns a QueryClient instance, with different behavior for server and client environments.
+ *
+ * On the server, it always creates a new QueryClient instance with `cacheTime: Infinity` to prevent data from being garbage collected.
+ * On the client, it reuses the same QueryClient instance to avoid recreating it during React's initial render suspension.
+ *
+ * @experimental This component is experimental and may be changed or removed in the future.
+ *
+ * @param config - Optional QueryClient configuration. On the server, `cacheTime` will be automatically set to `Infinity`.
+ * @returns An object containing a `getQueryClient` function that returns a QueryClient instance.
+ *
+ * @example
+ * ```tsx
+ * // Create a get-query-client.ts file in your project:
+ * // get-query-client.ts
+ * import { createGetQueryClient } from '@suspensive/react-query'
+ *
+ * export const { getQueryClient } = createGetQueryClient()
+ *
+ * @example
+ * ```tsx
+ * // Then import and use it in your code:
+ * // app/providers.tsx
+ * 'use client'
+ *
+ * import { QueryClientProvider } from '@tanstack/react-query'
+ * import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
+ * import { getQueryClient } from '@/app/get-query-client'
+ * import type * as React from 'react'
+ *
+ * export default function Providers({ children }: { children: React.ReactNode }) {
+ *   const queryClient = getQueryClient()
+ *
+ *   return (
+ *     <QueryClientProvider client={queryClient}>
+ *       {children}
+ *       <ReactQueryDevtools />
+ *     </QueryClientProvider>
+ *   )
+ * }
+ * ```
+ *
+ * @see {@link https://suspensive.org/docs/react-query/createGetQueryClient Suspensive Docs}
+ */
+export function createGetQueryClient(config: QueryClientConfig = {}) {
+  let browserQueryClient: QueryClient | undefined
+  const getQueryClientConfig: QueryClientConfig = isServer
+    ? {
+        ...config,
+        defaultOptions: {
+          ...config.defaultOptions,
+          queries: {
+            ...config.defaultOptions?.queries,
+            cacheTime: Infinity,
+          },
+        },
+      }
+    : config
+
+  function getQueryClient() {
+    if (isServer) {
+      // Server: always make a new query client
+      return new QueryClient(getQueryClientConfig)
+    }
+    // Browser: make a new query client if we don't already have one
+    // This is very important, so we don't re-make a new client if React
+    // suspends during the initial render. This may not be needed if we
+    // have a suspense boundary BELOW the creation of the query client
+    if (!browserQueryClient) {
+      browserQueryClient = new QueryClient(getQueryClientConfig)
+    }
+    return browserQueryClient
+  }
+
+  return { getQueryClient }
+}

package/src/index.ts

@@ -1,3 +1,4 @@
+export { createGetQueryClient } from './createGetQueryClient'
 export { infiniteQueryOptions } from './infiniteQueryOptions'
 export type { SelectedInfiniteOptions, UnSelectedInfiniteOptions } from './infiniteQueryOptions'
 export { QueriesHydration } from './QueriesHydration'