From Segments to Suspense: The Future of Next.js Caching

How to Use React. Hello, everyone. Thanks for joining me today. Obviously, my name is Wyatt Johnson. I'm a software engineer on the Next.js team at Vercel.

Today's talk is a deeper exploration of some of the changes that we've introduced with Next.js 16, specifically Cache Components. Cache Components is the future of the Next.js app router that combines many of the experimental features we've been developing over the last few years into a single concept. Now, with a single configuration option, you can get the rendering techniques of partial pre-rendering, the dynamic detection of Dynamic I.O., and the new caching directives, like Use Cache.

Together, these features paint a much more complete future of the app router. I actually went on stage last year at Next.js Conf to discuss partial pre-rendering and Dynamic I.O. We wanted developers to understand the reasoning behind some of the technical decisions that we made, along with providing some concrete examples of how Dynamic I.O. improved the developer experience. Just like then, today we're going to talk about how Cache Components solves many of the problems that developers face today.

When we started development of the app router, our goal was to create a new way of developing React applications that offered fast and dynamic experiences for their users. App Router took advantage of React Server Components to enable everything from co-located data loading within their components, to data mutations powered by server actions. It meant that now, instead of writing GetStatic Props or GetServerSide Props, developers could just write React.

They could query their databases inside of their components, or access request data, like cookies. Next.js used this information it collected at build time to determine if a page could be rendered statically, or if it needed to render each request dynamically. But, there was a problem with this design. As developers started to build more and more complex applications, they had to be increasingly vigilant to ensure that they didn't introduce performance regressions.

Adding a component to a page that accessed request data meant that the entire page could not be rendered statically, leaving users waiting for their page to load. We had created a mountain road without any guardrails. Small mistakes could result in big impacts to performance. We needed a way to guide developers so that their applications were still fast, without sacrificing the flexibility offered by dynamic rendering.

After years of development, literally years, we think that Cache Components has that solution. It's not just a configuration option, it's actually a new programming model, as it provides a new way for static and dynamic parts of your React applications to compose together. Under this new model, components don't just co-locate their data, they also co-locate their caching. To help developers, Next.js now provides more feedback to ensure that they're guided towards creating the best version of their applications.

Now, when a component attempts to access request-specific data, like cookies, Next.js produces a build error if that component, or its parents, is not wrapped in a suspense boundary. This ensures that applications that want to show dynamic data can still have something static to send for initial load, streaming the dynamic content in afterwards.

Other forms of I-O, such as fetch calls or database queries, are also automatically marked as dynamic, thanks to Dynamic I-O. To mark I-O as statically cacheable, the developer needs only annotate that code with a cache directive, such as useCache. We wanted to introduce this new programming model in a way that led developers to getting the most out of the framework. We also wanted to do this while introducing as few new APIs as possible, so developers wouldn't need to learn so many new concepts. Today, I'm going to focus on only a few of these changes that we've introduced with cache components.

We'll explore some of the changes to generate static params and deprecations of segment configuration options for revalidate and dynamic. First, let's explore the changes to generate static params. Walking through some parts of a fictional e-commerce application, we can illustrate these in action. This is our product page. As this page has dynamic path parameters, category, and slug, it's marked as dynamic by default. This means that when users try to visit a product page, they'll have a fresh page rendered on the server for each request. If these product pages are visited frequently, we may want to take advantage of static rendering so it can be served fast from the edge, improving the speed of navigations in the site.

To tell Next.js that we want to render this page statically, we need to export generateStaticParams to provide optionally some parameters that we want to prerender. Let's add that now. Perfect. Now when a user visits a product page for the first time, this page is rendered statically and can now be served fast for all subsequent visits. We're done, right? While this may have worked initially, this code masks a danger that inexperienced developers might miss. Days, weeks, or months later, a seemingly unrelated change in another component could silently break this page in production.

This particular class of error evades detection through Next.build, appearing only when the application is running in production. The culprit? This line. It's kind of hard to see at the bottom of the slide there. It's not that returning an empty array from generateStaticParams is inherently an error by itself. The bug itself manifests when a server component that was rendered on this page or layout attempts to access request data, such as headers. Let's update our page with an example of that to see how that works. Now, our product page includes our new userDeals component. Inside, it reads request headers to determine the user's country so it can present them with relevant deals for their region. When we run Next.build, everything looks good and it successfully deploys to production. When we try to navigate to one of these product pages, however, we get an error.

