Clear Router Cache without refetching current route

[chriskrogh]

Goals

1. Add support for clearing the router cache without refetching the current route

Background

Problem

Currently, all of the methods of invalidating the Router Cache involve refetching / re-(server)-rendering the current route (revalidateTag and revalidatePath do this even though it's not mentioned in the docs).

This is a problem for us at Faire because some routes can be "expensive" if refetched often.

Use case

Faire is an e-commerce marketplace. We recently migrated most of our critical user journeys (home, search, categories, cart) to be rendered primarily using server components. When users add items to their cart while browsing, we want to invalidate the Router Cache so that subsequent visits to the cart page won't be stale.

However, if we were to do so right now, next would refetch the current route (e.g. "search") every time the cart is updated which is undesired.

Here's our workaround

Whenever we update the cart, we set a global client state marker (shouldRefreshCartPage) to true. At the top of the cart page's layout, we pass lastUpdatedAt={Date.now()} to a client component so we can keep track of how old the cart page's router cace entry is. If shouldRefreshCartPage is true, and we haven't just loaded the cart page, then call router.refresh

useLayoutEffect(() => {
  if (
    shouldRefreshCartPage &&
    lastUpdatedAt < Date.now() - REFRESH_THRESHOLD // 3s
  ) {
    setStore({ shouldRefreshCartPage: false });
    refresh();
  }
}, [shouldRefreshCartPage, setStore, refresh, lastUpdatedAt]);

This isn't that great since we wait until the cart page starts hydrating to refresh. Clearing the router cache would allow us to prefetch the cart page on subsequent navigations each time it was invalidated.

Proposal

Short term

To preserve the existing functionality as much as possible, it would be nice to add an optional argument to router.refresh, and revalidateTag e.g. { refetchCurrentRoute?: boolean } that's true by default, but can be set to false. If set to false, next would clear the router cache for all other pages except the current page.

Followup

If we can skip refetching the current route from revalidateTag, then hopefully we can invalidate only a specific route in the router cache (for us this would mean only invalidating the cart page).

Long term

I know the team is working on some big changes to caching for PPR #72875 but I'm hoping that one day we can clear or refetch the cache for segments individually (similar to react query's clear and invalidate with refetchType).