Understanding revalidatePath vs current documentation

[gmoniava]

I was trying to understand revalidatePath but current docs seem a bit confusing to me, here it is:

• revalidatePath only invalidates the cache when the included path is next visited. This means calling revalidatePath with a dynamic route segment will not immediately trigger many revalidations at once. The invalidation only happens when the path is next visited.
• Currently, revalidatePath invalidates all the routes in the client-side Router Cache when used in a server action. This behavior is temporary and will be updated in the future to apply only to the specific path.
• Using revalidatePath invalidates only the specific path in the server-side Route Cache.

To which cache does the first bullet apply? It does not say. Is it client side router cache? If yes, then next bullet is confusing because it says that all routes are invalidated. Or is it full route cache? What about data cache?

Because I got confused in the following example when I call deleteItem server function, the data gets refreshed immediately.
But the docs above say after it is next visited. So I was not expecting it to get refreshed immediately. So which part of above quote explains this behavior?

Example:

// Server component
export default async function SearchPage({ searchParams }: { searchParams: { q?: string } }) {
  const query = searchParams.q ?? '';
  const results = await search(query);

  return <SearchResults items={results} />;
}

// Client component

'use client';

import { useTransition } from 'react';
import { deleteItem } from './actions';

export default function SearchResults({ items }: { items: string[] }) {
  const [isPending, startTransition] = useTransition();

  return (
    <ul>
      {items.map((item) => (
        <li key={item}>
          {item}
          <button
            onClick={() =>
              startTransition(() => {
                deleteItem(item); // This immediately refreshed the search results
              })
            }
            disabled={isPending}
          >
            Delete
          </button>
        </li>
      ))}
    </ul>
  );
}

@icyJoseph

[VIDAKHOSHPEY22]

Hi!
Great question – the documentation around revalidatePath can definitely be a bit confusing. Here’s how I understand it:

• The first bullet refers to the server-side route cache. When you call revalidatePath('/some-path'), the cache for that route is invalidated, but only the next time someone visits that path. So, the invalidation happens on the next visit, not immediately.
• The second bullet is about the client-side Router Cache. Currently, when you use revalidatePath inside a server action, it invalidates all routes in the client-side cache, causing them to refetch on navigation. This is a temporary behavior and should be updated in the future to only invalidate the specific path.
• The third bullet clarifies that on the server, only the exact path you specify is invalidated.

About your example:
When you call the deleteItem server function, the data refreshes immediately. This happens because after a server action, Next.js triggers a refresh for the current route on the client side to keep the UI up to date, even if the server cache is only invalidated on the next visit. So the immediate refresh you see is a client-side effect.

Summary:

• The “next visit” rule applies to the server-side cache.
• On the client, after a server action like your deleteItem, Next.js often triggers a refresh right away for a consistent user experience.

Hope this clears things up! Let me know if you have more questions or want to discuss in more detail.

[icyJoseph]

I meant the answer, but idk if that one is such to be honest, I've arrived to this thread this morning, after seeing a lot of what looks like llm answers, so I am likely biased.

Not saying there's anything wrong, or frowned upon, when using LLMs to answer. On the contrary, today it is the most efficient way to research a topic. It'd be great if these actually helped people at a better rate. I am trying to make next.js docs content more readily available for these.

However, straight up copy pasting, without verifying what output you got, is likely not helpful - and sets people on the wrong direction. Also for complex issues, these answers are not always fully accurate, and might be just re-wording the OP context, or documentation, which might cause broader implications.

And last but not least, often people end up here, because they already tested all sort of tools, and are still having issues.

[VIDAKHOSHPEY22]

I apologize, honestly I thought I could help because there was no answer and I said I would help and thank you for giving a better answer and again I apologize that I may have given the wrong answer @icyJoseph @gmoniava 😔🙏🏻

[icyJoseph]

No worries! We are all here to help in one way or another!

[gmoniava]

I would have grouped the first and third bullets because they seem to be related to full route cache. And I would add line about "framework updating UI when revalidatePath is triggered from server function" - to the second bullet. @icyJoseph

[gmoniava]

One more thing, just saw example: https://nextjs.org/docs/app/api-reference/functions/revalidatePath#revalidating-all-data, which says that data cache is also cleared sometimes but data cache is not mentioned in the main part of docs which I quoted in my initial question.

This will purge the Client-side Router Cache, and revalidate the Data Cache on the next page visit

@icyJoseph can you clarify?

(Maybe update your first response I wanted to accept it as answer but now feels incomplete).

[madeByIgor]

I agree, their docs really need some clarification. It doesnt help that cache works different out of box in 14 and 15 version.

[niteshcipher]

The key to understanding this is knowing that Next.js uses two separate caches that are affected here:

The Data Cache (Server-Side): This is a cache that lives on the server. It stores the result of your fetch requests and the rendered HTML of your pages. This is the cache the docs are primarily talking about when they say "invalidates the cache when the included path is next visited."

The Router Cache (Client-Side): This is a cache that lives in the user's browser. It stores the pages the user has already visited so that navigating back and forth is instantaneous.

When you call revalidatePath() from a Server Action, it interacts with both of these caches.

[niteshcipher]

What revalidatePath() Actually Does in a Server Action
When your deleteItem() Server Action runs, here’s the sequence of events:

Invalidates the Server Cache (The "Next Visit" Part) ✅
revalidatePath('/some-path') sends a message to the server, telling it: "Hey, the data for /some-path is now stale. The next time someone requests this page, don't serve them the old cached version. You need to re-fetch the data and re-render the page from scratch."

This is the part that aligns with the documentation's description.

Invalidates the Client Cache (The "Instant Refresh" Part) ⚡️
Because the user just triggered this action from their browser, the Next.js client-side router knows the UI is now out of date. As a result, revalidatePath() also purges the client-side Router Cache.

The router then immediately re-fetches the page data from the server. Since the server's cache was just marked as stale (from step 1), the server is forced to run your data fetches again, giving the client the fresh, updated information.

This two-step process is what creates the "instant" refresh you're seeing. The invalidation happens on the server for future visits, but the client-side router is cleared immediately to reflect the mutation that just occurred.

[CHC383]

revalidatePath is called on the server-side, how does the client-side router knows the UI is out of date since not every action will revalidate the content? Is it some sort of build time mark NextJs put, or maybe React RSC is able to communicate and push data from the server side?

[icyJoseph]

When the UI through a server action, calls revalidatePath, this is communicated back to the browser in the headers, as per current implementation detail. Then the client side router evicts, clears, invalidates, the data it holds, and issues a request to the server for a new tree to patch against the currently showed tree.