Let's explore. When we provided no params to prerender and instead just provided an empty array, it's the equivalent of telling Next.js, trust me, this page is static. So when Next.js went to render this page statically in production and it started to render the userDeals component, it tried to read request headers, something that only dynamic components can do. This page is only rendering statically because we added generateStaticParams export to it. If a page attempts to access something dynamic during prerendering, Next.js stops and marks that page as dynamic, preventing this style of error from occurring.

The problem is we never actually provided any parameters to prerender, so we never actually rendered the product page during build, and Next.js never sees it using the headers API. Let's modify the generateStaticParams function here to return some parameters so we can render the page and see what happens. Now we've modified our generateStaticParams function to return some popular products from the database. With a complete set of path parameters, Next.js can now prerender this page at build. This time, Next.js can hit the code in the userDeals component that accesses headers. When it does, it stops trying to statically prerender the page and instead marks it as dynamic.

Let's reflect on the flow we just went through here. We had a dynamic page that rendered every request, which was slow to navigate around, so we exported generateStaticParams so that Next.js would know we want to instead render it statically, which can be served fast. Later, we added a component that accessed request data, which isn't available when running statically, and as we didn't return any parameters for Next.js to prerender, it wasn't able to discover the call to the headers API, and as a result, we get that build error in production. Returning some products for us to render solved that runtime error, but now the route is back to rendering dynamically, losing all the speed of static. The team found this a little strange and unintuitive, and we wanted to make it easy for keeping the static parts of your page fast while still allowing the flexibility of dynamic APIs.

The team found this a little strange and unintuitive, and we wanted to make it easy for keeping the static parts of your page fast while still allowing the flexibility of dynamic APIs. Thankfully, this is something that we've addressed with cache components. Let's roll back our product page to the beginning. We know from before that this page will be rendered dynamically because it does nothing to prerender at build time. With cache components enabled, though, we're actually presented with this error when visiting the page in development.

It's telling us that we're accessing uncached data outside of suspense boundary. This is because when cache components is enabled, thanks to partial prerendering, Next.js actually attempts to render the following route. When Next.js goes to render this page, not only will attempting to read request data be considered dynamic, but also any attempt to read the category or slug path parameters too. How do we solve this then? We don't want to add a suspense boundary, as we'd like the product pages to have their product information included in the static part of the page and not stream in afterwards. Instead, let's follow the same flow as before and add generate static params.

Just like before, let's start to return an empty array and run Next.build again. Surprisingly, we get an error. A new error. With cache components enabled, we're now required to provide at least one parameter when calling generate static params. This helps prevent the previous class of errors that would go undiscovered until it was deployed to production. Let's update our generate static params export now to return some parameters like before. Now we're returning some of the products. Running the build again, we don't actually get any build errors at all.

Let's explore what's happening here again. Assuming that we're returning the following parameters from generate static params, with cache components disabled, we know that Next.js would have rendered the page with the following path names. It's only able to render the path names where all the path parameters like category and slug are known. But with cache components enabled, not only do we render the routes with complete path names, but thanks to partial prerendering, we also try to render each unique permutation of the parameters that were provided, including those where category and slug were unknown.

Next.js is trying to render these partial path names to see if it can generate a static content that can be reused. For example, for other products under the jacket category that weren't listed here. How did adding params to the render eliminate our build error? Let's take a look at the code again for a second. When we provided some products to generate static params, Next.js could prerender the product page for those specific products. When it did, the category and slug parameters were known, but there was no dynamic access within this page. We proved to Next.js that there wasn't anything else dynamic on the product page.

What about when we tried to navigate to a product that isn't popular, such as another jacket? We know from earlier that when cache components is enabled, we attempt to render partial pages. When Next.js tried to render this page, however, we know that accessing the slug path parameter was not a dynamic. As we didn't add any suspense boundaries to the parameter access, there was no fallback for it to use when it suspended, meaning Next.js couldn't produce any static content. During build, Next.js uses this as a signal that static parts of the page depend on both the category and slug path parameters. It's full of heuristics. In production, this means that when you navigate to a page, Next.js knows it can render the page statically.

