Deep Dive: Caching and Revalidating

[timneutkens]

The Next.js App Router introduced new heuristics around caching and revalidating. To ensure we’re all discussing the intended behavior of how caching is designed to work, I thought it would be helpful to have a discussion going in-depth on how each piece works.

This complements the recently published caching documentation. It’s a follow up to an issue where some members of the community were confused about the client-side router cache / wanted a slightly different behavior, so I wanted this to be an opportunity to set the context for how it’s designed to work and open a discussion with the community.

Please read the entire post before replying, as it is important to have this context.

Data Mutations

The App Router was originally announced almost a year ago. At the time, we had not yet shared our plans for how we intended to handle data mutations. There Server Actions were not yet supported, and router.refresh() did not yet clear the route cache as expected yet.

We understand this caused a bit of confusion, so we’d like to clarify that here.

Since then, we’ve added Server Actions. This is how we expect most mutations will happen when it’s stable. We’ve also made sure router.refresh() behaves as expected.

Below, you’ll find sections on the individual pieces, how they fit together, and how you can replicate some of the behaviors you’ve used in other tools (sometimes used implicitly).

These sections are broke up into two pieces:

• Mutations that I, the user, trigger in an application, including forms.
• Mutations that others, like colleagues, trigger, including changes like adding products in a CMS.

The mutations I trigger

Invalidation

Server Actions (revalidatePath / revalidateTag)

