Doubts about queryClient scoping and server/client caching in Next.js App Router [skill issue] #9314

lucarampi · 2025-06-25T20:43:28Z

lucarampi
Jun 25, 2025

First of all, thanks for the amazing work on TanStack Query and its amazing course. I’ve been using React Query for a while, but after diving deeper I’m facing some edge cases that are probably a skill issue on my side, and I’d love some insight.

📖 Context

I’m using Next.js 15 (App Router) with both server-side prefetching and client-side React Query hydration. My app structure is something like this:

In RootLayout.tsx:

export default async function RootLayout({ children }: NextLayoutProps) {
  await queryClient.prefetchQuery({ ...userSettingsQuery(), queryFn: fetchUserSettings });
  await queryClient.prefetchQuery({ ...currenciesQuery(), queryFn: fetchCurrencies });

  return (
    <html lang="en">
      <body>
        {/*This smells wrong*/}
        <Providers>
          <HydrationBoundary state={dehydrate(queryClient)}>
            {children}
          </HydrationBoundary>
        </Providers>
      </body>
    </html>
  );
}

In Providers.tsx:

const queryClient = getQueryClient();

export default function Providers({ children }: ProvidersProps) {
  return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
}

🤔 The Problem

After some debugging, I noticed:

Server-side prefetch queries are being cached across multiple instances of the app (I suspect Next.js is caching the request in one of its internal caches, as data sometimes auto-updates after 5 minutes — which is odd since my external APIs don’t cache that way).
I might have misconfigured React Query, particularly regarding how I’m creating and scoping queryClient instances.

My suspicion is that I’m creating a queryClient outside of the Providers component (server side), and then again creating another one (now client side inside Providers). Then I hydrate the state from the server-prefetched queries with the first instance — but the client uses a different one. Could this be causing the inconsistent behavior I’m seeing (some queries stale, others up-to-date)?

🔄 Prefetching Specifics

Inside inner page layouts (like /product or /product/[id]), I also prefetch page-specific queries server-side.
But sometimes — seemingly random — after mutating a product, navigating back to the list or product page might still show stale data.

Notes:

Forcing a refetch via React Query DevTools works fine.
Hard reload may or may not fetch fresh data.
Client-side requests (via fetch calls to Next API routes) work consistently.
Server-side prefetch calls go directly to external services always return stale data.
If I invalidate the query immediatelly before the prefetch, the data returned is correct (but may be due to a after client-side refetch)

📌 Questions

Is my RootLayout + Providers setup flawed?
Am I mishandling queryClient instancing and scoping, causing server and client to work with different clients?
Extra question: Should I await queryClient.invalidateQueries() if I need to trigger a router navigation right after?
(Or is it safe to navigate and rely on background refetching?)

Would appreciate any guidance on properly handling queryClient instances between server-side prefetch and client-side hydration in Next.js App Router.

Thanks a lot!

After notes:

If I'm asking here, it's because I’ve spent quite some time researching, testing, and debugging this on my own. And in all my skill issue ignorance, I haven’t been able to find a proper fix or a clear explanation for this specific scenario.

So if your first thought is "look at the docs", I’d genuinely appreciate it if you could drop a link to the exact section or topic you have in mind — it would be super helpful. 🙏

TkDodo · 2025-09-04T16:52:32Z

TkDodo
Sep 4, 2025
Maintainer

that depends what getQueryClient is doing:

const queryClient = getQueryClient();

export default function Providers({ children }: ProvidersProps) {
  return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
}

usually, you’d want to always create a new QueryClient on the server within the sever component to avoid leaking things between requests. This is the page you’d want to read:

https://tanstack.com/query/latest/docs/framework/react/guides/advanced-ssr

0 replies

lucarampi · 2025-09-04T17:01:58Z

lucarampi
Sep 4, 2025
Author

My exact getQueryClient implementation is (inspired from here):

import { convertToMilliseconds } from '@/lib/utils/convert-to-milliseconds';
import { QueryClient } from '@tanstack/react-query';

function makeQueryClient() {
  const queryClient = new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: convertToMilliseconds(5, 'minutes'),
        retry: 1,
      },
    },
  });
  return queryClient;
}

let browserQueryClient: QueryClient | undefined = undefined;

export function getQueryClient() {
  if (typeof window === 'undefined') {
    // Server: always make a new query client
    return makeQueryClient();
  }
  // 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 = makeQueryClient();
  return browserQueryClient;
}