What about now if we added that dynamic component from before and add it to our page and see what happens? Now we're back to the code we had when we had cache components disabled. Remember that the user deals component here accesses request headers. Now, when we visit this page in development, it can see that we attempted to read the headers outside a suspense boundary. Unlike before, where we only saw an error after we deployed to production, Next.js was now able to detect the dynamic usage early and fail the build. With cache components enabled, Next.js is guiding us towards generating some of the static content that we can send to users to ensure fast navigations.

Now that we've added some dynamic components to our page, let's wrap them with a suspense boundary so they can stream in after the static content. Now, when the Next.js goes to pre-render the product page, the dynamic user deals component has a suspense boundary to fall back to. Instead of producing a product page that is completely static, it's now partially static. Thanks to the feedback that we received from Next.js we can now serve the rest of the product page statically while the user deals component streams in when it's ready. And we can actually apply the same principle to add another optimization to this page.

We know from before when the slug parameter is not known that we don't actually produce any static content. The reason? Awaiting the params promise in a page is considered dynamic when rendering those partial pages and we didn't have any surrounding suspense boundary. Let's add a new layout under the category segment. So for this particular layout we have the category slug path parameter but not the slug path parameter. So this promise works a bit different than what you saw on the page because this one doesn't actually contain the slug path parameter only the category. Now when we go to render the jackets category product page where the slug is unknown the param access falls back to the suspense boundary in the category layout producing a static page for us to use. Now when a user navigates to a product under the jackets category they'll be served the static parts of their page fast including this category layout while the rest of the page streams in afterwards.

Thanks to our changes we've made with the build process along with changes to generate static params for cache components Next.js can provide more meaningful feedback to developers. Rather than solely relying on exporting this method as a means to indicate that something should be rendered statically it helps guide developers to producing more static outputs that can be reused reducing the risk of errors, making it into production and improving the experience.

Next we'll explore some of the changes to our cache life APIs starting with our decision to deprecate the revalidate export. Before cache components we provided developers the ability to control how long a page should be cached for by exporting a revalidate config. This export present in a page or layout would mean that it should be statically re-rendered after one day. If you used other APIs like fetch and included a revalidate property the lower of the values would be taken This approach, however, had a few drawbacks.

With the segment configuration option living at the page or layout level the choice for the revalidation time usually felt quite arbitrary. A page could include any number of components possibly with their own calls to fetch that lowered the revalidation time. It seemed like the revalidation time of a page was pretty dependent on what it contained and what the path name was. It also wasn't possible to call fetch and have its result affect the properties like cache lifetime or tags. You could only configure the revalidation time when you called fetch, not after. We wanted a unified way to describe the properties of a cache entry one that would apply beyond just calls to fetch.

Similar to our story for React server components we wanted to solve this in a way that enabled users to just write code not configuration leveraging co-location to ensure that the important caching information stayed near the code that created it. For this reason, when you enable cache components in Next.js we deprecated the use of exporting the revalidate from pages and layouts and introduced a new caching model to replace it. Let's take our product page from before and explore how this works. Defining a function for fetching data from our product from the database and reading this code it's important to remember that cache components all IO is considered dynamic. We have two ways to handle dynamic data. We can either wrap it in a suspense boundary, meaning it'll run every request or we can mark the content as cacheable. In this case, we don't want it to hit the database each time so let's mark it as cacheable. We can also use a cache directive so that it's not marked as dynamic anymore and it means that because the call to the database occurs inside the use cache context it's not considered dynamic. It can be included in the static shell. As we didn't specify the cache life for this function implicitly it'll use the default. But if I wanted to configure a different cache life profile I'd just have to import the cache life function and apply the result to the get product function. Now when the result of this function is used within a static part of the page it too will have the same cache life profile. This provides a lot more granular control over the cache lifetimes of the data that's used to create static content.

Removing the validate segment configuration option streamlines our caching API so developers should only need to reach for the cache life API to configure lifetimes now. Let's look at the dynamic segment configuration option next. Before cache components this configuration option was used to override the behavior of some of the dynamic APIs and the rendering process as a whole. When not defined or set to auto Next.js would use that information that it discovered during build time to determine if a page should be static or dynamic. When set to for static it actually changed the behavior of request APIs to instead return empty results preventing it from becoming dynamic at all. When used on a product page for example every time the user deals component access headers it would instead return an empty set. While this did ensure that the pages were always rendered statically it meant that every component depended on request data would silently get frozen to the same empty state introducing subtle and hard to find bugs. We had introduced this option as an escape hatch where the page always produced an expected output and it was designed in a time that only produced static or dynamic pages.