• When it’s useful
  • User interactions that require the server
    • Example: forms
      • Adding a product
        • You add the product as part of the user sessions, then call revalidateTag / revalidatePath to ensure the page gets re-rendered, because the cart component is rendered as a server component this ensures it’s up to date (similar to mutate() in useSWR / react-query)
      • Login / logout
        • You submit the username/password (or other auth flow) through a form that is backed by a server action. You set a cookie, and then call revalidatePath / revalidateTag to ensure the Router Cache is purged and a new render happens with the newly set cookie.
    • Example: In-page typeahead / search results box
      • What you see when searching on [nextjs.org/docs](http://nextjs.org/docs) for example (currently that is backed by Algolia, but say it was backed by your own code)
    • Example: Tooltips based on permissions
      • What you see on Facebook / Instagram / GitHub where the tooltip is loaded based on server data when you click on it
• How it works
  • "use server" adds a marker to the function at compile time and move it into a separate module. All Server Actions have their own unique ID so that they can be referred to individually. (This explanation is heavily simplified, reality is a bit more involved)
  • When you call the function it will do a POST request to the current URL with the Server Action ID, that allows Next.js to call the right underlying function.
    • Example of calling the function: The <form action={serverAction}> is submitted or you manually call serverAction() in a client component
  • While calling the function you’ve defined to be a Server Action a few things can happen
    • The function calls revalidatePath / revalidateTag

      • Will purge the specified entry from the Full Route Cache / Data Cache (the server caches)

        • When the route is static rendering (in the full route cache) all fetch tags that were used are also tags on the Full Route Cache, meaning that if you revalidateTag it’ll still correctly purge the Full Route Cache too.

      • Based on which path is in revalidatePath the current page will re-render on the server. In case of revalidateTag the current page always re-renders

        • What you might realize later on is that this behavior is very similar to calling router.refresh()
        • This happens as part of the same round-trip, so there is no additional client-side request

      • Will purge the client-side cache, depending on which path was provided. In case of revalidateTag the entire client-side Router Cache is purged.

        • Example using Server Actions:

        export async function updateUser(config) {
          "use server"
          await prisma.user.update(config);
          revalidateTag('prisma-user');
        }

        • In the thread there was a lot of confusion around this as there were a few bugs in the implementation, which have been fixed in the latest version of Next.js. (E.g. it didn’t purge the cache used for back/forward, only prefetches, so stale data would be possible, this is no longer the case but wanted to highlight that)
        • This behavior uses practically the same code path as router.refresh() after the fetch to the server comes back, so they purge the router cache essentially in the same way.
          • In the future we’re going to be a bit smarter about the purging as if you’re currently on /products and call revalidatePath('/dashboard/settings') in a Server Action the entire Router Cache is still purged, even though we can make sure it purges only the /dashboard/settings path and any segments below it
            • Anything below it here means /dashboard/settings/environment for example, we can’t know if the layouts below the provided path have changed so the Router Cache has to be purged for that case.
            • As you might have guessed this also means that revalidatePath('/') means you purge all paths in the Router Cache, as it’s / and any segments below it. Calling router.refresh() is equivalent in purging and re-filling the Router Cache to revalidatePath('/').
    • The function calls redirect()
      • Calling redirect means you can’t return a result from the server action, as the redirect will be applied immediately
    • The function calls cookies().set()
      • In this case the Router Cache is entirely invalidated and the page is re-rendered, similar to calling revalidateTag, as changing cookies could affect what is rendered in layouts.
        • Example: You login / logout
        • Example: Feature flags change
    • The function returns a result
      • You can return your own response from Server Actions, this could be an object, but could also be JSX, anything valid to be serialized from Server Component to Client Component is also a valid return value for Server Actions.
      • This does not prohibit you from calling revalidatePath / revalidateTag, in the case that you do call those the response from the server will hold both the result of your function as well as the newly rendered page, both will be applied to the application.
      • In order to use the result you have to manually call the Server Action, this does not apply to passing the Server Action directly to the action prop in <form action={serverAction}>

Route Handlers (revalidatePath / revalidateTag)

• When it’s useful
  • Purging the server-side caches (Full Route Cache and Data Cache) based on external events
    • Example: You edit an item in a CMS, you want to purge the current Full Route Cache / Data Cache so that the new data will be fetched and populated in the Full Route Cache / Data Cache.
      • Even though the caching document explains Full Route Cache and Data Cache separately, it’s actually just one Data Cache under the hood. The main reason we documented it as two separate concepts is that the Full Route Cache part is storing HTML / RSC Payload whereas the Data Cache part you interact with is storing fetches and unstable_cache calls (that API will be stable in the near future)
• How it works

  • Calling revalidatePath / revalidateTag will purge the specified entry from the Full Route Cache / Data Cache

    • When the route is static rendering (in the full route cache) all fetch tags that were used are also tags on the Full Route Cache, meaning that if you revalidateTag it’ll still correctly purge the Full Route Cache too.

  • If you were to fetch() a route handler from the user’s browser that won’t affect their Router Cache because there is no way to know in Next.js what was changed. In that case you have to call router.refresh().

    • However, since you’re going to call a route handler which is an API endpoint on the application you could use Server Actions instead to do this in one round-trip instead of two.

    onClick={async () => {
    	const res = await fetch('/my-route-handler')
      const json = await res.json()
      // etc
      router.refresh()
    }}

router.refresh()

• When it’s useful

  • When you want to purge the router cache based on an event that is outside of user interactions covered by server actions

    • Example: You have a form / click handler that fetches some external API directly to e.g. add an item and you didn’t use Server Actions for it. This is similar to the case for mutate() when you use useSWR or react-query
      • Using Server Actions for this is better because in the example above you do two round-trips, one to the API and one to render the page with updated data. Server actions make this a single round-trip, you add the item and call revalidatePath or revalidateTag which renders the new result in the same request to the server. But obviously it might not always be feasible to use server actions.

  • When you want a stale-while-revalidate (useSWR / react-query) behavior where the page is rendered and then updated with the latest items

  • Example: see below code, keep in mind this is really similar to what useSWR does under the hood, you just have full control over when / how to trigger with the revalidation. Keep in mind this only affects the router cache, not server-side caches:

    import { useRouter, usePathname } from 'next/navigation'
    import { debounce } from 'lodash';
    
    interface DataRevalidatorProps {
      /**
       * The timeout in milliseconds to wait before revalidating the data.
       */
      timeout?: number;
    }
    
    export function DataRevalidator({
      timeout = 5000,
    }: DataRevalidatorProps): null {
      const router = useRouter();
      const pathname = usePathname()
    
      const getRefresher = useCallback(() => debounce(
        () => {
          // Can be removed, just to showcase when it triggers refresh
          console.log(
            `[${new Date().toLocaleTimeString()}] Triggering router.refresh()...`,
          );
          router.refresh();
        },
        timeout,
    		{ leading: false, trailing: true }
      ), [router, timeout]);
    
      // Trigger router.refresh() whenever `pathname` changes.
    	// Note: this does not cover searchParams, you can add `useSearchParams` if needed.
      useEffect(()=> {
    		const refresher = getRefresher()
        refresher()
    	}, [revalidate, pathname])
    
      // Trigger router.refresh() when focus goes back to the window (similar to useSWR / react-query)
      useEffect(() => {
        if(process.env.NODE_ENV === 'development') {
    			return
        }
    
    		const refresher = getRefresher()
    
        window.addEventListener('focus', refresher);
        return () => {
          refresher.cancel();
          window.removeEventListener('focus', refresher);
        };
      }, [revalidate]);
    
      return null;
    }

• How it works

  • Calling router.refresh() causes a few things to happen:
    • A fetch to the server to get the current page in it’s entirety (this includes <html> down to the content, it’s everything on the page but as RSC Payload instead of HTML.
    • Purges all router caches
      • The prefetch cache (holds all prefetches)
      • The router navigation cache (the 30s one)
      • The component cache (holds all segments you navigated to, it’s used to allow partial rendering and back/forward with preserved scroll position)
    • Applies the fetched RSC Payload to the purged cache, making it the only path in the component cache.

The mutations others trigger

Data source changes

The other side of the mutations story, what if my colleague makes an update in the CMS instead of doing it myself. If that mutation is backed by revalidatePath / revalidateTag it would invalidate the Full Route Cache and Data Cache, but those are server-side, and the Router Cache in my browser tab might still have the previous result from the server, instead of the very latest data.

A bunch of the comments on the issue were talking about this case where someone else does a mutation and what happens in that case, so let’s start by clarifying what the behavior is:

• I navigate to the /products route
• Someone else triggers a server action that adds a new product to the ecommerce store
• I navigate away to /account by clicking on account in the menu
• I decide I want to see the products again, really want that hoodie on https://demo.vercel.store
• I click on products in the menu
• I instantly go to the /products route again, similar to if I had clicked the back button
• I see the same page as what I saw when I initially opened the /products route

If the route was “static” (i.e. static rendering or setting prefetch={true} when the page is using dynamic rendering) the time where I can instantly go back to /products is 5 minutes

If the route was using dynamic rendering (i.e. using cookies, headers, export const dynamic = ‘force-dynamic') the time where I can instantly go back to /products is 30 seconds

After this 30 seconds or 5 minutes the cache item would be purged for router.push / router.replace navigations (which includes <Link>).

Let’s assume /products is marked to use dynamic rendering. This would mean the cache time is 30 seconds, so if I spend slightly longer on /account I don’t notice there is cache.

Now as for why this behavior exists there are multiple reasons:

• When you click / tap around the menu quickly the UX would be jarring when you click on a link, then another, and then back, and see many loading states again.
• When you’re on a slow network connection this behavior helps ensure the navigating back/forward using links still feels fast.
• It’s also about keeping your place when navigating between router quickly, for example looking something up on another page and then going back to the previous one.

There is prior art and research associated with this timing, e.g. Facebook has this timing when you click around the application. react-query is adopting this timing as well.

The /products route might still leverage the Data Cache for the header / footer data, in order to make sure the only blocking data request is for the products themselves, which is fine.

This doesn’t mean that you can’t invalidate the Router Cache, you can still use the stale-while-revalidate and focus behavior useSWR / react-query have (see router.refresh section above).

Overall we believe the default for this behavior is correct, however we’d like to figure out in what way folks in this issue want to opt-out of the behavior, as there are multiple related features that seem to be confused for this behavior.

Partial Rendering

Since the docs explain the high level concept quite well here’s an excerpt from the docs:

Partial rendering means only the route segments that change on navigation re-render on the client, and any shared segments are preserved.

For example, when navigating between two sibling routes, /dashboard/settings and /dashboard/analytics, the settings and analytics pages will be rendered, and the shared dashboard layout will be preserved.

partial-rendering.avif

Without partial rendering, each navigation would cause the full page to re-render on the server. Rendering only the segment that changes reduces the amount of data transferred and execution time, leading to improved performance.

The way this is possible is that the App Router has a concept we called the “Router Tree”, this tree is a format that decides what is being rendered on the current screen you’re looking at.

The Router Tree looks somewhat like this (simplified):

// Array format as it's transferred between server/client often.
type RouterTree = [
	// The segment, e.g. 'dashboard' or for dynamic params ['user', 'timneutkens', 'd' /* d for dynamic */].
  // Final segment is called __PAGE__
	segment: Segment
  // In the simple case this would only hold `children`.
  parallelRoutes: {
		// E.g. `children` or `modal` (when you add `@modal` as a parallel route slot).
		[parallelRouteKey: string]: RouterTree
	}
]

Every route has a Router Tree associated with it. For example for a route like /dashboard/settings/page.tsx the router tree would look somewhat like this:

const routerTreeForSettings: RouterTree = [
	'dashboard',
  {
    children: [
      'settings',
      {
        children: [
		      '__PAGE__',
          {}  
        ]
      }
    ]
  }
]

When you first request the page a version of the Router Tree server-side holds the list of components (i.e. layout, loading, page), this is then used to render the entire page.

When you navigate the Router Tree that is currently on screen is sent as part of the payload to the server, that allows the server to diff the current Router Tree with the Router Tree for the page you’re requesting. The result of that diff is then used to render only the part of the Router Tree that is different.

The Router Tree is kept in the browser history (more on this in the back/forward section)

As you might have figured out by now a tree of what is currently on screen is not enough if we can’t reuse the individual segments from a previously rendered page. That’s where the “Component Cache” part of the client-side router comes in.

Besides keeping the Router Tree in the router state, we also keep the component cache there. This cache looks somewhat like this (simplified)

type ChildSegmentMap = Map<
  // For explanation purposes showing Segment
  // Real value is a serialized version of Segment (string)
	Segment,
	ComponentCacheNode
>

interface ComponentCacheNode {
	// There is also 'DATAFETCH' and 'LAZYINITIALIZED' but not going into those in this post.
	status: 'READY',
  // This property only exists on the `__PAGE__` nodes.
	head?: React.ReactNode
  subTreeData: React.ReactNode
	parallelRoutes: Map<ParallelRouteKey, ChildSegmentMap>
}

The Component Cache keeps track of each rendered segment separately, in doing so it unlocks a bunch of features:

• Navigating between pages reusing segments (Partial Navigation).
• Instant back/forward navigation that preserves the browser scroll position
• Parallel Routes / Interception, as you can keep the segment cache nodes of multiple pages at the same time. The Router Tree is the other piece in making Parallel Routes work as that decides what is being shown on screen.
• Purging individual segments of the router cache (i.e. router.refresh() purges the entire cache, but revalidatePath('/dashboard') will only purge the client-side router cache below the specified dashboard path in the near future).

Back/forward navigation

This behavior is very similar to the bfcache shipped in browsers: https://web.dev/bfcache/.

When navigating between routes the client-side router calls pushState or replaceState to update the url that you see in the browser url bar. When it does it also pushes some metadata as part of that, specifically the Router Tree is attached to the history entry.

The Router Tree decides what is rendered on the screen (see previous section for deeper explanation).

When you navigate back/forward (popstate) the Router Tree from the history entry is applied to the router. This caused the page to render that Router Tree.

By leveraging the Component Cache we can take advantage of the default scrollRestoration in browsers, ensuring that you end up back in the exact place you came from when navigating backwards/forwards.

This scrollRestoration behavior in the browser has a set heuristic in which you need to do all the work otherwise it bails out of restoring the scroll position.

Now you might be wondering how this is different from Pages Router.

In Pages Router there were two behaviors, both had problems that apply to the client-side router:

• getStaticProps
  • When you navigate the data would be fetched and put in a simple cache that is essentially { [url: string]: Data }
  • When navigating backwards/forwards the cache would reuse the data
  • This behavior has a pitfall: you can never invalidate the client-side router cache, so if you make a change to the data the user would have to refresh the tab to see the result. There were no APIs to purge that cache.
  • Scroll position would be restored
• getServerSideProps
  • When you navigate, a fetch to the server would be triggered to get the data.
  • When you navigate backwards/forwards it would also trigger a request to the server for the data
  • Backwards/forwards navigation wasn’t applied instantly because the fetch would still be ongoing before you’d hit the heuristic where applying scroll bails out so you’d end up with a UX that felt broken.

We believe the new behavior which ensures scroll position is preserved and navigation is instant is the right behavior, it mirrors the browser bfcache behavior.

The main thing to keep in mind with this behavior is that the client-side Component Cache that is used when navigating back/forward is only purged when you call one of the purging functions (router.refresh(), revalidatePath, revalidateTag).

This is not that different from what you’ve likely done before though, i.e. if you build a fully client-side SPA you’re essentially building your own cache using state management to keep track of fetches, that one would also have to be purged, similarly in useSWR / react-query.

Near-term work on the router

Our focus right now is on improving stability of the App Router and we’re spending a significant amount of time investigating and fixing reported bugs. Once those are done, there’s a bunch more work on features that improve client-side router performance.

Static Layout Optimization

Currently when a route is fully static (Static Rendering) we fetch the url for the RSC Payload and get a HIT on the Full Route Cache, this means that the request is served as a static file and thus fairly fast. However, this response could be optimized further by splitting up the layout rendering, specifically we could generate a RSC Payload for every layout which in turn means we can get more granular navigations similar to when doing Dynamic Rendering.

Batching of navigations / refresh

Currently navigation fetches happen in sequence in order to ensure the state is correct across multiple React Transitions. However, there’s a new feature in React Experimental (which is used when you enable Server Actions) that allows the startTransition function itself to be async and React will keep track of the order while being able to trigger multiple transitions at the same time. We’re planning to leverage that to speed up the case where you call navigations multiple times. An example of that being updating the searchParams while you type in an input field.

Batching of Server Actions

Currently server actions are ran in sequence, they should still run in the sequence you call them in general for consistency, but we can do a single request to the server to run multiple actions.

Client / Offline Islands

We’re working on a proposal for marking sections of your application as more SPA-like where navigations would not fetch the server, there’s a trade-off with this in that we’d have to send a manifest of all possible JS to be loaded in that particular “island” (set of routes).

Conclusion

Now as for configuring the 30 seconds caching of dynamic rendering RSC Payloads.

Let’s preface with this: reading the feedback I noticed there is a bug in the current behavior where every subsequent navigation to the page before the 30 seconds has passed increases the time by another 30 seconds. This is a bug and we’re going to change it to 30 seconds since navigating away from the page, so if you navigate to /account then wait 10 seconds and navigate back to /products it would not increase the time by another 30 seconds. Instead, the cache node would be purged after another 20 seconds (as we clicked back after 10 seconds).

There’s an alternate universe where we could have gone by choosing everything is dynamic by default, this would mean we would always from the root of the application down on navigations.

This would be similar to how getServerSideProps works in Pages Router. However, in doing so that would introduce a few problems, for example:

• As you start moving more components from the Client to the Server you increase the RSC Payload, which you now have to refetch anytime you do anything, like navigating, mutating, etc.
  • This is especially visible when you have layouts that are shared between multiple pages. This could be the root layout that holds <html> etc. or even the dashboard layout when navigating between dashboard pages. Without Partial Navigation this would mean we refetch from the <html> down for all these interactions.
    • This would also mean significantly more bandwidth usage which affects both performance on slow networks and would increase cost.
  • In the future we’re planning to provide ways to make these Partial Navigations even smaller, where only a single component or a smaller amount of components is rendered. For example, tooltips, searchbox, tabs, pagination, accordions.
    • It’s unclear if these navigations would also have to refetch the page and layouts. If there was no router cache and every interaction needs a full rerender of the page this type of pattern would become slow as all data fetching for the route would have to run, just to show the tooltip.
• If you had this mode where everything is dynamically rendered and there was no caching and Partial Navigation you always rerender the entire page on the server. That also means that all your components, including 3rd party npm modules, will need to reason about how they stay fast by introducing their own caching mechanism, for example react-tweet would need to write to disk or an external store.
  • Similarly if you do the same in the browser if there is no cache you end up introducing one yourself, for example useSWR / react-query introduced introduce their own caching behavior. Or even if you use a state management library like Redux you end up rolling your own client-side cache that has to be managed whenever changes happen (i.e. calling mutate() or dispatch()).
    • While that might be fine in a SPA with Server Components the router is deeply integrated into the way Server Components are rendered, as such it becomes unwieldy to manually keep track these navigations / caches in an external library. This is why the maintainer of react-query pointed out you might not even need react-query in a Server Components world.

We want to avoid forking the behavior in Next.js and RSC as much as possible as otherwise this would create split in the RSC ecosystem where using a component in one application is different than using it in another application.

We’re also expecting that in the near future it will be less likely that you have to manually call revalidatePath / revalidateTag, as data fetching solutions like ORMs/SDKs could handle invalidation for you automatically as part of the library when inserting/updating data. E.g. Prisma’s SDK could automatically

// Without integration into the SDK
export async function updateUser(config) {
  "use server"
  await prisma.user.update(config);
  revalidateTag('prisma-user');
}

// With integration into the SDK
// If the SDK called revalidateTag and applied tags instead:
export async function updateUser(config) {
  "use server"
  // Automatically calls `revalidateTag` on your behalf.
  await prisma.user.update(config);
}

With this additional context and explanation of the internals, how to handle mutations, how to get fresh data using the stale-while-revalidate pattern, and the bugfix, does this make sense or do you still have a case that is not covered. When you could configure the time to be zero instead of 30 would that solve a case you’re running into even though that wouldn’t affect back navigation and such? Let me know!

If you start reading at the end of the post, please read the entire explanation from start to finish before commenting on this discussion.

[jamesisaac]

Hi Tim, thanks for the detailed write-up.

The functionality I'm keen to get out of a framework like Next.js is SSR on the initial page load, for reasons like SEO & accessibility. Having a fallback html payload before the JS app kicks in, which is industry standard in sectors like ecommerce. Beyond that, when the user has JS enabled and is navigating between screens, I don't exactly see a need for RSC (beyond not wanting to write and maintain separate Server/Client Component implementations of each screen).

The main points you've listed for requiring the client-side cache seem to come down to performance? But IMO a higher priority for certain types of websites is predictability over marginal performance gains. I wrote a comment in the last thread about how, while "bfcache" may well be intuitive, clicking on a link not loading a fresh view of the data is IMO unintuitive compared to way the majority of the web functions.

I also don't really follow why this client-side cache is so important for performance, yet only up to 30 seconds, and after that it becomes unimportant (seems very arbitrary).

To give a more specific use-case: imagine an ecommerce website with a public-facing products list page. SSR is essential for the reasons listed above. But that page may also contain lots of highly dynamic state (e.g. amount left in stock, how many the user has added to the basket, and more advanced gamification features). Having that data be stale even though the user just clicked a fresh link to that page could be highly confusing / make the site feel unreliable (ironic as the stated goal is user perceived performance, but I'd perceive a website showing me half-minute old data as much "slower" than one which spends 200ms longer on a loading spinner but then gives me perfectly fresh data). And to address some of the workarounds you talked about, consider an example where:

• The mutations to this products list page are made by other users.
• This is a bigger system where the Next.js website is just one front-end to a central back-end API server, with other clients such as mobile apps. So the idea that the ORM central API is going to make revalidateTag calls is not very realistic, it's a completely different system, maintained by a separate team than the one working on the website.

[switz]

If that's the behavior you want then great, we're on the same page.

I am not OP, but that is exactly the behavior that I want.

[Fredkiss3]

If that is reluctance to wanting to figure out a solution then I'm not sure why I'm even posting these replies.

Sorry for the rant, as it comes of a place of frustration, i should have worded it better and not assumed ill intentions about you or the team 🙏.

---

The behavior you get with 0 seconds instead of 30 seconds:

• Still have Partial Rendering, so only the piece below the common layout is rendered / replaced on the page. For example app/dashboard/layout.tsx will not rerender when navigating between /dashboard/settings and /dashboard/profile.

I Suppose this behavior is expected, and that would help fix at least some of my issues with the 30s caching, this is ok with me.

What would be the more flexible approach IMO, is if layout caching could also be configurable. Like with segment config as of today, whenever i specify a cache time on the layout it would be propagated and applied to the whole segment, same for a cache time to individual pages which would only affect those pages.

I preshot a use case in an invoicing app (a dashboard), where there is a sidebar layout showing the list of expenses, and whenever the user clicks on one, it navigates to the expense detail while maintaining the sidebar. While navigating, if there is a new expense added to the list, it would be better to show it in the sidebar accordance to the stale time defined in the /dashboard/expenses/layout.tsx , same for if one of the expense has been updated in the meantime, it would respect the stale time defined in the /dashboard/expenses/[expenseId]/page.tsx file.

This is just a suggestion though, as i think this also could be implemented with parallel routes, if they are their stale time is also configurable, then the layout could stay unchanging between navigation and parallel routes would instead be the go-to way to achieve the behavior defined above.

• Back / forward navigation still uses behavior described, this is not invalidated, similar to bfcache.

I understand this and it does not really bother me, as i've come to see many apps still retain their old information on the bfcache, so this is ok with me.

I am not concerned with this behavior (yet) in my current use-cases, but for some people this could be a no-go, i don't know if and how it would/could be configured.
Maybe giving a way to devs to configure this behavior (to skip or not the bfcache) with a warning in the docs that it could introduce a delay between navigations would be better ?

[jamesisaac]

Hi @timneutkens , many thanks for engaging with the responses here. Apologies if I misinterpreted your question.

I'd argue that for the case described around showing stock in most cases you'd want stale-while-revalidate behavior instead of blocking the page from loading.

Personally I just don't agree with this from a UX perspective. I'm aware of the SWR pattern, and there are some situations where I make use of it, but on the majority of projects/use-cases I work on, I prefer to block the page until fresh data can be shown. Showing a flash of outdated content (or several seconds on a slow connection) before showing the latest, after clicking a link, does more harm than good IMO.

For the cart case you definitely have to tell Next.js "something changed" as it is a user interaction, similar to how you have to do a state update if you're using a state management library or using mutate in useSWR / react-query. You'd either do that through server actions + revalidatePath/revalidateTag or by calling router.refresh().

Sure, with the simplest type of ecommerce website this is no problem. But what if these events causing state to change are not coming from the user directly? What about gamification features (e.g. random discounts / free products / site credit etc coming from server-generated events)? Or social/community features (users reacting/commenting/voting on products, etc)? Or what if something had to be removed from the user's cart because stock ran out? Or even the same user jumping between different devices (mobile app & website)?

You can probably argue away each of these points individually as too niche to worry about, or possible with cache invalidation workarounds, but it just introduces a lot of friction when trying to build more complex/dynamic features with Next.js. As instead of simply being able to opt out of caching and focus on building rich functionality, and worry about optimisation later if the product becomes successful, you end up with a "glitchy" (in terms of data freshness) implementation from day 1 unless significant thought is put into cache invalidation, which wouldn't have been a problem in the first place without the router cache.

Examples have been given in other comments of Facebook & GitHub not showing fresh data immediately... but the vast majority of Next.js users are not building sites to serve that scale of traffic, so should not need to be dealing with all the complications of such aggressive need for caching. I imagine vast majority of dynamic apps people build with Next.js will just have relatively small numbers of users, so performance/caching is not a priority, and the developers will just want it to behave consistently/reliably.

I understand what you mean, but I'm not talking about the central API, you could think of that central API as "the database" you talk to, what do you use to talk to the central API? Likely a SDK, either developed in-house or generated from something like Swagger / GraphQL. The ORM/SDK I was referring to is specifically the functions you're using in your Next.js application to fetch the external API.

Sorry, I don't follow. The Server Components make simple fetch GET requests to the central REST API. Then display this content to users via SSR/RSC. How would the Next.js app know when it's appropriate to call revalidateTag etc if the data has changed in the central system?

Still have Partial Rendering, so only the piece below the common layout is rendered / replaced on the page. For example app/dashboard/layout.tsx will not rerender when navigating between /dashboard/settings and /dashboard/profile.

For the use-case I originally talked about (SSR important for original request, then not really minding how the rest of navigation happens), IMO it would be useful to be able to opt out of this too. Otherwise say if you have representations of the dynamic features (gamification/community etc) in the website header, they can easily become out of sync with the rest of the page.

Back / forward navigation still uses behavior described, this is not invalidated, similar to bfcache.

IMO this is fine, I don't think the typical user has any expectation that back/forward buttons are a request to see new data.

[jamesisaac]

Put it this way: first we built a mobile app in React Native, to communicate with this central REST API. On the client-side, we never had to think about caching once. Everything worked perfectly reliably, the app was very well received, never had a single compliant about looking at loading spinners. Even though the app had quite a large user-base, the back-end was well architected with its own carefully managed layer of caching on hot paths, so performance was never an issue.

The system also had a classic server-rendered website, which also never needed to worry about cache invalidation. I don't think any mainstream server-side framework forces you to add a caching layer, it's always opt-in.

Then we wanted to build a refreshed web interface, and settled on Next.js App Directory as it sounded like the modern way to build a more dynamic "web app" that supports SSR (so that the initial page load would benefit from SEO, accessibility, fast time to first paint, etc). Now we are running into all sorts of issues with data freshness, and to resolve these, being asked to learn the intricacies of a pretty complex caching system and write a lot of code around cache invalidation.

At the moment, we would much prefer to avoid all that by simply opting out of caching, and eat any slower loading times / extra server costs that results in, until that become a priority to tackle, at which point we'd happily switch on the caching system (on hot paths at least) and invest the time into fully understanding and utilising it, keeping up with all the changes, etc.

[Darren120]

router.refresh invalidates the entire tree, when you navigate back to a list, the scroll resets. super bad ux.

[rshaul]

First of all thank you so much Tim and Vercel for taking this topic so seriously. Really appreciate how responsive you guys are to feedback.

I would say "The mutations I trigger" area is thoroughly covered by the tools nextjs provides and is not an area of concern.
Back/forward I think you also want to be pulled from a client side cache and I don't think that is a problem either.

However in the "mutations others trigger" area, if I am writing a dashboard and the sidebar has a link to a list of all products, users have been trained from years of the internet that clicking on the link in the sidebar (or clicking a link to go to a product detail page etc) will get them the absolute most fresh and up to date information available. Currently it seems like it is not possible to get sidebar links to behave like an old school "traditional MPA" even when I think it is being pretty explicitly asked for when the developer puts revalidate = 0 (or "force-dynamic" or whatever) in the page.tsx file. Seems like it would be nice to have <Link> skip the client side cache for any "dynamically rendered" page when the user manually clicks it. With the understanding that back/forward will still use a client side cache.

Edit: Also I think partial rendering is a great idea and I think it would be totally fine for the layouts to not refetch / re-render even on a dynamically rendered page. This would give RSCs a leg up over the traditional MPAs and hey if you really want the layouts to re-render also you can always use <a> tags.

---

As you start moving more components from the Client to the Server you increase the RSC Payload, which you now have to refetch anytime you do anything, like navigating, mutating, etc.

Isn't this the whole point of dynamic rendering and revalidate = 0?

---

Regardless of whatever happens here I will be a happy user of nextjs and RSCs, I have been loving them so far and you guys are doing incredible work. Cheers.

[oljimenez]

question : @oljimenez . When you navigate between issues in github, and there are a new comment within the span of your navigation, what do you expect when you come back to that issue ? To still see stale data or to see the new comment added to that issue ?

If you also navigate between issues and one of the issues has been closed when you navigated away, do you expect to still see the issue as open ? What if the issue has been locked so it doesn't accept new comments, do you still expect to be able to comment to that issue ?

• I would suggest you to browse github issues and you will see that for every navigation there is a browser request to ensure that what you see is always fresh and up to date.

Using websockets when to just see new data is over-engeenering for something the web has done without for a long time. And to use websockets on vercel, you would need to use another 3rd party, you introduce a problem which did not need to be here in the 1st place.

Caching is a hard problem in software engineering for a reason : because it could easily introduce unwanted behavior, and it is preferably used in parsimony.

Yeah, i understand your concern. Is true that go to a already closed issue can be problem, but what's your UX expected on that?. If you can enter a closed issue is meant that you already visit that page less than 30s ago, it would be also bad UX if i visit a issue and then go back/forward and have my history completely broken, maybe even to be redirect to a 404 page or something like that i didn't expected. Maybe the best UX in this kind of problem, is to fetch in intervals, and show a modal or something to reload the page if the issue was closed by example, of course if you try to write you will get an error. Also if you go to the issue from the dashboard passed after 30s, you will be hit by new data and be unable to enter the issue. I don't think i wanna to have back/forward broken if already visit the page 30s ago. GitHub seems don't use client caching at all, maybe some people want that, is true, but also i as a user don't wanna see the 20 loading spinners on github dashboard when i navigate every time, yes, they do that even when i back/forward. This is a issue that can happen to any user if they don't navigate at all, so fetching on everything navigation I don't think that fix the problem, fetch on intervals fix both problems. Yeah, websockets is too much overheat, but some apps have that necessity.

[timneutkens]

Posted a reply to clarify some details / intentions: #54075 (reply in thread)

question : @oljimenez . When you navigate between issues in github, and there are a new comment within the span of your navigation, what do you expect when you come back to that issue ? To still see stale data or to see the new comment added to that issue ?

Here's a fun one: Have you checked what the behavior is on GitHub today?

The behavior is that when you navigate using links you're not going to see the latest comments, GitHub's UI is stale more often than you think as they leverage caching mechanisms similar to the one in Next.js.

[dogsonacid]

Hey Tim,

We have been redeveloping our forum using Next.js as a frontend on top of an existing forum API.

As you can imagine forums need to be very dynamic and almost no cache, for example looking at a stale list of threads if multiple users have posted replies to those threads, it doesn't appear to the user viewing the list of threads that there has been any replies

Currently when we navigate around between forums I am seeing stale lists of threads and also cases within the threads where replies are not fresh (multiple browsers/users scenario)

Prefetch false helped a lot but didn't seem to solve all the client side cache issues.

That's just an example of where we need to have absolute fresh pages.

Thanks

[oduncan]

The behavior is that when you navigate using links you're not going to see the latest comments, GitHub's UI is stale more often than you think as they leverage caching mechanisms similar to the one in Next.js.

To that point, GitHub's UI appears to use some mechanism of polling to show new posts/comments/etc. After your shown a new post and you navigate away, then quickly navigate back via the back button, you will still see that new post.

Based on your explanations @timneutkens, it should be true that we can achieve this behavior by calling revalidatePath/Tag once the client retrieves a new message via polling/some other client mechanism, is that correct?

If so, I think it would solve a lot of issues surrounding this discussion, in our early testing we were not able to achieve this behavior consistently and the 30 second cache was found to be the source of the inconsistent behavior, forcing us back to a client side fetching/caching library. Had we been able to disable or set that to 0 we may have been able to continue using that paradigm while we waited for more clarity on revalidatePath/Tag and getting it working as intended.

[timneutkens]

Based on your explanations @timneutkens, it should be true that we can achieve this behavior by calling revalidatePath/Tag once the client retrieves a new message via polling/some other client mechanism, is that correct?

Yeah, you're right, it could even do polling of a server action in which you check if the data has changed, if it didn't change you don't call revalidatePath, if it changed you call revalidatePath / revalidateTag 👍

[masterbater]

[timneutkens]

Please have a look at this reply: #54075 (reply in thread)

[Fredkiss3]

Hello Tim, Thank you for the deep dive, it really helps put in perspective some of the roadmap and thinking around caching.

While i don't really aggree with most of the reasons, i will give you just my particular usecases which would be suited for a lower stale time and some opinions (of my own) i have for the other related subjects you talked about in the discussion.

---

1st use case : flash messages that should only show once

I have an app where i've implemented the concept of sessions from scratch without using 3rd party libraries, with the objective of having different features within my app, notably : authentication, remembering the user's form entry and flash messages. The last one is very important as flash messages are supposed to clear themself on access so that they show up only one time, as a feedback after a user's action.

In my app i have a register form where the user can sign up, and on submit, it shows them wether the action has been successfull or not as a dismissable alert box, i've used sessions for that because i want it to work without the need of JS as the form is also progressively enhanced with form actions.

The problem is that whenever the user navigate away then back to the page, it still shows them the flash message, even though they navigated away and finished their signup and/or clicked the dismiss button, even though the flash is cleared on access, if the user refresh the browser, they will not see the flash message. Below the video for a better illustration :

Enregistrement.de.l.ecran.2023-08-16.a.01.01.00.mov

The expected behavior is this (JS is disabled in this video), the flash only show once after the user has made an action :

Enregistrement.de.l.ecran.2023-08-16.a.01.07.08.mov

The reason why i wanted to create sessions from scratch is because there is not yet a lib (that i know) that support using sessions within nextjs App Router, the current ones that i found, are either not maintained since 2022 and do not support app router yet.

---

2nd use case : remembering the user's input and showing form errors

I also used sessions in another app to give the user the possibility to submit a form and get progressively enhanced form errors with their last input restored.

The problem is the same : when they navigate back and forth to their form it should only show once as form data & errors are also flashed in the sessions, so they only should show once (this behavior is the same as laravel), but with the client side caching, it shows them the same errors on navigation.

Enregistrement.de.l.ecran.2023-08-16.a.01.11.49.mov

And this is the expected behavior (JS is disabled) :

Enregistrement.de.l.ecran.2023-08-16.a.01.12.32.mov

---

3rd use case : notifications

In the original thread, someone mentionned the case of github notifications, i am in the process of trying to recreate a clone of github in Next App Router and the notifications are one the features i want to implement.

In github when you receive a notification (ex: someone mentionned you in an issue, a new comment has been made on an issue you're subscribed, someone changed the status of the issue you wrote), github will show you a little badge over the notification button in the header, and when you click that button, it navigates you to the notification page where you can see unread notifications.

Let's take the case of how it would work with the router cache of 30s :

• A user receive a notification (someone mentionned them in an issue), the blue badge show up
• They click on it and see new unread notifications (great !), they read the notification and navigate away
• They receive another notification less than 5 seconds later (another issue they're subscribed to has been fixed), the blue badge show up
• They click on it and do not see the the new notification (Not great)

What would the user conclusion would be ? That the app is broken right ?

The user's expectatino is that, if the blue badge show up, they can go to their notifications page and instantly see the new notification, this expectation is broken with this behavior.

Now let's take the case where instead of going to the notification page, the notifications would show up in a dropdwon list and directly link up to the destination (like on vercel) :

• A user is on issue # 123 which they subsribed to
• A user receive a notification (someone mentionned them in issue # 456 ), the blue badge show up
• They navigate to issue # 456 and see the page with the new comment mentionning them (great)
• They receive another notification less than 5 seconds later (issue # 123 has been fixed and is now closed), the blue badge show up
• They navigate to issue # 123 and still see that the issue is open even though they received a notification stating the contrary

Same problem here.

---

My opinions around caching

You said here :

There’s an alternate universe where we could have gone by choosing everything is dynamic by default, this would mean we would always from the root of the application down on navigations.

Why would you need to rerender everything from the root ? why not just rerender dynamic segments on the server with respect to a TTL defined by the user. You do not need to rerender everything, just the sections marked as dynamic, static segments would not need to be refetched. The point of caching is that some data do not change everytime and those data we don't want to recompute everytime, that does not means that we want everything to be cached.

If you had this mode where everything is dynamically rendered and there was no caching and Partial Navigation you always rerender the entire page on the server. That also means that all your components, including 3rd party npm modules, will need to reason about how they stay fast by introducing their own caching mechanism, for example react-tweet would need to write to disk or an external store.

There would not be a need for 3rd party libs to write to disk or an external store, as the caching is only temporary in the client side router, that at least means that the user would hit the fetch to twitter API at most every 30s, which is already a lot. And if the user cannot run JavaScript (for many different reasons) and/or has js disabled while using the app, every navigation to them is a full page navigation which, will hit the twitter API a lot more. Even with JS enabled, let's take the case where your app receives a lot of traffic (1 000 of users for ex), each new user loads your page and for each user you would need to request the twitter API, you can more or less agree that there will be many users accessing your app at the same app, this would be way more than one request per 30s.

The thing is that there is already the data cache preventing the spamming of 3rd party APIs, and there is also static generation & ISR which helps reduce the number of requests sent to 3rd parties. If we take the case of the website like https://dub.sh/ , which uses react-tweet to show their testimonials, they can be assured that the twitter APIs will not be spammed because the homepage is static.

We’re also expecting that in the near future it will be less likely that you have to manually call revalidatePath / revalidateTag, as data fetching solutions like ORMs/SDKs could handle invalidation for you automatically as part of the library when inserting/updating data. E.g. Prisma’s SDK could automatically

// Without integration into the SDK
export async function updateUser(config) {
  "use server"
  await prisma.user.update(config);
  revalidateTag('prisma-user');
}

// With integration into the SDK
// If the SDK called revalidateTag and applied tags instead:
export async function updateUser(config) {
  "use server"
  // Automatically calls `revalidateTag` on your behalf.
  await prisma.user.update(config);
}

This one is odd, unless nextjs directly detects that prisma made a db update (which i really have no idea how it would), prisma SDK cannot automatically invalidate the client side cache, if it did then the library would tie itself strongly to nextjs. Prisma cannot do that as they have to serve much more different users and are used in vastly different contexts which are completely unrelated to nextjs or RSCs. It is the same for the other libraries.

As of now, the ecosystem of RSC is only nextjs, but there will be different RSC framework (and there is already) with support for server actions which would not use the same API for client side revalidations, or provide a router or data cache at all, i suppose those libraries would not want to tie themselves to any framework because of the vastly diverging implementation that could exist outside of nextjs, letting the user do the caching and invalidation by themself is the safe choice; The other side is to create an adapter for each framework, which would break the premise of the RSC ecosystem of using one lib everywhere without any change.

---

Sorry for the long message, but i had a lot to say. I still really like using nextjs App Router, and i would like to continue working with it in future projects, but the reluctance from the next team on this issue is making me second guess my decision to continue using it.

[timneutkens]

Please have a look at this reply: #54075 (reply in thread)

the reluctance from the next team on this issue is making me second guess my decision to continue using it.

I find it unfortunate that you keep dismissing replies we post in trying to remedy the misconceptions people have and trying to find a solution that most people are happy with, as we want to make sure people understand what they're asking for exactly before making changes. Writing this discussion cost all of Thursday (reading all 290 replies individually), all of Friday, all of Monday, and all of Tuesday. I've spent 1,5 week with Delba full time writing the new caching document as well, Delba spent 2 weeks on it.

If that is reluctance to wanting to figure out a solution then I'm not sure why I'm even posting these replies.

[timneutkens]

@Fredkiss3 could you share the code for the first and second example? We'd like to double check how you've implemented it.

[Fredkiss3]

The relevant links for the 1st example are :

1. the flash-message component : one is the server one which loads all the flashes from the session, and the other is to render the UI and click to hide the component.

• https://github.com/Fredkiss3/next-custom-session/blob/ec71c80da059cd3318465389ecbbcf2eb7ba78bc/src/app/(components)/flash-message.tsx#L6

// src/app/(components)/flash-message.tsx
import * as React from "react";
import { getSession } from "~/app/(actions)/auth";

import { FlashMessage } from "./flash-message.client";
export async function FlashMessages() {
  const flashes = await getSession().then((session) => session.getFlash());

  return (
    <>
      {flashes.map((flash) => (
        <FlashMessage key={flash.type} {...flash} />
      ))}
    </>
  );
}

• https://github.com/Fredkiss3/next-custom-session/blob/ec71c80da059cd3318465389ecbbcf2eb7ba78bc/src/app/(components)/flash-message.client.tsx#L6-L27

// src/app/(components)/flash-message.client.tsx

"use client";
import * as React from "react";
import { SessionFlash } from "~/lib/session";
import { clsx } from "~/lib/utils";

export function FlashMessage(props: SessionFlash) {
  const [hidden, setHidden] = React.useState(false);
  return (
    <div
      className={clsx(
        // ... other class Names
        {
          flex: !hidden,
          hidden,
        }
      )}
    >
      <span>{props.message}</span>
      <button onClick={() => setHidden(true)}>
        X
      </button>
    </div>
  );
}

2. There is the code for the session flash, whenever it is accessed, it is deleted automatically :

• https://github.com/Fredkiss3/next-custom-session/blob/ec71c80da059cd3318465389ecbbcf2eb7ba78bc/src/lib/session.ts#L101-L121

// src/lib/session.ts

export class Session {
  /// ...other methods
 public async getFlash() {
    const flashes = this.#_session.flashMessages;

    if (!flashes) {
      return [];
    }

    // delete flashes
    this.#_session.flashMessages = {};
    await Session.#save(this.#_session);

    const flash = Object.entries(flashes).map(
      ([key, value]) =>
        ({
          type: key,
          message: value,
        } as SessionFlash)
    );

    return flash;
  }

}

3. And here is the code for when the register action :

• https://github.com/Fredkiss3/next-custom-session/blob/ec71c80da059cd3318465389ecbbcf2eb7ba78bc/src/app/(actions)/auth.ts#L24-L49

// src/app/(actions)/auth.ts
"use server"
// ...other imports, variables & types

export async function registerUser(formData: FormData) {
  const data = Object.fromEntries(formData);

  const parseResult = registerSchema.safeParse(data);
  const session = await getSession();

  if (parseResult.success) {
    // the code for the DB is commented, but it just does a db.insert
 
    await session.addFlash({
      type: "success",
      message: "Account created successfully, you can now login",
    });
  } else {
    await session.addFlash({
      type: "error",
      message: "Your input is invalid",
    });
  }
  return revalidatePath("/");
}

---

The relevant links for the 2nd example (which is way more complex, because it is a bigger app) are :

1. the session class :

• https://github.com/Fredkiss3/gh-next/blob/8f74c6dd4393b9f96e0be2e42ae4eea0ab5b7c9a/www/src/lib/session.ts#L216-L227

// www/src/app/lib/session.ts
export class Session {
  // ...other methods
  public async getFormData() {
    const data = this.#_session.formData;


    if (!data) {
      return null;
    }


    // delete formData & flashes
    this.#_session.formData = null;
    await Session.#save(this.#_session);
    return data;
  }
}

2. The page used for submissions :

• https://github.com/Fredkiss3/gh-next/blob/b381ea3288961e8148ff836e9232813b93c9ba0c/www/src/app/(routes)/(app)/(settings)/(pages)/settings/account/page.tsx#L24

import * as React from "react";

// components
import { ChangeUsernameForm } from "~/app/(components)/change-username-form";

// utils
import {
  getAuthedUser,
  getSession,
  redirectIfNotAuthed,
} from "~/app/(actions)/auth";

// types
// www/src/app/(routes)/(app)/(settings)/(pages)/settings/account/page.tsx
import type { Metadata } from "next";

export const metadata: Metadata = {
  title: "Account settings",
};

export default async function Page() {
  await redirectIfNotAuthed("/settings/account");

  const user = (await getAuthedUser())!;
  const formData = await getSession().then((s) => s.getFormData()); // <- form data is accessed here
  return (
    <div className="flex flex-col gap-4">
      <section className="flex flex-col gap-4 md:gap-8">
        <h2 className="text-3xl font-medium border-b border-neutral py-2.5">
          Change username
        </h2>

        <p>
          Changing your username means that all the mentions (
          <strong>@{user.username}</strong>) would be lost
        </p>

        <ChangeUsernameForm
          errors={formData?.errors}
          defaultValue={formData?.data?.username?.toString() ?? user.username}
        />
      </section>
    </div>
  );
}

3. The relevant code of the action :

• https://github.com/Fredkiss3/gh-next/blob/b381ea3288961e8148ff836e9232813b93c9ba0c/www/src/app/(actions)/auth.ts#L151-L159

// www/src/app/(actions)/auth.ts
"use server"

// ... other imports & methods

export const updateUserName = withAuth(async function (formData: FormData) {
  const session = await getSession();
  const user = await getAuthedUser();
  const result = updateUserNameSchema.safeParse(formData);

  // This is the code that produces form errors if the user input is invalid
  if (!result.success) {
    await session.addFormData({
      data: {
        username: formData.get("username")?.toString() ?? null,
      },
      errors: result.error.flatten().fieldErrors,
    });
    return revalidatePath(`/settings/account`);
  } 

 // ...the rest of the code is for treating other validation cases 
}

---

For both cases i used manual workarounds with useEffect to do a router.refresh(), what i would want is to not have to do that, both my apps are fully dynamic (and i want it that way), and i mitigate the need for caching by using edge runtime which is fast enough for my use case.

[pkellner]

Please have a look at this reply: #54075 (reply in thread)

the reluctance from the next team on this issue is making me second guess my decision to continue using it.

I find it unfortunate that you keep dismissing replies we post in trying to remedy the misconceptions people have and trying to find a solution that most people are happy with, as we want to make sure people understand what they're asking for exactly before making changes. Writing this discussion cost all of Thursday (reading all 290 replies individually), all of Friday, all of Monday, and all of Tuesday. I've spent 1,5 week with Delba full time writing the new caching document as well, Delba spent 2 weeks on it.

If that is reluctance to wanting to figure out a solution then I'm not sure why I'm even posting these replies.

Thank you Tim for putting so much time into this challenging and important problem.

[osdiab]

When you click / tap around the menu quickly the UX would be jarring when you click on a link, then another, and then back, and see many loading states again.
When you’re on a slow network connection this behavior helps ensure the navigating back/forward using links still feels fast.
It’s also about keeping your place when navigating between router quickly, for example looking something up on another page and then going back to the previous one.

This is all fine and great if you're building Facebook, where seeing a stale version of your news feed isn't a big deal, but not everybody is building Facebook.

What we're looking for at my company, is the flexibility to make those UX decisions for ourselves. In my company's case, having fresh data is more important than avoiding loading spinners on a back navigation. We're a B2B SaaS dealing with business critical data where freshness is key. The frustrating part is that NextJS assumes that all users have the same requirements and that one cache policy works for all apps under the sun; this is simply not the case.

[timneutkens]

Please have a look at #54075 (reply in thread).

How are you currently building dashboards? Are you using useSWR / react-query or using a custom rolled fetching hook? How are you handling mutations? If using those hooks what is the configuration you're using?

[osdiab]

Same team as @haleykoike so his post is basically where we're at: #54075 (reply in thread)

That solution does work, which is what we're doing at the moment via a pnpm patch that just sets it to a very low number, and we're happy enough with that. But even better would be if we had control.

Personally, I think it would make sense if we could export from each layout/path segment a number of seconds cache timing for router cache (and tbh all of the caches would make sense), and have the ability to opt out of it entirely for critical flows. I could guess though that that could get hard to reason about, and there maybe are details I don't understand that might make this complicated to implement—you tell us.

But at least global customization is a must IMO—to be able to globally opt out or set a default caching period for the whole app. If there were flexibility to then opt-in to caching as we want to optimize specific routes, that would make sense, since that's what it is, an optimization. Premature optimization is the root of all evil.

Opting out of it entirely everywhere is a blunt instrument, but it would be our strong preference over the current default/mandate that you have to cache 30s all the time. If Next gave us the power to make intelligent decisions for ourselves (as opposed to just imposing what it thinks is best for us), that would be the ideal.

[haleykoike]

Different applications have different requirements in which case certain UX tradeoffs around caching may or may not be acceptable. The expectation for a framework like NextJS is to give developers the flexibility to configure based on their application's needs and what is or isn't acceptable to their users.

For certain applications, having the ultra fast back/forwards between navigations could be preferable. For others, always fetching the latest up-to-date data and not showing stale data regardless of whether or not the user has navigated within that browser session could be preferable.

Rather than trying to force developers to implement workarounds to the client router cache like using a useEffect hook for stale-while-revalidate, or moving all fetching to client components, why not just let developers configure and/or opt-out of the client router cache if that is more suited to their application's needs?

NextJS has already added the options to configure or fully opt-out of the data cache, request memoization, and the full route cache, so why why not just do the same for the client router cache? To draw the line in the sand that you must have the client router cache and that it must be 30 seconds because Facebook has prior research that 30 seconds is a good number for Facebook doesn't make any sense.

[haleykoike]

Before RSC, 95% of data fetching was done client side with Apollo and we basically didn't leverage SSR on most routes. For certain routes where SSR was important, we used getServerSideProps. Any parts of the application that show mission critical user data were configured to opt-out of Apollo's cache or to use getServerSideProps. This way we could ensure that no matter how the user navigated to the route or forward/back to the route they would never be served with stale data.

I understand the UX tradeoff with losing scroll position, but for our users the most important thing for UX is to always show them fresh data. It's much more detrimental for them to see stale data that they perceive to be wrong than to wait for an extra loading spinner, or to need to scroll back to their position. So with that in mind, our preference would be to be able to opt out of all of NextJS's caching mechanisms, and then progressively enable caching to improve other parts of the UX.

[oduncan]

@timneutkens I apologize for giving more of a general perspective and not directly answering the question, we have been using a lot of nextjs!! so the passion for getting this right is palpable, forgive me.

The root of our problem was largely related to bugs if I understand your post correctly, and should be resolved as those problems seem to have been addressed as you stated here:

In the thread there was a lot of confusion around this as there were a few bugs in the implementation, which have been fixed in the latest version of Next.js. (E.g. it didn’t purge the cache used for back/forward, only prefetches, so stale data would be possible, this is no longer the case but wanted to highlight that).

Reliably being able to control when a path is stale and seeing behavior that respects that invalidation would have completely resolved this issue for my previous use case, so in that case setting the cache to 0 would not have solved that problem. However, being able to control or disable the cache in certain segments of the route tree would allow my team to enforce best practice/recommended caching intervals whenever possible and avoid complications when in areas of the app where it's not as important.

The pattern I'm looking for is simply:

1. Query data, load a list
2. add an item to the list via mutation (not just server actions but even client mutation)
3. once the mutation is complete, revalidate (tell the server the list is no longer valid)
4. navigate away
5. press the back button
6. see list with new item added in step 2.

The reason I specify "not just via server action" is that it shouldn't be relevant, I should be able to reliably invalidate any fetched data programmatically, regardless of how I mutate the data. My focus is almost exclusively on "mutations I trigger" because I believe it's foundational. If I can reliably invalidate the cache, I can then set up another layer using websockets or polling to listen for "mutations others trigger" and use that client event/response to keep my page data fresh and my cache aware that this query no longer valid, (at any point I can navigate away, press back and see fresh data).

If I can't reliably invalidate the cache, I would need to be able to disable the router cache or set it to 0. I hope that makes sense, it's hard to give a yes or no answer but I think its only so complicated because the bugs and lack of consistently made it feel like disabling the cache was the only solution.

Clearly, most developers would want to take advantage of clever caching and would strive toward a working solution that took advantage of such mechanisms. However, I still think it should be an option for those that don't have the ability to get it working as expected or just don't want to subscribe to that feature set.

[timneutkens]

@oduncan no worries, seems you missed a section of the explanation post. It's totally possible to do what you're explaining, the API for when you do mutations that are not server actions is calling router.refresh(), that invalidates all caches including back/forward.

Here's the specific section:

The main thing to keep in mind with this behavior is that the client-side Component Cache that is used when navigating back/forward is only purged when you call one of the purging functions (router.refresh(), revalidatePath, revalidateTag).

If in step 3 you call router.refresh() then step 4 / 5 / 6 would correctly show the result.

Thanks for writing up the exact case as this allows us to verify if the thing being asked for is actually the solution needed, as in this case you'd just want to invalidate the router cache on interaction.

[nicwcampbell]

@timneutkens what if you wanted to do the following steps:

1. Query data, load a list
2. Navigate to a new page with a form to add a new record to the query data list on the previous screen
3. Save the record to the the database via a client side POST to a separate backend (i.e. not using a Server Action)
4. Use router.push() to use the id returned by the POST to navigate to the record I just created in order to get the latest details and the URL reflecting that id
5. When the user clicks a back button then navigate back to the previous list screen and see the new record

So basically I need to use router.refresh() at some point. I would have added it before or after 4 but when I do that, it doesn't run as I think the router.push is overwriting it? Is there not a way to make these synchronous or async and then I can await the router.refresh().

A better way may be to use a Server Action to do the POST and then invalidate this path and thus the page would refresh - but I am not sure how to get the Id into the route in this way, so maybe then I would need to do a redirect, but then it doesn't seem any more efficient than just doing a client-side POST? Maybe you can explain?

But I'd also still like to know a best practice to be able to use router.refres() and router.push together to that I can navigate to a fresh page - maybe there should be another option such as router.pushAndRefresh so that it will refetch that page - and ONLY that page.

[ztanner]

@nicwcampbell are you revalidating the data (via revalidatePath or revalidateTag) associated with your write? If so, I'd have expected navigating back to trigger the revalidated data to be re-fetched. If that's not the case, can you share a minimal reproduction?

[ttsirkia]

With this additional context and explanation of the internals, how to handle mutations, how to get fresh data using the stale-while-revalidate pattern, and the bugfix, does this make sense or do you still have a case that is not covered. When you could configure the time to be zero instead of 30 would that solve a case you’re running into even though that wouldn’t affect back navigation and such?

Thank you for this posting. I think that this concludes the issue pretty well. The biggest question remains: why this is the only cache the developer cannot fully control and adjust the caching time to be 0, 5, 30 or maybe even 120 seconds if that suits best the application. There is not a single correct value for this and lots on many very good use cases are discussed here already as well as in the original issue.

At least I got a feeling that this behavior is not going to change and I expected that there would have been already clear suggestion how this behavior is going to change. Now we need to continue discussing the problem and its consequences instead of discussing a RFC for the (in my opinion) required changes for the logic.

[ttsirkia]

And as @timneutkens has written, most likely this kind of configuration will be possible in the future but this particular discussion thread did not have any RFC how the code for that would look like.

[Phoenixmatrix]

react-query / useSWR keep the stale data visible on back navigation,

Asterisk there. tanstack react query lets you manipulate the cache, and its pretty common to update the cache directly after a mutation, so when you navigate after a mutation, there's no flicker of stale data. The manually updated cache shows up, and then react query re-fetch the data from the server to update it (usually updating temporary client side generated ids with the ones created on the server, but that's not visible to the user).

[masterbater]

What react-query does is almost 1:1 exactly the same as the component I shared in the initial post, it just calls the fetcher to get new data and that is then re-rendered. Now replace the word fetcher with router.refresh() and it's the same thing. Think of router.refresh() as the way to trigger a new render. react-query / useSWR keep the stale data visible on back navigation, that's what this does too.

If I do isFetching and use that as loading animation it will at least not make user show data stale.

Does router.refresh() also trigger loading.ts?

[timneutkens]

Asterisk there. tanstack react query lets you manipulate the cache, and its pretty common to update the cache directly after a mutation, so when you navigate after a mutation, there's no flicker of stale data. The manually updated cache shows up, and then react query re-fetch the data from the server to update it (usually updating temporary client side generated ids with the ones created on the server, but that's not visible to the user).

I'm saying if this is what you're used to you're not that far off from getting that.
mutate() in Next.js if you're not using Server Actions is router.refresh(), this clear the back/forward cache too, which is explained in my post:

The main thing to keep in mind with this behavior is that the client-side Component Cache that is used when navigating back/forward is only purged when you call one of the purging functions (router.refresh(), revalidatePath, revalidateTag).

Then for the back/forward navigation / focus case you add the component I shared in the initial deepdive post and you have the same behavior. That is not a hack or workaround, it's very similar to what useSWR does, only difference is that you pass it as a prop to a predefined component instead of using your own component.

If I do isFetching and use that as loading animation it will at least not make user show data stale.
Does router.refresh() also trigger loading.ts?

It would trigger Suspense boundaries where the key doesn't match up with the current page you're looking at, so you'll want to do something like <Suspense fallback={<>loading...</>} key={somethingThatChanges}>.

[masterbater]

Asterisk there. tanstack react query lets you manipulate the cache, and its pretty common to update the cache directly after a mutation, so when you navigate after a mutation, there's no flicker of stale data. The manually updated cache shows up, and then react query re-fetch the data from the server to update it (usually updating temporary client side generated ids with the ones created on the server, but that's not visible to the user).

I'm saying if this is what you're used to you're not that far off from getting that.
mutate() in Next.js if you're not using Server Actions is router.refresh(), this clear the back/forward cache too, which is explained in my post:

The main thing to keep in mind with this behavior is that the client-side Component Cache that is used when navigating back/forward is only purged when you call one of the purging functions (router.refresh(), revalidatePath, revalidateTag).

Then for the back/forward navigation / focus case you add the component I shared in the initial deepdive post and you have the same behavior. That is not a hack or workaround, it's very similar to what useSWR does, only difference is that you pass it as a prop to a predefined component instead of using your own component.

If I do isFetching and use that as loading animation it will at least not make user show data stale.
Does router.refresh() also trigger loading.ts?

It would trigger Suspense boundaries where the key doesn't match up with the current page you're looking at, so you'll want to do something like <Suspense fallback={<>loading...</>} key={somethingThatChanges}>.

Thanks for the effort in replying to each of our question. Most issues encounter probably is the caching we are not used to and how to deal with that, app router is still new and server actions is still in alpha. Last time I check revalidatePath/revalidateTag
is only server actions which is alpha, I read now in docs you can also do it in route handler, probably its there before and I missed that.

Probably its more productive to make people show whats the issue with their app router project then nextjs team will put up an example to solve it. Just only the most common issues or patterns and how to deal with it not spoon feeding everything. @timneutkens thanks for always and being patient on answering all our queries and educating us with RSC and app router in general. As you can see there is a lot of interest with app router and we love nextjs and the team who made it hoping for the best so we can use it without any problems.

[p00000001]

I currently work on an event listings website and two issues where a stale cache impacts us is:

1. The user "saves" an event to their wishlist and the heart icon then displays next to the event everywhere on the website. revalidatePath([segment]) on a specific segment would not work for us as the heart is shown on many different pages that list the event. revalidatePath('/') or router.refresh() would empty the entire cache, but it seems overly aggressive to have to re-render our layout and call its APIs each time, which are some of our most timely and expensive.

2. The event content is updated in an external CMS - presently no way to overcome this with the 30s client router cache other than to wait

Configurable Time

When you could configure the time to be zero instead of 30 would that solve a case you’re running into even though that wouldn’t affect back navigation and such? Let me know!

Yes! That would solve both issues for us.

To echo some other comments, if this configuration is going to be added, it may be worthwhile making it an arbitrary number for users who want caching durations longer or shorter than 30s.

For a simple/quickest solution, if we could just configure the default router cache time on a global level to start, then that would be a big win. In the longer-term, localised options to configure the cache time per page/segment would be a advantageous to optimize different routes where needed e.g. "check out" vs "about us" pages could have different cache settings.

Time Calculation

I noticed there is a bug in the current behavior where every subsequent navigation to the page before the 30 seconds has passed increases the time by another 30 seconds. This is a bug and we’re going to change it to 30 seconds since navigating away from the page, so if you navigate to /account then wait 10 seconds and navigate back to /products it would not increase the time by another 30 seconds. Instead, the cache node would be purged after another 20 seconds (as we clicked back after 10 seconds).

Whilst not a major concern, I don't really understand why the stale time is calculated based on when the user first navigated away from the page, rather than when the data was first retrieved. For example, If the user leaves the browser page open and goes out to lunch for an hour, they could come back and do a navigation to and from the page and still see data over an hour old? I appreciate the use-case is more niche, but would it not be more consistent to base the stale time on when the data was retrieved so the developer can be more confident they'll never be showing pages more than "x" seconds old?

Stale-White-Revalidate Option

I also think a really nice feature would be an additional option to leverage stale-while-revalidate in the router cache so we can still benefit from the speed of the cache and the browser native scroll position, whilst ensuring fresh data.

This could be useful for data that is important but not mission critical if it takes a second to refresh, such as our "saved" events and e-commerce product "availability" etc. So when a user navigates to a page either through a link or browser buttons:

- If router cache expired (can set arbitrary number) - show stale data immediately, retrieve latest segment data from server, update the segment in the background with a type of router.refresh([segment]) using the new returned data

- If router cache not expired - retrieve from router cache only

At the moment, whilst we can use a router.refresh(), this function reloads the entire tree including layouts from the root so is too aggressive, it invalidates all the other router cache so won't work for future navigations, plus we'd also have to implement some sort of bespoke checks on every page to identify if the page was fresh from the server, otherwise we'd end up calling router.refresh() even on fresh data because we don't know if it's old or new.

[jmurty]

Hi Tim,

Thanks very much for the time and effort you and the team have put into this write-up and discussion, and for listening to our feedback. I really appreciate it!

Looking at the mutations others trigger situation, I think I understand how everything fits together – there's certainly a lot to digest – but to me, although the recommended approaches to ensure fresh content would work they seem a bit inelegant and error-prone to use.

The options seem to be:

• trigger a router.refresh() with some extra client-side code. Aside from requiring more fiddly code to manage client-side, this is an aggressive purge that clears all the router caches, not just the content specific to the page you're on, so feels excessive.

• trigger a server action that calls (directly or indirectly) revalidatePath(), revalidateTag(), cookies().set() or similar, which as a side-effect triggers a full purge on the client like router.refresh(). This leaves us with the excessive client-side purge for now, though this may become more fine-grained in the future for revalidatePath().
  Of these the cookies().set() seems the most attractive, even in situations where a cookie isn't really needed, since the revalidate calls are metered when deployed to Vercel and could lead to overage fees, or just stop working for people on free plans.

• use a potential future feature to configure the Router Cache for dynamic content (not static or prefetched) to be some value other than 30 seconds, including zero seconds.

Configuring the client side cache timeout would almost certainly avoid over-caching in most situations, including the ones I care about. However it isn't yet clear how fine-grained the configuration control would be, and the level of control might determine whether or not it solves everyone's problems. For example, we would like to have minimal caching for some pages – the user's time-limited cart, pages with availability counts for high-demand tickets, etc – but have longer-lived caching of most of our other content pages.

What I am not clear on is why most the discussion is focussed on clearing content from the client-side cache, in often fiddly ways, instead of avoiding caching the dynamic content in the first place?

The approach that would make most sense to me, is for content from pages explicitly marked as dynamic to skip the cache altogether – or to be cached only for back / forward navigation, similar to browsers. In other words, when receiving content from dynamic RSCs the client-side cache could act like it has a 0 seconds cache timeout.

Avoiding caching of dynamic content does degrade the user experience in some ways, granted, but for pages where timely data is vital I think this is the behaviour we are trying to opt into when we explicitly add export const dynamic = ‘force-dynamic' or const revalidate = 0 etc to our pages. Plus if the client-side Router Cache respected these existing directives, there wouldn't be any need for new router cache configuration options, or to choose a specific timeout value other than 30 seconds.

For us, having dynamic pages trigger 0 seconds client-side caching behaviour would meet our needs and keep things relatively simple.

[leerob]

When you revalidate a page, for example, some compute runs (a Vercel Function) to generate the new page.

[Fredkiss3]

Isn't it the same compute used to serve your app, is it ?

If it isn't and is billed separately from that compute (serving your app), then does it also get executed when you call revalidatePath on a dynamic route (with revalidate = 0) ?

[timneutkens]

To clarify:

• There will be no limit on how often you call revalidatePath / revalidateTag on Vercel and you won't be charged for the act of calling revalidatePath/revalidateTag.
  • Similar to how there is no limit on amount of dynamic renders.
• Calling a Server Action uses compute, same as requesting a Route Handler / Dynamic rendering.
  • When you call revalidatePath / revalidateTag in the Server Action it will render the new result in the same request.

[mbeaudru]

Thanks for the clarification, discussions around revalidate pricing were a bit misleading in the original issue 👌

[timneutkens]

The confusion made sense, there was some documentation mentioning limits in the Vercel docs but as far as I understood (wasn't involved myself) these limits were mostly to ensure individual users wouldn't overload the data cache service when it was introduced as beta, as it was expected to be used a lot. It's further along now where the specific limit was lifted 👍

[viniciusbitt]

For my use case and if it is possible to be done, it would be to invalidate the client-side cache
including the back-forward after called revalidatePath/revalidateTag, all pages/layouts/routes that are in the path or in the tags are invalidated, and this function is not exclusively for Server Actions, as not all people will want to use this feature.

Example:

/product/[productId]/page.tsx:

unstable_cache(() => { /* fetch from database... */ }, [tag], {
  tags: [tag],
});

/api/product/info/route.ts:

revalidatePath(`/product/${productId}`)
revalidateTag(tag)

I think its partially implemented in .next/cache/fetch-cache/tags-manifest.json it seems to save the path of the page which contains the tag.

But while that can't be done, I'm in favor of having the 30 seconds configurable.

[mspangl5]

I would also like this. In our app, it is using a CMS and allows for editing the CMS content while on the site (in an edit mode). When a user does this, it uses server actions and correctly refreshes the data. But when CMS content is changed directly in the database, Supabase has a hook that calls an API that uses revalidateTag to clear the server-side cache but the client-side router cache still stays and causes problems.

[timneutkens]

Before reading this proposal please read the initial post of this discussion to ensure you have the context.

Proposal

Introducing a new property called staletime that can be set on layout.tsx or page.tsx.

Defaults

The default the value for staletime:

• For layout.tsx: Infinity
• For page.tsx: 30 (dynamic rendering) or 300 (5 minutes, static rendering)

These defaults mirror todays default values.

When navigating the router still finds the common layout between two routes, however, while checking that it also checks the staletime of each layout. If the set staletime has passed that level will be used to render from instead, causing the navigation to render below the expired layout, instead of below the common layout.

If the staletime has not expired you get the same behavior as today, where the previous rendered components are reused.

Example

An example:

• The directory tree:
  • app/layout.tsx (root layout) — Doesn’t specify a staletime
  • app/dashboard/layout.tsx (dashboard layout) — Specifies a staletime of 300 (5 minutes)
  • app/dashboard/page.tsx (dashboard page) — Specifies staletime of 0
  • app/dashboard/settings/page.tsx (settings page) — Doesn’t specify staletime and uses dynamic rendering (so it defaults to 30)
• The navigation sequence:
  • I open /dashboard, it shows me a list of items
  • I click on a link to /settings, it shows me the settings page
  • Someone adds an item
  • I click on a link to /dashboard, it renders below app/dashboard/layout.tsx because the 5 minutes have not passed yet.
    • Had I waited 5 minutes before navigating it would have rendered below app/layout.tsx instead because of the specified 5 minutes staletime in app/dashboard/layout.tsx.
    • app/layout.tsx is never re-rendered unless there is a Server Action that calls revalidatePath / revalidateTag or you call router.refresh() as those always render from the root down.
  • I now see the newly added item, the navigation would trigger loading while the hole hasn’t been filled in yet.

The main difference between setting staletime and the current behavior is where you’re setting the timing and how that affects the rest of the tree below it. For example if the current 30 seconds behavior was set to 0 seconds it would never re-render the common layout between two pages, as that timing would still be somewhat equivalent of Infinity.

Back/Forward Navigation

Back/forward navigation will still preserve the cache, it does not invalidate this cache in order to mirror bfcache, based on the replies most folks said this is fine.

What I’m expecting is that others might want to do an update on back navigation based on expiring of staletime too, so Sebastian and I discussed potentially having a way to do the stale-while-revalidate pattern built-in for back navigations. The current default is still preferable for most applications though as it ensures scroll position is always where you were before, instead of feeling broken as items shift around on the page, so we’ll have to figure out if this is something we’d want to have on back navigation and how to opt-in to that, overall it’s not a blocker for adding staletime in my opinion based on most replies saying the current behavior for back/forward is fine.

Conclusion

We still believe the current defaults are correct and bring the experience closer to the current generation of data fetching libraries like useSWR / react-query / Apollo while allowing you to do server-side data fetching.

In reading the replies on the issue and this discussion there seems to be a general consensus that that the defaults are correct but that for certain types of applications in order to iterate quicker you want to opt out of them in order to ship an already better experience (compared to Pages Router) and then optimize from there, which we understand.

There’s more work to be done to show what we think would be the ideal UX for most applications We’ll share those patterns as much as possible, the focus / polling component shared in the discussion post actually came out of the Vercel codebase.

It’s still early days with React Server Components and not all patterns have been as thoroughly documented compared to data fetching libraries that have been around for years. I’m expecting there will be new patterns here as well.

For example something Sebastian pointed out to me yesterday is that you can build a more efficient polling system using Server Actions by using the Server Action to decide if the page should be rerendered with new data. Something like this:

import { revalidateTag } from 'next/cache'

// timestamp is provided from the client in order to query if there have been updates or not
function pollingHandler(timestamp: number) {
   "use server";
   // example of querying the database just for the count of items added since the timestamp
   const currentTimestamp = Date.now()
   const count = prisma.todoTransactions.count({
	    where: {
	      date: {
			lte: new Date(currentTimestamp).toISOString()
	        gte: new Date(timestamp).toISOString(),
	      },
	    },
	  })
    // Only rerender when there is new data since the page was loaded, based on the timestamp.
    if(count > 0) {
      revalidateTag('todos')
    }

		// Return the new timestamp so that it can be passed back to this Server Action on subsequent calls,
		// as you know that up till this point the values were handled.
		// This is to ensure that after you rerender the page every poll
		// doesn't cause another re-render because of the timestamp being outdated.
    return currentTimestamp
}

// Then you set up a Client Component that polls / focus calling `pollingHandler()` and it'll only re-render the page when there is new data.

Let me know what you think! Based on the cases described in the replies to this discussion this new configuration would solve the issue 🙏

PS: The replies on this discussion have been super helpful in highlighting where the gaps in documentation and examples are, we’ll work on explaining those gaps and providing examples for how we’re expecting some of the common patterns shared in this discussion to work.

I’d like to thank everyone that got involved on this issue, I know it has taken some time but that was mostly because we wanted to make sure any changes actually covered the case folks posted, in posting this discussion with the more thorough explanation of the individual pieces the replies were a lot more constructive. Thanks for bearing with me and the rest of the team.

[timneutkens]

@karlhorky We're still working on stability and performance. No update on this currently. unstable_noStore is the same as calling e.g. headers / cookies but without having a specific return value.

[jrnxf]

@timneutkens is there any update on this / when there is can you message in this thread to let us know? I've been checking back here every few days to see.

[ttsirkia]

I would like to ask the same as above, what is the current implementation status of this suggestion @timneutkens ? There has been now better documentation published, videos etc. but this original problem still remains that the 30-second value cannot be configured.

[feedthejim]

We're looking into this, should come around next month, potentially sooner if you're on canary!

[karlhorky]

Looks like this has been implemented and is being documented now 🙌

#54075 (comment)

[williamlmao]

Hi @timneutkens ,

Thanks for the write up. This does help clear some things up, but one thing I'm still quite confused about is how to add revalidation tags on non-fetch functions. Say I'm using Prisma or Drizzle to query my DB inside of a server component. How do I add revalidation tags to that?

[joeleonard212]

Hello @Fredkiss3 thanks for the reply. So the cache-key parameter allows me to invalidate all the tags at once ? Are you using tags in fetch or unstable_cache ?

[Fredkiss3]

For unstable_cache I set both key_parts & tags to the same value and It works fine. But I don't really know what the second parameter of that function is.

Something like :

unstable_cache(callback, tags, {tags});

[eric-burel]

@timneutkens this specific example really puzzles me, sorry if it has been answered before but: what is the official approach to invalidating a specific dynamic segment? Say the segment is /blog/[article-slug]

•  revalidatePath("/blog/next-is-cool") doesn't work, we should instead use /blog/"[article-slug]". This marks all articles as stale so we do not want that if we have many articles.
• so revalidateTag can be preferred, as mentioned here it's expected to be available in unstable_cache and not just fetch call. Is creating a tag specific to each page the way to go?
• or perhaps this is not something that is expected to be doable in Next?
• there might be difference between dynamic and static/incremental scenarios that I do not yet fully grasp, more explanations around that could help

[timneutkens]

revalidatePath("/blog/next-is-cool") doesn't work

This just wasn't implemented yet, was on our todo list. #53321 implemented it and the docs are being updated here: #55083.
It's pending a release but already out on canary 👍

[psteinroe]

@timneutkens related to the request above, do you plan to add a few apis that allow users to do more fine-grained cache updated? I did a write-up here: #50043

the 13.4 release blogpost introduced a revalidateTag API, which allows resetting the cache for a given tag. I am hereby requesting an API, that returns all existing cache keys.

The motivation is quite simple: For sophisticated cache revalidation strategies, it is impossible to know what cache keys should be revalidated without actually knowing which exists. As an example, you might query all posts from a post table in one component, and the details of one post in another. The cache tags would then contain the post table, and, for the latter, the id of the post, e.g. ["post", "id=123"]. Or, ["post?id=123"]. When I update one post within a server action, I can only revalidate both queries with revalidateTag('post'). For larger apps, this leads to a lot of unnecessary revalidation.

To enable more sophisticated revalidation strategies, we would need at least one of:

getAllCachedQueries() to return all active cached queries with their tags (returns an array of arrays, with one array of tags for each query)
getAllCacheTags() to return all active cache tags
To further improve the DX:

revalidateTags(["post"]) to revalidate a set of tags.
revalidateQueries(["post", "id=123"]) to revalidate all queries that have all of the passed cache tags. In this example, only the detail query would be revalidated.

[acomanescu]

Can we have a router.clearCache() that will only clear the router cache? Or a router.push('/', { clearCache: true }) alternative? I have some specific use cases where router.refresh() is not a valid solution because it reloads the current page when I need to navigate to a different one after cache invalidation.

[acomanescu]

Hi @Fredkiss3, thanks for the tip! As far as I know (I might be wrong), but router actions are async, so isn't there the change for current page reload to be executed after the push call and cancel the push?

[Fredkiss3]

the call itself isn't async (you can inspect the return type of router.refresh or router.push).
And normally startTransition should ensure the respect of the ordering of operations.

[acomanescu]

@Fredkiss3 Yes, the return type is not a Promise, but internally they do work async:

 push: (href, options = {}) => {
  startTransition(() => {
    navigate(
      href,
      'push',
      Boolean(options.forceOptimisticNavigation),
      options.scroll ?? true
    )
  })
},
refresh: () => {
  startTransition(() => {
    dispatch({
      type: ACTION_REFRESH,
      cache: createEmptyCacheNode(),
      mutable: {},
      origin: window.location.origin,
    })
  })
},

Maybe it works because they are already wrapped with startTransition internally. I'm not sure how it works when nesting transitions.

[Fredkiss3]

then no need to wrap them inside transitions again. When using useTransition, it ensures only the last transition state updates are applied, so calling router.refresh before will execute both but only router.push will update the screen.

This is my understanding, but it may be different, so you can test to see.

[cpeaustriajc]

I think pr #62856 will solve the router cache problem. I took a look at it and if this PR gets merged, you can configure the client router cache. Still WIP and experimental though, but I hope the dx will get better if this gets successfully merged and stabilized!

[RafalFilipek]

Not entirely.

This also doesn't change back/forward caching behavior to ensure things like scroll restoration etc still work nicely.

[devajakamerus]

I just patch the constants like THIRTY_SECONDS, I don't see a problem in it since it's only referenced in one line anyway. It seems there are some non-techical reasons why such trivial change would take months. Back/forward issue is something that I can live with...

I understand framework authors have their view how things should work but ignoring the actual needs from developers is not very pragmatic.

[karlhorky]

Looks like thanks to @ztanner, configuration of experimental.staleTimes.dynamic (default 30s) and experimental.staleTimes.static (default 5m) are now available in [email protected] 🎉

next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    staleTimes: {
      dynamic: 30,
      static: 180,
    },
  },
}

module.exports = nextConfig

Source: https://github.com/vercel/next.js/pull/64040/files#diff-b23477d2c11d3ddbba50c39cdace0690017ba9f44213efdaf11c1c44f0670fc1

• Feature PR: add experimental client router cache config #62856
• Docs PR: docs: add experimental staleTimes resource #64040

[karlhorky]

Via click on a link, I added that detail above now.

[ztanner]

A good way to check if it's behaving properly on the client is to see if you're seeing new RSC requests (the ones with ?_rsc in the URL) every time you navigate the animals dashboard page and other tabs. I could try to help a bit more if you have a link to where I can repro or a Replay with sourcemaps enabled.

[karlhorky]

I could try to help a bit more if you have a link to where I can repro

Nice, thanks! I added repo links to my comment above. Note: The main branch of that repo isn't on canary and does not have the experimental configuration.

Setup steps:

1. Set up the PostgreSQL database following steps in the readme
2. Run the migrations with pnpm migrate up
3. Upgrade to latest canary
4. Add the experimental config

[ztanner]

I see what's happening, and it has to do with the initial seeding of the prefetch cache (for the page that you first load). I'll PR a fix for it tomorrow :)

[ztanner]

if you'd like to track:

• ensure seeded prefetch entry is renewed after expiry #64175

(and thank you for catching this!!)

[bozzhik]

Hi, I also have a caching problem in my project. could you please help me with a better solution than the one I solved it through.

Project description:

Web site for sanatorium, Next JS + Sanity CMS.

Project repository:

https://github.com/mbozhik/udelnaya

What was my problem?

Locally running project:

When adding new data via Sanity Studio, it did not display, even on reboot and even after some time had passed. Only when combining the keys Ctrl+Shift+R (reboot with cache refresh, I guess) they appeared on the site.

Deployed on Vercel:

When adding new data through Sanity Studio, they did not appear, even when reloading and even after some time. Ctrl+Shift+R shortcut didn't help either, the data was cached intentionally. Such options to change the caching type as revalidate = 0, force-dynamic and <Link prefetch={false} ... did not help either, the data appeared only when redeploying to Vercel.

Commit that solved my cache problem:

mbozhik/udelnaya@75783a8

This is currently the only solution I have found to solve the caching issue when retrieving data from Sanity CMS:

import {unstable_noStore as noStore} from 'next/cache'

...

const getData = async (slug) => {
  noStore()

  const query = `
    *[_type == 'program' && slug.current == '${slug}'][0] {
        name,
        ...
    }`
  const data = await client.fetch(query)
  return data
}

...

i added unstable function noCache() to no cache data in Next js project, here is Lee Robinson on Vercel channel explains this: https://youtu.be/VBlSe8tvg4U&t=423

Tell me how I can achieve the same result without using unstable features and utilities

I apologize for my probably bad English

[jmurty]

Hi, for the Sanity CMS specifically, you should be able to do this in a cleaner way by passing cache revalidation options to the Sanity client since Sanity's client uses the cache-supporting React/Next.js fetch version behind the scenes.

Specifically, you can pass caching options when calling fetch like this:

const data = await client.fetch(
    query,
    undefined, // Query parameters, not needed
    // Caching directives
    {
        // Never cache results
    	cache: "no-store",
        // Alternatively, cache results in Next.js Data Store for 60 seconds
    	// next: { revalidate: 60 },
    })

As suggested at the bottom of the Sanity documentation section I linked above, where it's easy to miss, you should add the logging.fetches setting to your Next.js config file to see log messages about how the fetch implementation is or is not caching data. This is what I do:

// In next.config.js 
logging: {
    // Comment in to enable verbose logging of `fetch` calls, especially cache
    // HIT/SKIP status to help debug Next.js over-caching issues
    // Use `fullUrl: false` to avoid showing overly-long URLs with complete Sanity GROQ queries
    fetches: { fullUrl: false },
},

Please try this or similar and follow up here with your findings.

I think this will work, but I have had a lot of trouble with caching configs in the past and I have not tested exactly this approach yet in production Vercel deployments. So feedback about whether this works or not with the latest Next.js would be valuable.

Thanks.

[jmurty]

I should add that I am confused about why the standard Next.js app router layout/page caching config options like export const dynamic = "force-static"; etc do not seem to apply to the indirect fetch calls like made by the Sanity CMS client.

After a lot of time reading through this and similar GitHub issues, the Next.js documentation, and experimenting directly, I still don't have a clear enough mental model to understand exactly what is happening, or even what should happen.

I believe that the Sanity CMS client fetch calls should "inherit" and apply the Next.js cache directives set at the layout or page level when fetching content for a page. But I haven't been able to get it to do this.

Perhaps that's a bug in the next-sanity library, or in the way I'm using it, or in my understanding of how this is all supposed to work?

What I saw the last time I tried (and failed) to figure this out was:

• Sanity CMS client calls performed when generating a page do not respect the layout/page export const revalidate directive, and do not cache any content
• Sanity CMS client calls performed through a server action, triggered by client-side interaction, always cache content and never return updated data. In this situation I have also had to use the noStore() hack you mentioned, but am planning to switch to the cache: "no-store" client option instead.

[bozzhik]

Hey, I've been busy for a while. Now I've sat down to figure out how NEXT.js works with data from Sanity CMS
The option you presented seems to be more stable, but it also implies no store data, which can get expensive due to API calls.

here's the solution I found:

https://www.npmjs.com/package/next-sanity#time-based-revalidation

here's the commit that solved my problem, but already in other repo

COMMIT: remake fetch call for Sanity data using time-based revalidation (bozzhik/portfolio)

async function getData(): Promise<Project[]> {
  const data = await client.fetch<Project>(
    `*[_type == 'project'] {
       name,
       ...
    }`,
    {},
    {
      next: {
        revalidate: 30,
      },
    },
  )
  return Array.isArray(data) ? data : []
}

[rustunooldu]

Has anyone had success with the new staleTimes feature? I have tried disabling router cache by setting both experimental.staleTimes.dynamic and experimental.staleTimes.static to 0, but nothing seems to have changed and I'm still seeing stale data. Here is my use case:

Main layout has header with 2 navigation links: "/products" and "/likes".

1. Navigate to likes page, 2 products are shown.
2. Navigate to products page (via Link click in header). Click "like product", which makes a fetch() call to a route handler that adds the new liked product to db.
3. Navigate to likes page again (via Link click in header), still 2 products are shown. (refreshing the page or using regular anchor tags rather than <Link> works as expected and page shows 3 products)

Both are dynamic pages, and all fetch calls are tagged with no-store so nothing is coming from the data cache.
Am I doing something wrong here? Is this happening because products page is mutating another page's contents with an api call, rather than server action etc?

[iamjohnlong]

I briefly tried this with both dynamic and static set to 0 with a Math.random() in the dom and it seem to only work after running a build and starting next start. Not sure if the intension was to only have it work in prod? Trying building and next start to see if it's working as intended.

[rustunooldu]

That actually worked, thanks for the tip.

@ztanner is this intended?

[ztanner]

Hey @rustunooldu -- this looks like a bug specific to when you've set both static and dynamic to 0.

I'd recommend only setting dynamic to 0, or if you do intend to disable static as well, then consider also setting prefetch={false} on all of your links, as otherwise you're going to see a lot of wasted prefetches as it means the router will try to prefetch your loading.js components (to power instant loading states), but will immediately discard it because of the static staletime configuration.

To clarify, the static property applies to when you set prefetch={true}, but is also an indicator for how long to re-use your loading.js components (if you have any).

That said, I've opened a PR to address this particular case in dev:

• remove special-cased prefetch kind in dev mode #64941

[rustunooldu]

Got it, thank you for the detailed response.

It's a highly dynamic site and we benefit little from caching (all the links already had prefetch={false}), so I was basically trying to disable router cache all together and not deal with random cache related issues in pages.

Once the PR for dev mode is merged, I'll definitely do more testing and fine tune it following your suggestion.

[Wilian-Pereira-W]

How to use prefetch={true} and static 10s. Because when I hover the mouse over the link and the prefetch is done again. Is there anything that can be done?

[EryouHao]

revalidateTag often does not work, the program code remains unchanged, but occasionally it fails to work, which forces me to update the tag key every once in a while. This makes me very frustrated.

I want to know how much unstable_cache space can be used for Next.js projects deployed on Vercel.

[leerob]

Hey @EryouHao, are you seeing this on the latest version? And if so, can you open an issue with a reproduction so we can investigate please? Thank you.

[leerob]

Thank you all for the feedback here. We're making some larger changes in Next.js 15, based on this discussion.

fetch, Route Handlers, and the client router cache are all no longer cached by default. You can still use them by manually opting into this caching behavior.

Try out the release candidate and learn learn -> https://nextjs.org/15-rc

[bozzhik]

If I understood correctly, now by default nothing is cached in next js, or only fetch is not cached and everything needs to be set up independently if necessary?

[ivan-kleshnin]

Even RC docs are completely outdated now... we're drifting alone 🌴 🙄

• Will NextJS team acknowledge that SPA was the reason people have started to use it?
• Will NextJS team address the growing number of concerns of developers working on heavy-interactive apps?
• Will the above happen before we switch over to SolidStart or another tool that listens to our requirements and complaints?

Nobody knows.

[leerob]

Wrote up a longer form message on where we're headed in the future as well: https://x.com/leeerob/status/1803824227704877236

[leerob]

@bozzhik Please give the Next.js 15 RC post a read. This won't go into effect until we release 15 stable.

@ivan-kleshnin We're still working on updating that page further before the stable release.

You can absolutely build SPAs with Next.js if you want, we don't discourage that. We also have the "static export" mode.

[ivan-kleshnin]

we don't discourage that.

I dunno, I see many obstacles for building SPA.

To begin with, there's no way to mark page as a "use client" component and have metadata working at the same time. In page router it was possible to have getInitialProps / getServerSideProps and Head component in the same file. But now, in the app router, it's somehow impossible.

I see no technical reason to limit that ("use client" components are still executed on the server, so you could strip out metadata / generateMetadata). In the best case, it wasn't done to simplify NextJS internals, but even than it reflects team priorities.

Now the way to get along with SPA is to have nested "use client" sub-page components near ALL page components. Where page server components would handle metadata and subpage client components would handle data fetching. Aadditionally ghettoized by RSC-CC boundary rules. No function passing, no contexts. Sometimes with obscure untraceable errors if you violate any of those.

So we're encouraged pushed to follow React/NextJS vision of await-based data fetching.

Which is fine when 1) data is static 2) data is rarely updated. SPA are typically interaction heavy. It feels absolutely insane to hit a server, rerender the whole app tree, send the result back, parse it, reconcilate the whole VDOM to... update a single counter after some "Like" button press. And that is what we're supposed to do with server actions and revalidate. The amount of resources used for what should have been a single node DOM mutation is mind boggling.

To me, it certainly feels like SPAs are 2nd class citizens in NextJS.
I see there's a https://nextjs.org/docs/app/api-reference/functions/unstable_cache which implies we'll get key-based cache update at some point. Regardless, we see that NextJS removes functionality necessary/convenient for SPA before it provides any reasonable alternative. Which means that SPA is an afterthought if not a "legacy approach" in NextJS view and BE-centric cache / fetch control is the way to go. And every recent React controversy supports my claim.

[bitttttten]

Hi @timneutkens @leerob thanks for the great post!

Does revalidateTag also revalidate what's been cached by Vercel's Edge Network? We have our about page, for example, that we refetch data for every 24 hours (i.e. next.revalidate = 86400). If we call revalidateTag('about') would it also cache bust what's been caught on Vercel's CDN/Edge Network?

Apologises if this has been answered somewhere else already, I am still getting to terms with all the lingo :)

[jim-king-2000]

router.back() does not purge data cache of the target page. invalidatePath or export const dynamic = 'force-dynamic' does not work. Is it possible to purge the data cache of the very page(let's say '/') and use router.back() to go back to the page(let '/' invoke server fetch)?

[jim-king-2000]

Call router.back() twice will workaround this. Weird!

[kostas-pblworks]

Hi everyone, I've been trying to understand what are the standard/best practices when it comes to clearing to cache.

I've created this sandbox to showcase my case. The problem I'm trying to deal with is to figure out when the UI has done changing after a mutation. The case is simple, there's a list of records and a delete mutation. The only way to do it so far is to use a form in conjunction with useTransition. So now my question is, is this the standard practice? What other practices are there?

There's also a conversation here trying to explain the case as well.

Thank you

[jazsouf]

Hello everyone,

I've been exploring the behavior of revalidateTag and I noticed that it behaves differently when called from a server action compared to a route handler. The original post explains the behavior, but I'm curious about why make this choice.

In the official documentation, it's mentioned that revalidateTag has a stale-while-revalidate behavior. However, I'm wondering why we need to refresh the router by default with server actions. It seems counterintuitive to have different behaviors for the same function, depending on where it's called from.

Would it be possible to have revalidateTag behave only similarly to how it does inside a route handler? This way, if I want to refresh the page, I could simply call router.refresh on top of that. This would make the code more predictable and easier to understand for developers.

I'm interested in your thoughts on this and any suggestions you might have.

[brgndyy]

Hello, may I translate the above explanation into Korean and post it on my personal blog?

It seems to be an important part of the Next.js app router, and I would like to translate it into Korean to share with other Korean developers.

[johannespn]

Thanks for reacting Next team, but because of not being able to opt out of route caching, trying out mixing server components and client components was very frustrating for me.. I'll think again if I really want to use server components..

[a89529294]

Can someone help me out with this issue #74272
It seems like a bug in client side router cache.