I always call this method, both server-side and client-side (also I don't use useQueryClient(), instead I just call the getQueryClient() outside the component scope)

1 reply

TkDodo Sep 4, 2025
Maintainer

but if you create a client outside the component on the server, you create one client that is shared between requests. This will not be a new client on every request!

lucarampi · 2025-09-04T17:23:36Z

lucarampi
Sep 4, 2025
Author

To that extend, I`ve recently watched the server-side rendering from the course. I will just paste the comment here so it is publicaly available:

I'm using the exact setup from this section of the React Query docs:
https://tanstack.com/query/latest/docs/framework/react/guides/advanced-ssr#streaming-with-server-components

The problem I'm running into is that I'm always getting stale data, even after a hard refresh (Ctrl + F5). The only way I’ve found to fix it is by calling invalidateQueries right before prefetchQuery() in the server component — which feels a bit off.

App flow:

I have a page that lists books.
On create/edit, I use useMutation and invalidate the booksQuery on the client side.
When I go back to the list page (or reload it), the data is outdated — it doesn’t reflect the mutation result.

But if I do this in the server component:

import { getQueryClient } from '../../get-query-client';

export const dynamic = 'force-dynamic';

const queryClient = getQueryClient();

export default async function RootLayout({ children }: NextLayoutProps) {
  await queryClient.invalidateQueries(booksQuery()); // <- THIS FIXES IT
  await queryClient.prefetchQuery({ ...booksQuery(), queryFn: fetchBooks });

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      {children}
    </HydrationBoundary>
  );
}

…it works. Without the invalidation, prefetchQuery seems to return stale data — even on the first load.

What I’m suspecting

This might be related to Next.js 15’s caching. I’m already using export const dynamic = 'force-dynamic' in the layout/page, so I’m not sure why the query is still stale — maybe the server component is caching the query client state?

It’s strange, because the mutation does trigger a client-side invalidation, but it doesn't seem to affect the server-rendered hydration when navigating back.

I’m testing a few other patterns for initializing the query client (based on the docs), but figured I’d ask in case someone else has run into this.

Does prefetchQuery always read from a cached state in server components unless you explicitly invalidate it first? Or is there a better approach for ensuring fresh data here?

Note: In both client and server components, when I want to access the query client, I just do the following (pretty sure I saw this pattern in the docs):

"use client"
import { getQueryClient } from '@/app/get-query-client';

const queryClient = getQueryClient();

export default function MyClientComponent() {
  ...
}

import { getQueryClient } from '@/app/get-query-client';

const queryClient = getQueryClient();

export default async function MyServerComponent() {
  ...
}

Extra context:
My query provider looks like this:

const queryClient = getQueryClient();

export default function Providers({ children }: ProvidersProps) {
  return (
    <QueryClientProvider client={queryClient}>
          {children}
    </QueryClientProvider>
  );
}

I came across a few GitHub issues and videos that mention wrapping it in useState or useRef, which left me a bit confused — I’m wondering if that’s still necessary with the current setup.

2 replies

TkDodo Sep 4, 2025
Maintainer

I'm using the exact setup from this section of the React Query docs:

no, you don’t. in our example, the function call to getQueryClient is inside the component:

export default function PostsPage() {
  const queryClient = getQueryClient()

in your example, it’s outside the component.

lucarampi Sep 4, 2025
Author

I was 10000% sure I had seen this implementation somewhere in the docs/course. I just triple-checked and couldn’t really find it... my bad. Maybe I hallucinated (am I becoming an AI?).

I’ll take some time to test it inside a component to see if it solves the “stale data on the server-side” issue I mentioned earlier.

On a related note, should I prefer useQueryClient or getQueryClient (on the client side, of course)?

I’ll share feedback soon, thanks for your attention!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Doubts about queryClient scoping and server/client caching in Next.js App Router [skill issue] #9314

Uh oh!

{{title}}

Uh oh!

Replies: 3 comments 3 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

Doubts about queryClient scoping and server/client caching in Next.js App Router [skill issue] #9314

Uh oh!

lucarampi Jun 25, 2025

📖 Context

🤔 The Problem

🔄 Prefetching Specifics

📌 Questions

After notes:

Replies: 3 comments · 3 replies

Uh oh!

TkDodo Sep 4, 2025 Maintainer

Uh oh!

lucarampi Sep 4, 2025 Author

Uh oh!

TkDodo Sep 4, 2025 Maintainer

Uh oh!

lucarampi Sep 4, 2025 Author

App flow:

What I’m suspecting

Uh oh!

TkDodo Sep 4, 2025 Maintainer

Uh oh!

lucarampi Sep 4, 2025 Author

lucarampi
Jun 25, 2025

Replies: 3 comments 3 replies

TkDodo
Sep 4, 2025
Maintainer

lucarampi
Sep 4, 2025
Author

TkDodo Sep 4, 2025
Maintainer

lucarampi
Sep 4, 2025
Author

TkDodo Sep 4, 2025
Maintainer

lucarampi Sep 4, 2025
Author