Now with cache components you're not making an all or nothing decision anymore. Pages aren't just static or dynamic. They're both. We saw from before how we can compose cache boundaries in order to keep the static parts of our page static and fast and we could add suspense boundaries to keep the dynamic parts of our pages dynamic and flexible while still providing a static fallback to display. Developers were able to use the language of React and Compose's ability to describe their intended state of the applications rather than having to rely on static configuration. It just doesn't make sense to apply an all or nothing approach to static rendering when instead we're guiding developers to crafting fully or partially static pages instead. Next.js with cache components has been re-architected with this code-centric approach and it's as much about enabling you to cache things and stream things using suspense as it is about all the different ways that it now provides you with early feedback during development. We've explored a lot of changes. This isn't nearly all the changes we've made but you're able to test out cache components today simply by adding this option to your next config file.

Try it out. Open an issue of experience. Is there type safety between generateStaticParams and the params prop or is that the responsibility of the developer? I think it really depends on where it's being used as a part of the stack. The problem with generateStaticParams is that you can technically place it anywhere inside the segment hierarchy so you can have it at the root layout, you can have a generateStaticParams that applies to some route there or you can have it at the page, the leaf to also apply there so it's a little bit hard for you to universally pick one but if we don't already have types that are generated for it it's something we definitely could do. I really love that and also one thing I loved about the way you spoke about the cache components, you really spoke about guiding the developer, you spoke about those guardrails and how you want them to do less configuration and more code and I'm just curious not just this but in the way Vercel and Next.js work as a whole how do you approach really trying to create this yellow brick road, for lack of a better word very on point with the zeitgeist that developers can follow in order to actually have very performant applications? Yeah, we call it internally and I'm sure it's not a unique term is that we want developers to fall into this pit of success where it's easy for them to make the right decision because the framework is pushing them in that direction so there's just so many options when it comes to how you can build applications today that taking advantage of a framework oftentimes takes immense amounts of understanding of how things work so we just want to push them in that direction. Well I enjoy it, you're doing hard work so I don't have to think about it Alright, another question's coming and they're all coming in now How would you advise to use query data inside a layout for usage inside a provider with cache components enabled? It's very, very specific. Yeah, that's pretty tricky. I'd say it really depends on the use case and the thing you want to consider when you're using cache components and the App Writer in general is that all the segments render independently so rendering the layouts versus the pages they're actually rendered separately so the ideal here is that we don't want to re-render things that are too high in the hierarchy so that's why we don't provide some parameters in different places it really depends on the use case And the next one's a bit of a philosophical question and there's so many different frameworks, different approaches what are your thoughts on more explicit approaches versus the more magic approach directives provide? Yeah, I think that we saw the success with useClient when we started to adopt the differences between server and client components and cache directives are very much aligned with this with the client components right now so I'd say overall there are different solutions to the same problem and nothing is particularly right or wrong versus any of them but I think that the directive approach for us has been working really successfully Nice. And this one is about caching in React server components versus client components how do they differ or are they the same? I mean, it depends on if they're rendered server-side or not so we have a difference between obviously there's a misconception that when you have a client component that it only renders in the client but of course we render that server-side if we can but when you use a hook like usePathName we actually detect that as dynamic usage and apply that it's the same thing we did with the params from before where awaiting it would trigger dynamic access if one of the parameters is unknown so it depends on how much the client components can actually be rendered server-side and then we can reuse it I'm really excited. I can see all of these questions coming very specifically people applying caching to their use cases and this is for logins and logouts have you explored caching based on a different context such as caching to different versions of a page for logged in and logged out users? We've talked a little bit about this internally we're sort of dubbing it under a category we're calling variants nothing really exciting to talk about yet because there's nothing there but it's very much aligned with the idea that you want to create these static shells that can be reused under different contexts and then use things like headers or cookies or query parameters or some other thing to mux you to one of those variants so you can get that static version fast

Alright, and folks don't worry I wasn't ignoring you I was just saving the best question to last Where can people get this amazing and I really love it you need to turn around for everyone this amazing Vercel Jacket Yeah, it's one of those limited run things, you just have to be there to get it unfortunately, not a good answer I know but such is life Well, follow him around, you might be there when the next one's handed out Thank you so much Wyatt, can we give him a round of applause