Docs: revalidatePath docs should be updated to reflect the current behavior

[tdurnford]

What is the improvement or update you wish to see?

The current revalidatePath documentation suggests that developers can selectively revalidate specific routes. However, as per a GitHub issue comment by @timneutkens, the revalidatePath function currently revalidates the entire client-side router cache, not just individual paths.

This behavior contradicts the documentation's implication that the function allows for granular control over route revalidation. It's important for the documentation to accurately reflect the current capabilities of revalidatePath. Misleading information could lead to confusion and inefficiencies among developers using this function.

I recommend updating the documentation to clarify the current behavior of revalidatePath and to note that future updates are planned to make this feature more granular. Additionally, providing a roadmap or an estimated timeline for when developers can expect the revalidatePath function to support individual path revalidation would be highly beneficial for planning and development purposes.

Is there any context that might help us understand?

The lack of clarity on when the function will support granular revalidation makes it challenging for developers to plan and implement cache strategies effectively. By providing accurate documentation and a roadmap for future updates, developers can better anticipate changes and adapt their strategies accordingly.

Does the docs page already exist? Please link to it.

https://nextjs.org/docs/app/api-reference/functions/revalidatePath

_DX-2254

[kahnclusions]

This also needs to cover the several features that are not working as expected per documentation. The recommended way to do forms in modals is with intercepting and parallel routes, but by calling revalidatePath or revalidateTags from a server action causes the client to redirect to the intercepting route's page, control never returns to the submit function. I don't even know a workaround besides "don't use intercepting/parallel routes" for forms.

Everything around these features just seems totally broken and the lack of any response or updates addressing these issues is a bit disappointing.

See #54085

[Vibrat]

The most noticeable effect that I observed is the flash of an entire screen due to hot reload. And to handle granular re-rendering in client, I had to opt out of revalidatePath and revalidateTag and use another full-client-cache query library like react-query (see more: invalidateQueries)

For example, we can wrap server action by a client function that invalidates client query as below.

import { useQueryClient } from '@tanstack/react-query'
import { onServerActionSubmit } from "./actions.ts"

export const MyForm =  () => { 
  const query = useQueryClient()
  async function clientSubmit(e) {
     const serverActionResponse = await onServerActionSubmit()
     if (serverActionResponse == true) {
        query.invalidateQueries({
           queryKey: ["/api/test"]
      })}
  }
  
  return <form onsubmit={clientSubmit}>
  ...
  </form>
}

[github-actions]

This closed issue has been automatically locked because it had no new activity for 2 weeks. If you are running into a similar issue, please create a new issue with the steps to reproduce. Thank you.