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).