DEV Community: Peter Jacxsens

Using Suspense in NextJs

Peter Jacxsens — Thu, 16 Apr 2026 09:34:39 +0000

Before we move to the new model of caching (cache components), I want to take a look at how <Suspense> interacts with static and dynamic rendering in the not partial prerendering model.

static vs dynamic rendering

Quick reminder: dynamic rendering happens when a route contains at least one of the following elements:

cookies function
headers function
connection function (more later)
draftMode function
searchParams prop
unstable_noStore (legacy)
dynamic fetches: fetch with { cache: 'no-store' }

Dynamic rendering means that the route will be rendered server-side at request time. This render is not cached, so every visitor gets a fresh and personal render. Any route that isn't dynamic will be statically rendered. That is it will be prerendered and cached at build time. These prerendered files are stored in the .next build folder. Each visitor gets served the same prerendered content. This is called the full route cache.

Suspense

The Next docs don't explain much about the <Suspense> component:

<Suspense> works by wrapping a component that performs an asynchronous action (e.g. fetch data), showing fallback UI (e.g. skeleton, spinner) while it's happening, and then swapping in your component once the action completes.

This swapping out is called streaming. Let's see some examples. Note: the examples are available on github. We reuse the <Post /> component from earlier:

// components/Post.tsx

type Props = {
  postId: number;
  fetchOptions: RequestInit;
};

export type PostT = {
  id: number;
  title: string;
};

export default async function Post({ postId, fetchOptions }: Props) {
  const data = await fetch(
    `https://jsonplaceholder.typicode.com/posts/${postId}`,
    fetchOptions,
  );
  const post: PostT = await data.json();
  // get date from headers
  const fetchDate = data.headers.get('date');
  const time = fetchDate
    ? new Date(fetchDate).toTimeString().slice(0, 8)
    : null;
  return (
    <div className='flex gap-2'>
      <div className='text-orange-400 mr-2'>{time}</div>
      <div className='font-bold'>{post.id}.</div>
      <div className='italic'>{post.title}</div>
    </div>
  );
}

And we load it in a static route:

// app/suspense/static/page.tsx

export default function Page() {
  return (
    <>
      <Header />
      <Suspense fallback='...loading'>
        <Post postId={50} fetchOptions={{}} />
      </Suspense>
      <Footer />
    </>
  );
}

We also added a header and footer:

// components/static/Header.tsx
export default function Header() {
  return <header>***** header *****</header>;
}

// components/static/Footer.tsx
export default function Footer() {
  return <footer>***** footer *****</footer>;
}

And we run next build. The build log reveals that the route was rendered statically: ○ /suspense/static. But, more importantly, when we look into the .next build folder, we can see that everything was prerendered, including the async data:

<!--
  .next\server\app\suspense\static.html
  cleaned out
-->

<!doctype html>
<html lang="en">
  <body>
    <header>***** header *****</header>
    <!--$-->
    <div class="flex gap-2">
      <div class="text-orange-400 mr-2">16:46:44</div>
      <div class="font-bold">50<!-- -->.</div>
      <div class="italic">
        repellendus qui recusandae incidunt voluptates tenetur qui omnis
        exercitationem
      </div>
    </div>
    <!--/$-->
    <footer>***** footer *****</footer>
  </body>
</html>

We can clearly see the header, footer and the <Post /> content. So Next resolves the promises during build time.

I got a bit curious at this point and wrote a new test with an button that calls updateTag (we used the <UpdateTagActionButton /> component earlier):

// app/suspense/updateTag/page.tsx

export default function page() {
  return (
    <>
      <Suspense fallback='Loading...'>
        <Post postId={51} fetchOptions={{ next: { tags: ['post-51'] } }} />
      </Suspense>
      <UpdateTagActionButton tag='post-51' />
    </>
  );
}

So, we got a static route with a tagged post, wrapped in suspense. The <UpdateTagActionButton /> component is just a button that calls a server action where we call updateTag on tag "post-52". So, what happens? Will we get: Loading... fallback or not?

Nope! Honestly, I wasn't sure what would happen here. It seems that server actions and the read your own writes mechanic do not trigger the <Suspense /> fallback.

Another test with suspense in a dynamic route:

export const dynamic = 'force-dynamic';

export default async function Page() {
  return (
    <>
      <Header />
      <Suspense fallback='Loading...'>
        <Post postId={52} fetchOptions={{}} />
      </Suspense>
      <Footer />
    </>
  );
}

It's a dynamic route. That means no static rendering and no full route cache to take a look at. The build log confirms that it is a dynamic route. When we run next start and visit this example we get a very quick loading state when we load or reload the page:

This is pure streaming. The initial dynamic render shows the static components and the fallback. (This is called the static shell) Once Next resolves <Post /> in the background, the rendered result is streamed in.

What is the advantage of this? There is no blocking. Without suspense, the server must wait for every fetch to finish before sending a single byte to the browser. With suspense, the static shell is immediately send over, giving the user instant visual feedback.

Are we - partially prerendering - yet?

No, but we're getting very close. In the dynamic example above, the server had to generate the static shell at request time. In partial prerendering, that shell would have been rendered at build time while only suspense children would get rendered at request time.

useSearchParams hook

Way back in chapter 3 of this series, we covered static rendering of client components. As a quick reminder, client components are components that:

use hooks or custom hooks
have interactivity (event listeners)
use browser only API's like localStorage or geolocation.

We found out that client components can be statically rendered into HTML and rsc. The HTML is served on initial visit, rsc on client side routing. We also discovered that client components that use hooks can be statically prerendered into HTML. For example initiating state with 1 and then rendering a count with this state will result in prerendered HTML: "count: 1". The useState hook and most other hooks can be prerendered.

But, one hook is different: useSearchParams. Take this example:

// app/suspense/useSearchParams/page.tsx

export default function Page() {
  return (
    <>
      <Header />
      <Hello />
      <Footer />
    </>
  );
}

And <Hello /> is our client component with the useSearchParams hook:

// components/client/Hello.tsx

'use client';

import { useSearchParams } from 'next/navigation';

export default function Hello() {
  const searchParams = useSearchParams();
  return <div>Hello, {searchParams.get('name')}</div>;
}

When we run this in dev mode on route: http://localhost:3000/suspense/useSearchParams?name=peter (note the searchParam) we see this:

***** header *****
Hello, peter
***** footer *****

However, once we run build, we get an error:

⨯ useSearchParams() should be wrapped in a suspense boundary at page "/suspense/useSearchParams".

What is going on here? We are in a statically rendered route, that is at build time. At build time there is no Request and also no searchParams. There is no searchParams.name, so Next cannot prerender this route.

How do we solve this? We have two options:

Make the route dynamic. At request time, Next will have access to searchParams.
Keep the route static by using suspense.

We update our example with suspense:

export default function Page() {
  return (
    <>
      <Header />
      <Suspense fallback='Loading...'>
        <Hello />
      </Suspense>
      <Footer />
    </>
  );
}

And run build again:

○ /suspense/useSearchParams

○  (Static)   prerendered as static content

Great! But how did it render? Here is the prerendered HTML:

<!-- 
  .next\server\app\suspense\useSearchParams.html
  cleaned up
-->

<!doctype html>
<html lang="en">
  <body>
    <header>***** header *****</header>
    <!--$!--><template data-dgst="BAILOUT_TO_CLIENT_SIDE_RENDERING"></template
    >Loading...<!--/$-->
    <footer>***** footer *****</footer>
  </body>
</html>

Interesting. We now have a loading state - as expected - and some sort of template tag. When we run next start and visit the route, we see "Loading..." that gets replaced with "Hello, peter" really fast.

I'm not 100% sure how this works. My guess is that it's very similar to how client components are rendered on client side routing (when a user navigates inside your app) or during hydration. We discussed this in chapter 3 of this series.

Client-side Next requests and reads the rsc for this page. The rsc points to the client component <Hello />. Client side Next renders it (in the browser) and that rendered content gets swapped with the suspense fallback. So, in this particular case, suspense seems to set a boundary between server side and client side rendering.

Don't worry, this is an edge case. But, it is closely related to static and dynamic rendering of client components, to suspense and to partial prerendering, that is why I cover it here. Back to useSearchParams inside suspense. We can have statically rendered pages that use useSearchParams hook if we wrap the component inside suspense. This is great for performance.

Are we - partially prerendering - yet? Nope, but we really edged close here. We have a static shell that was created at build time. All components were statically prerendered expect the children of suspense. In our example, these children were rendered client-side. In PPR the rendering of a component wrapped by suspense would be done on the server.

Conclusion

At this point, we're done with the other model of caching. I specifically saved suspense and useSearchParams for last because they are a stepping stone to partial prerendering. Next was already starting to implement PPR-ish features and I wanted to highlight this.

At this point I'm going to take a small break in this series. When I'm back we'll cover the new model of caching with partial prerendering and cache components.

If you want to support my writing, you can donate with paypal.

Router cache and request memoization

Peter Jacxsens — Thu, 16 Apr 2026 09:27:58 +0000

We've covered full route cache, data cache and revalidation. Next, we look into router cache and request memoization.

Router cache

Router cache is client side cache, it lives in the browser's memory and consists of rsc payload. The goal of router cache is instantaneous navigation between pages. It does that by caching already visited pages and by prefetching pages that we might visit (the <Link /> component) and saving those in cache.

Each route is split into route segments: layouts (layout.tsx), loading states (loading.tsx) and pages (page.tsx). It's these route segments that actually get cached in the router cache. But only partly:

Layouts are cached and reused on navigation (partial rendering).

Loading states are cached and reused on navigation for instant navigation.

Pages are not cached by default, but are reused during browser backward and forward navigation. [...]

I don't really know how a page can be reused but not cached.

Duration

I can't improve upon what the Next docs say about this, so I'm just going to copy it:

The cache is stored in the browser's temporary memory. Two factors determine how long the router cache lasts:

Session: The cache persists across navigation. However, it's cleared on page refresh.

Automatic Invalidation Period: The cache of layouts and loading states is automatically invalidated after a specific time. The duration depends on how the resource was prefetched, and if the resource was statically generated:

Default Prefetching (prefetch={null} or unspecified): not cached for dynamic pages, 5 minutes for static pages.

Full Prefetching (prefetch={true} or router.prefetch): 5 minutes for both static & dynamic pages.

While a page refresh will clear all cached segments, the automatic invalidation period only affects the individual segment from the time it was prefetched.

Next docs

Note: this comes from Next 15 docs, more on this is a bit.

Invalidation

Again, from the docs:

There are two ways you can invalidate the Router Cache:

In a Server Action: - Revalidating data on-demand by path with (revalidatePath) or by cache tag with (revalidateTag) - Using cookies.set or cookies.delete invalidates the Router Cache to prevent routes that use cookies from becoming stale (e.g. authentication).

Calling router.refresh will invalidate the Router Cache and make a new request to the server for the current route.

Next docs

Note: in tests in the previous chapters, I had issues with router cache persisting after revalidation from a server action. So don't take this for granted.

Some closing notes

You may be thinking I took it a bit easy in this chapter by just copy-pasting. True, it was easier but there are some reasons why I did it.

Next explained it well. There was nothing for me to clarify.
It's hard to write tests for this so I couldn't really offer any added value.

But the main reason is something else. When I started writing this series I was carefully studying the docs. But, when I started to write this chapter, I suddenly couldn't find the docs on router cache anymore.

What happened? Next updated the docs on caching (v16.2.1 at 25/03/2026). Everything we covered in the previous 9 chapters is now considered "Caching and Revalidation (previous model)". The new model is "cache components".

On top of that, Next renamed router cache to client cache (we approve) and also changed how it works. The parts from the docs I cited above are from Next 15.

Lastly, I'm not sure there is that much to say about router cache. I just works in the background. We will come back to client cache later because at this point I don't know nothing about cache components yet.

Request memoization

It's very common to need data from a particular fetch in multiple components within a single route. Request memoization removes the need to pass props or use context by caching the result of the fetch and reusing it during the render pass.

/page.tsx
  Component1
    Fetch 1
    Fetch 2
  Component2
    Fetch 1
  Component3
    Fetch 2

In the above example, only two fetches will be made, fetch 1 and fetch 2. When Next hits the same fetch again, it will reuse the memoized result.

How does this differ from data cache then?

When Next encounters a fetch, it will first check request memoization. If there is a match it will return the match and not check the data cache. If there is no match in the memo cache, then Next will check the data cache and put this match in the memo cache.
Request memoization has a lifespan of the request cycle. So, a request is made, fetches are memoized and reused if needed, the route renders and the request memoization cache is purged.

So, the big point of memoization is that you can be 100% confident in making the same fetch over and over again in a singe route. It will not affect performance or cause higher load on some server endpoint.

Some notes

Memoization is a server feature. It only works in server components.
Memoization only applies to the GET method in fetch requests.
Once a request lifecycle has ended, memoization is removed. That's were data cache will takes over. It persists between routes.
Memoization doesn't work in route handlers (route.ts), only in the React component tree.

Finally, memoization happens for fetches that have the same url and options. Maybe we should write a little test for this?

Little test

Note: the examples are available on github.

We're going to create an api endpoint and then call it multiple times inside a dynamic page. Why do we need an endpoint? So I can log when it gets called. Why dynamic? In a static route I would need an external server (you can't run and build at the same time) and that would complicate this example. Here is the route handler:

// app\memoization\api\route.ts

const user = {
  id: 1,
  name: 'Peter',
};

export const dynamic = 'force-dynamic';

export async function GET() {
  console.log('Memoization/api called');
  return Response.json(user);
}

A getUser function that calls this endpoint. Note, we pass fetch options as param:

// app\memoization\getUser.ts

type UserT = {
  id: number;
  name: string;
};

export async function getUser(fetchOptions: RequestInit) {
  console.count('Running getUser');
  try {
    const res = await fetch(
      'http://localhost:3000/memoization/api',
      fetchOptions,
    );
    const user: UserT = await res.json();
    return user;
  } catch (error) {
    console.error(error);
    return null;
  }
}

A <User /> component that calls getUser and renders name:

// components\memoization\User.tsx

import { getUser } from '@/app/memoization/getUser';

export default async function User({
  fetchOptions,
}: {
  fetchOptions: RequestInit;
}) {
  const user = await getUser(fetchOptions);
  if (!user) return <div>No user found</div>;
  return <div>{user.name}</div>;
}

And finally a route:

// app\memoization\page.tsx

import User from '@/components/memoization/User';

export const dynamic = 'force-dynamic';

export default async function Page() {
  return (
    <>
      <User fetchOptions={{}} />
      <User fetchOptions={{}} />
      <User fetchOptions={{}} />
      <User fetchOptions={{}} />

      <User fetchOptions={{ cache: 'no-store' }} />
      <User fetchOptions={{ cache: 'no-store' }} />
      <User fetchOptions={{ cache: 'no-store' }} />
      <User fetchOptions={{ cache: 'no-store' }} />

      <User fetchOptions={{ cache: 'force-cache' }} />
      <User fetchOptions={{ cache: 'force-cache' }} />
      <User fetchOptions={{ cache: 'force-cache' }} />
      <User fetchOptions={{ cache: 'force-cache' }} />

      <User fetchOptions={{ next: { revalidate: 1000 } }} />
      <User fetchOptions={{ next: { revalidate: 1200 } }} />
      <User fetchOptions={{ next: { revalidate: 1400 } }} />
      <User fetchOptions={{ next: { revalidate: 1600 } }} />

      <User fetchOptions={{ next: { tags: ['user-1'] } }} />
      <User fetchOptions={{ next: { tags: ['user-1'] } }} />
      <User fetchOptions={{ next: { tags: ['user-2'] } }} />
      <User fetchOptions={{ next: { tags: ['user-2'] } }} />
    </>
  );
}

We log from getUser and from the route handler. Take a guess, what happens? Remember, request memoization is automatic for fetches that have the same url and options.

For me, the result was a bit surprising:

Running getUser: 1
...
Running getUser: 20
Memoization/api called

Even though the getUser function was invoked 20 times, the underlying API was only hit once. There is an interesting quirk here: React's memoization usually requires the URL and all options to be identical. Even though we varied the cache and next.revalidate options in our test, React (or Next.js's patched version of it) deduplicated them anyway. Great for performance!

Bonus points: Here's a little question: how many of these fetches ended up in data cache?

Again, a bit surprising, we have two entries in cache:

// .next\cache\fetch-cache\hash
{"kind":"FETCH","data":{"headers":{"connection":"keep-alive","content-type":"application/json","date":"Mon, 30 Mar 2026 14:10:04 GMT","keep-alive":"timeout=5","transfer-encoding":"chunked","vary":"rsc, next-router-state-tree, next-router-prefetch, next-router-segment-prefetch"},"body":"eyJpZCI6MSwibmFtZSI6IlBldGVyIn0=","status":200,"url":"http://localhost:3000/memoization/api"},"revalidate":31536000,"tags":[]}

// .next\cache\fetch-cache\hash
{"kind":"FETCH","data":{"headers":{"connection":"keep-alive","content-type":"application/json","date":"Mon, 30 Mar 2026 14:10:04 GMT","keep-alive":"timeout=5","transfer-encoding":"chunked","vary":"rsc, next-router-state-tree, next-router-prefetch, next-router-segment-prefetch"},"body":"eyJpZCI6MSwibmFtZSI6IlBldGVyIn0=","status":200,"url":"http://localhost:3000/memoization/api"},"revalidate":1000,"tags":[]}

One with revalidate 1000, the other 31536000 (default = 1 year). Can we explain this?

The first 8 fetches have implicit or explicit no cache policies, so they don't get cached in data cache.
The first fetch with force-cache should then be the one above with 1 year revalidate. The next 3 with force-cache will be memoized.
This: <User fetchOptions={{ next: { revalidate: 1000 } }} /> is obviously the second one we found in cache. But the next 3 with values 1200, 1400 and 1600 are absent. Not sure about this.
The last four with tags user-1 and user-2 are absent. Maybe they hit memo cache, matched and did not proceed to check data cache? I'm not sure.

It gets tricky but in the end it doesn't really matter. Some final pieces.

Cache and unstable_cache

React automatically performs request memoization for the fetch API. If you aren't using fetch, you can manually implement request memoization by wrapping a function with cache:

export const getItem = cache(async (id: string) => {
  const item = await db.item.findUnique({ id });
  return item;
});

Also, note that you're not limited to DB or endpoint queries. It's also possible to cache heavy computational functions. But, beware here, cache is for request memoization, not for data cache.

To manually add items to data cache, Next provides the unstable_cache function. However, Next warns that this API was replaced with use cache which we will cover later.

Closing

This mostly concludes caching in Next - the old model. Before we start with the new model - use cache - I have some loose ends to tie and some other things to investigate. We'll do that first and then move on to the new model.

If you want to support my writing, you can donate with paypal.

Incremental Static Regeneration (ISR)

Peter Jacxsens — Thu, 16 Apr 2026 09:27:29 +0000

We talked about incremental static regeneration before, it's when a statically rendered route is updated without having to rebuild it. It updates, server-side at request time. But that is just updating existing routes. ISR has an extra trick. You can also add new routes to the full route cache.

An example

It's best explained using an example. Note: the examples are available on github.

Let's say you have a blog app with five blog posts. When deploying the app, it will first run a build (next build) and then start up the server (next start). The five posts were statically rendered and are now in the full route cache. Each request will be served from this cache.

But how do we add content? Let's say we wrote a sixth blogpost in the CMS and published it. What now? We want a statically generated post but how do we get it on the Next server? A redeploy with a new build?

Maybe the CMS calls a webhook on publish. We can catch that in a route handler and call ... what exactly? We can't use revalidatePath because there is no path (the post doesn't exist in the initial build). revalidateTag('post-6', "max") maybe? No, there is no cache tag for 'post-6' yet. So, that's our problem, we need to add prerendered routes.

We set up a blog example: a blog home page and then posts in a dynamic route segment ([slug]).

app
  blog
    page.tsx
    [id]
      page.tsx

This is our blog home page.

// app/blog/page.tsx

import Link from 'next/link';

export type PostT = {
  id: number;
  title: string;
  body: string;
};

export async function getPosts() {
  const data = await fetch('https://jsonplaceholder.typicode.com/posts');
  const posts: PostT[] = await data.json(); // 100 posts
  return posts.slice(0, 5); // return 5 posts
}

export default async function BlogHome() {
  const posts = await getPosts(); // 5 posts
  return (
    <div>
      <h1 className='text-xl font-bold mb-2'>Blog</h1>
      <ol className='list-inside list-decimal'>
        {posts.map((post) => (
          <li key={post.id}>
            <Link href={`/blog/${post.id}`} className='underline text-blue-500'>
              {post.title}
            </Link>
          </li>
        ))}
        <li>
          <Link href={`/blog/6`} className='underline text-blue-500'>
            post 6
          </Link>
        </li>
      </ol>
    </div>
  );
}

Quick overview: We're trying to simulate that we have a CMS that returns 5 posts. So, we take the 100 posts that JSONPlaceholder api returns and only use the first 5. We then render these 5 posts out as links to individual blog posts. Finally, I manually added a 6th link. We will need this in a bit to run some tests.

Here is our dynamic route segment (f.e. /blog/1):

// app/blog/[id]/page.tsx

import SinglePost from '@/components/blog/SinglePost';
import { getPosts } from '../page';

export async function generateStaticParams() {
  const posts = await getPosts();
  return posts.map((post) => ({ id: post.id.toString() }));
}

export const dynamicParams = false;

export default async function Page({ params }: PageProps<'/blog/[id]'>) {
  const { id } = await params;
  return <SinglePost id={id} />;
}

You probably are likely familiar with dynamic route segments but here's a quick recap. We want to statically render this route (/blog/[id]/page.tsx). To let Next know what the ID is, we use generateStaticParams. This returns an array of the IDs we have for our five posts:

[
  { id: 1 },
  { id: 2 },
  //...
];

This enables Next to statically render these five posts at build time. Note the export const dynamicParams = false;. This actually disables the addition of new routes, more on this later. Finally, we render the post content in a <SinglePost /> component. It makes a fetch for a single post with given id and prints out title and content.

// components/blog/Post.tsx

import { PostT } from '@/app/blog/page';
import Link from 'next/link';

type Props = {
  id: string;
};

export async function getPost(id: string) {
  const data = await fetch(`https://jsonplaceholder.typicode.com/posts/${id}`);
  const post: PostT = await data.json();
  return post;
}

export default async function SinglePost({ id }: Props) {
  const post = await getPost(id);
  return (
    <div>
      <h1 className='text-xl font-bold mb-2'>{post.title}</h1>
      <p>{post.body}</p>
      <Link href='/blog' className='text-blue-400 underline block mt-4'>
        back
      </Link>
    </div>
  );
}

Run build

So, we have our setup. Let's now see what happens when we run next build:

├ ○ /blog
├ ● /blog/[id]
│ ├ /blog/1
│ ├ /blog/2
│ ├ /blog/3
│ └ [+2 more paths]

○  (Static)   prerendered as static content
●  (SSG)      prerendered as static HTML (uses generateStaticParams)
ƒ  (Dynamic)  server-rendered on demand

The build log confirms what we expected, the blog home and all individual posts were rendered statically. Note that Next distinguishes between Static and SSG.

As we did earlier, let's also take a look at the .next build folder. We find the following files:

.next
  server
    app
      blog.html
      rsc.html
      blog
        1.html
        1.rsc
        ...
        5.html
        5.rsc

So, for each of our 6 pages, an HTML and .src file were created. This is what we expect from static rendering.

next start

Let's now run next start and run locally in production mode. The page http://localhost:3000/blog appears as expected. Five generated links and one hard coded link. The five generated links work properly and lead to the relevant posts. Clicking the hardcoded link to /blog/6 (that doesn't exist in our prerendered build) leads us to a 404 not found page. This is as expected.

Now, we go back to the dynamic route segment (/blog/[id]/page.tsx) and change the route segment option dynamicParams to true. Note that true is the default value, so we could omit it:

export const dynamicParams = true; // true | false
// same as
// export const dynamicParams = true; // true | false

After rebuilding and restarting, the build log is the same and everything works as before except the blog/6 link. That no longer leads to a 404 but to an actual blog post:

<!-- http://localhost:3000/blog/6 -->
<div>
  <h1 class="text-xl font-bold mb-2">dolorem eum magni eos aperiam quia</h1>
  <p>
    ut aspernatur corporis harum nihil quis provident sequi mollitia nobis
    aliquid molestiae perspiciatis et ea nemo ab reprehenderit accusantium quas
    voluptate dolores velit et doloremque molestiae
  </p>
  <a class="text-blue-400 underline block mt-4" href="/blog">back</a>
</div>

This is great, we were able to create a new page. But there is something else to see here. Our .next build folder now contains 6.html and 6.rsc.

.next\server\app\blog\6.html
.next\server\app\blog\6.rsc

This is an extra function of incremental static regeneration. We added a route to the full route cache, not at build time but at request time. This prerendered route will now be served to all users. Once again, a user made a request to a route that was not prerendered. Next then freshly rendered the route - server-side at request time and added it to our full route cache. So, ISR allows us to add content to the full route cache at runtime. And that is awesome!

Some improvements

I want to take the rest of the chapter as an opportunity to apply some of the things we learned about caching thus far.

Blog home

On our blog home page, we made a fetch with no caching option - the auto option. That means no data cache was created. Nextmade a fetch, used it to generate HTML and rsc but did not cache the fetch result. In a real project, that could be a problem: when we publish a new blogpost, we would like it to appear on our home page.How would we solve this?

We could make the blog homepage dynamic and set no-store to the fetch. Every request would generate a fresh result. It would work.
revalidatePath or revalidateTag could work. CMS (publish post) -> webhook -> route handler -> revalidatePath('/app/blog') or revalidateTag(posts). The cached route is marked as stale and Next regenerates the page. We now have a link to our new blog post.
Time based revalidation could also work, e.g. fetch('https://jsonplaceholder.typicode.com/posts', { revalidate: 360 }). Every hour the data becomes stale and the next request will trigger a revalidation. Result: our new link appears.

Any form of caching on the posts fetch would have another benefit. We used getPosts inside our blog home page but also inside generateStaticParams in our dynamic route segment (/blog/[id]/page.tsx). This means that at build time, Next only fetched it once and used the data cache for the second one.

Blog post

So, ISR allows us to add content to our full route cache and to update our full route cache. Right now, we don't have that functionality in our post. If we wrote a typo for example, there is no way to fix it. We need revalidation.

How? Depends, you know the options: time based or on demand revalidation. Determine what you need and find a suitable solution.

ISR setup

Next allows ISR by default. This has some consequences. What if we visit blog/foobar? This should fail. Our fetch getPost wouldn't return a post but - depending on the CMS - something empty or an error. Our <SinglePost /> component would then crash trying to render this out as a post. To solve this, check the data and use notFound().

// has post?
if (!post) {
  notFound();
}

Also note that if you do not want ISR, you must turn it off: export const dynamicParams = false. This is important because crawlers or malicious users will otherwise make weird requests that force your server to try and render non-existent pages.

Onwards

So, we learned how to add statically rendered routes to full route cache, not at build time but at request time. This is a very powerful tool especially when combined with cache invalidation.

In the next chapters we learn about other cache mechanisms Next provides.

If you want to support my writing, you can donate with paypal.

revalidateTag & updateTag In NextJs

Peter Jacxsens — Thu, 16 Apr 2026 09:26:22 +0000

We've been covering on-demand revalidation. Three functions allow you to revalidate on demand:

revalidatePath
revalidateTag
updateTag

In the previous chapter, we took a look at revalidatePath. In this chapter we cover the other two:

revalidateTag allows you to invalidate cached data on-demand for a specific cache tag.

updateTag allows you to update cached data on-demand for a specific cache tag from within Server Actions.

We target cached data, that is data cache entries.

Create a tag

A cache tag (string[]) is a tag you add to a data fetch:

fetch(url, { next: { tags: ['posts', 'post-a'] } });

Note: there is a second option to create a tag: cacheTag. We will cover this in a later chapter.

Tagging a fetch will add the data to the data cache with those tag(s). You can then call revalidateTag or updateTag to revalidate or update the data.

updateTag

updateTag(tag: string): void;

Takes one argument: a single tag.
Can only be called from server actions.
Revalidates data as read-your-own-writes.

This should sound familiar. A function called from a server action performs a read-your-own-writes revalidation. Note that updateTag cannot be called from a route handler.

revalidateTag

revalidateTag(tag: string, profile: string | { expire?: number }): void;

First argument: a single tag.
Second argument (profile): 'max' or { expire: 0 }
Use it in route handlers.
Don't use it in server actions (you can, but use updateTag instead).

revalidateTag is a bit weird because its functionality seems to overlap with updateTag and that's true. updateTag is a recent addition to Next and it takes over some of the functionality of revalidateTag. However, for legacy support, revalidateTag keeps its original functionality. The rule is simple:

route handlers -> revalidateTag
server actions -> updateTag

It gets a bit weirder with the second argument of revalidateTag:

// inside route handler
revalidateTag('post-a', 'max'); // -> stale while revalidate
revalidateTag('post-a', { expire: 0 }); // -> read your own writes

So, when called from within a route handler, revalidateTag can revalidate via SWR or RYOW. revalidatePath can only do stale while revalidate.

Full route cache

revalidateTag and updateTag target the data cache, tagged data cache entries. But what happens with the full route cache - statically rendered routes? The short answer is as expected.

revalidateTag(tag, "max")(swr) in a static route

When calling revalidateTag(tag, "max") from a route handler, Next will mark the tagged data cache entry as stale. Any statically rendered routes that "depend" on this cache tag, will also be marked as stale. Note: no updates have been made at this point.

When Next receives a new request for a route that depends on the invalidated cache tag, it will serve the stale content and update the data cache and full route cache in the background. Only the next request will be served this now-fresh content. This is pure SWR. We've covered this. Let's write a test.

Note: the examples are available on github. We make a new route handler that will call revalidateTag. As before, we will hit this route handler directly to simulate an external call:

localhost:3000/revalidate/api/revalidateTag?tag=post-42&profile=max

This time we pass 2 searchParams: a tag and a profile value. This is our route handler:

// app/revalidate/api/revalidateTag/route.ts

import type { NextRequest } from 'next/server';
import { revalidateTag } from 'next/cache';

export async function GET(request: NextRequest) {
  const tag = request.nextUrl.searchParams.get('tag');
  const profileParam = request.nextUrl.searchParams.get('profile');
  const profile: 'max' | { expire: 0 } = profileParam
    ? profileParam === 'expire'
      ? { expire: 0 }
      : 'max'
    : 'max';

  if (tag) {
    revalidateTag(tag, profile);
    return Response.json({ revalidated: true });
  }

  return Response.json({
    revalidated: false,
    message: 'Missing tag to revalidate',
  });
}

We also create a route for some post components:

// app/revalidate/tag/max/page.tsx

export default function Page() {
  return (
    <>
      <Post postId={41} fetchOptions={{}} />
      <Post
        postId={42}
        fetchOptions={{ next: { revalidate: 1800, tags: ['post-42'] } }}
      />
      <Post postId={43} fetchOptions={{ cache: 'force-cache' }} />
    </>
  );
}

And we run a test:

[action]
  next build
  next start
  visit localhost:3000/revalidate/api/revalidateTag?tag=post-42&profile=max
  get revalidated response
  visit /revalidate/tag/max

[expect]
  ✅ pass: all time stamps to be equal (from build)

[action]
  refresh page

[expect]
  ✅ pass: post 41 to have updated time stamp
  ✅ pass: post 42 to have updated time stamp
  ✅ pass: post 43 not to have changed

We revalidated post 42. We were served stale content on the first request. It updated in the background. On a new request (refresh), it served fresh data. Post 43 did not update. This is as expected. Post 41 also updated. This may or may not surprise you. Post 41 is a fetch with the auto cache option, which means no cache. When we revalidated post-42, it triggered a data cache and full route cache update. The last one made a new fetch for post 41 and that is why it updated.

We proved that revalidateTag only revalidates the tagged cache and behaves SWR when called from a route handler with the argument 'max'.

revalidateTag(tag, {expire: 0})(RYOW) in a static route

Here is a new example. We're calling revalidateTag with arguments 'post-45' and { expire: 0 } from a router handler. We expect read your own writes. We reuse the same route handler from the previous example but update the searchParams to tag "post-45" and profile "expire":

localhost:3000/revalidate/api/revalidateTag?tag=post-45&profile=expire

And we create a new test route:

// app/revalidate/tag/expire/page.tsx

import Post from '@/components/Post';

export default function Page() {
  return (
    <>
      <Post postId={44} fetchOptions={{}} />
      <Post
        postId={45}
        fetchOptions={{ next: { revalidate: 1800, tags: ['post-45'] } }}
      />
      <Post postId={46} fetchOptions={{ cache: 'force-cache' }} />
    </>
  );
}

[action]
  next build
  next start
  visit localhost:3000/revalidate/api/revalidateTag?tag=post-45&profile=expire
  get revalidated response
  visit /revalidate/tag/expire

[expect]
  ✅ pass: post 44 and post 45 to have same time stamp (updated)
  ✅ pass: post 46 to have different time stamp (from build)

My test may be a bit confusing. We hit the endpoint and expect RYOW. The data cache for post-45 updates, this triggers an update for route revalidate/tag/expires, which in turn refetches post 44 (auto cache option). There is no refetch for 46 because the data cache is not stale. Thus, 44 and 45 were updated while 46 kept the timestamp from build.

Note: we could've first visited the test route /revalidate/tag/expire, looked at the time, then hit the api endpoint and returned to our test route. But, that would've caused problems with the client-side router cache and the test would've failed. This is a problem you have to consider in real live world apps as well.

In short, we confirmed that calling revalidateTag with option { expire: 0 } does revalidate as read your own writes.

updateTag()(RYOW) in a server action

We're working with server actions and read your own writes now. Server actions are event driven. A user clicks a button and expects a change in the UI. Notice how this differs from the previous example. That was an outside action, this is internal. We expect an immediate update.

Here is our example:

// app/revalidate/tag/updateTag/page.tsx

export default function page() {
  return (
    <>
      <div className='mb-8'>
        <Post postId={47} fetchOptions={{}} />
        <Post
          postId={48}
          fetchOptions={{ next: { revalidate: 1800, tags: ['post-48'] } }}
        />
        <Post postId={49} fetchOptions={{ cache: 'force-cache' }} />
      </div>
      <UpdateTagActionButton tag='post-48' />
    </>
  );
}

So, 3 posts and a button: button -> server action -> updateTag.

Note: not 100% clear but 2 clicks.

Everything updates as expected. 47 (no cache) and 48 updated, 49 (force cache) did not. We also made a copy of this route without the button:

// app/revalidate/tag/updateTag-copy/page.tsx

export default function page() {
  return (
    <>
      <Post postId={47} fetchOptions={{}} />
      <Post
        postId={48}
        fetchOptions={{ next: { revalidate: 1800, tags: ['post-48'] } }}
      />
      <Post postId={49} fetchOptions={{ cache: 'force-cache' }} />
    </>
  );
}

We clicked the button in the route revalidate/tag/updateTag. Then we visited our full route cache for the route copy:

.next\server\app\revalidate\tag\updateTag-copy.html

We found the prerendered HTML and saw that the timestamps were still the old ones on all posts. Next, we actually visited the route: revalidate/tag/updateTag-copy and found that all timestamps were updated. Upon revisiting the prerendered files, we saw that they had been updated as well.

So, this is interesting. The route where the server action was called from was updated immediately. Other routes that depend on the updated tag are marked as stale and get updated when a request is made for that route. No stale content is served. The server rerenders the route at request time, serves the fresh content and saves it in the full route cache. In other words, for other routes, the update is only made at request time. Hitting updateTag does not immediately update all routes statically.

Summary

revalidateTag invalidates a cache tag. Only call it from inside a route handler.

revalidateTag('tag', 'max'); // -> stale while revalidate
revalidateTag('tag', { expire: 0 }); // -> read-your-own-writes

Depending on the second parameter ("max" or "{ expire: 0 }"), it will also update all affected routes in the full route cache as stale while revalidate or read-your-own-writes.

updateTag invalidates a cache tag. Only call it from a server action. It invalidates cache tag and all affected routes in the full route cache as read-your-own-writes. However, only the route the server action was called from will immediately be statically rerendered. Other affected routes will only be statically rerendered at request time.

Some notes

The Next docs explicitly mention that it's fine to call both revalidatePath and updateTag together to ensure data consistency.
Caching and revalidation work completely differently in development mode, so be careful.

If you want to support my writing, you can donate with paypal.

On demand revalidation in Nextjs

Peter Jacxsens — Thu, 16 Apr 2026 09:25:21 +0000

Revalidation is about updating stale cache. Three functions can trigger revalidation on demand:

revalidatePath
revalidateTag
updateTag

These only work server-side:

In a route handler (route.ts): e.g. called by a CMS webhook.
In a server action: after a user event like a form submit or clicking a refresh button.

RevalidatePath

revalidatePath invalidates cached data for a specific path. It targets data cache and full route cache if present.

The path can be

a specific url revalidatePath('/blog/a')
a route handler (route.ts)
a route pattern: revalidatePath('/blog/[postSlug]', 'page').

Note the second parameter type ('layout' | 'page'). When revalidating a route pattern, the second parameter is required.

This type parameter changes what is revalidated. Imagine this route setup:

app
  layout.tsx
  blog
    [postSlug]
      page.tsx

When calling revalidatePath('/blog/a'), the root layout.tsx will not be revalidated. This is the same as calling revalidatePath('/blog/a', 'page'):

revalidatePath('/blog/a');
// same as
revalidatePath('/blog/a', 'page');

If content of layout.tsx also needs to be revalidated, use the type parameter 'layout':

revalidatePath('/blog/a', 'layout');

But beware, this will revalidate all paths that use layout.tsx, nested paths as well, f.e. /blog/author/[slug]/page.tsx.

Cache invalidation mechanisms

We covered the stale while revalidate invalidation mechanism earlier in the time based revalidation section. All time-based revalidation uses stale while revalidate. On demand revalidation like revalidatePath is different.

When called from within a route handler, revalidatePath revalidates using the stale while revalidate mechanism. However, when called from inside a server action, revalidatePath will revalidate using the read-your-own-writes mechanism.

`read-your-own-writes`

read-your-own-writes purges the cache and immediately updates it. This is best explained with an example. Imagine your app has an edit account page, where a user can update their username. This would look like this:

User edits their name and clicks the save button.
This calls a server action that:
- updates the DB
- triggers on demand revalidation

What does the user expect to see after a successful update? Obviously their new username, not the old one (stale data). And that is where read-your-own-writes comes into play. Here is how it works:

The server action calls on demand revalidation.
Affected data is purged from the data cache and the full route cache if needed.
Fresh data is fetched and stored in the data cache. If needed a new full route cache is rendered.
The server action responds (e.g. status) and the fresh data and rendered route are sent along.

So, read-your-own-writes will immediately update the cache, whereas stale while revalidate does not. Server actions are called by user events (form submit, button click). Following this event, the user expects a change in the UI, this is critical.

There is a downside to read-your-own-writes. Updating the DB + revalidating the cache takes some time: the user has to wait. How do you handle this delay? Either a loading state or the useOptimistic hook. stale while revalidate does not suffer from this delay. It immediately returns data, stale data, but still, no wait.

Ok, now that we know about read-your-own-writes, let's return to revalidatePath. When it's called from:

Route handler -> stale while revalidate
Server action -> read-your-own-writes

`stale while revalidate`

Why is it fine to have stale while revalidate with route handlers? Let's explain by example:

You make a typo in a blog post.
You fix it in your headless CMS and save.
This triggers a webhook that calls an api endpoint in your app.
In this route handler you call revalidatePath for the relevant blog post path (e.g. /blog/post-a).

In this flow, there is no link between the event (happens in the CMS, not the app) and the UI of your app. The first user to visit /blog/post-a will still see the stale data (blogpost with typo). In the background, Next will refetch and rerender and serve the updated content to the next user. This is fine, it's not critical.

Of course, some things are critical - like a typo in a product price. You want that updated ASAP. But, this would require a different caching strategy. For a blog post, it's fine. I hope this makes sense, it all depends on the context.

More limitations

revalidatePath revalidates everything in the path. So, when there are multiple fetches, they will all be revalidated. This might not be desirable. If not, use a different caching strategy.

There is another limitation the docs describe. Let's say we have this tagged fetch (we cover tags below, but you probably know about them already):

fetch(url, { next: { tags: ['product-a'] } });

And we use it in 2 places products/a and products/promos. These 2 routes are statically rendered, that is prerended HTML and rsc. We update products/a with revalidateTag. This will update the data cache (the fetch with tag 'product-a') and the full route cache: .next/server/app/products/a.html and .next/server/app/products/a.rsc.

However, the prerendered products/promos page will not be revalidated. The data cache got updated but the prerendered route will still contain stale data! And that's a problem you can't fix. This is a big limitation when using revalidateTag.

Testing

Note: the examples are available on github.

`revalidatePath` in route handler (swr)

To run this test, we need a path:

// app/revalidate/path/swr/page.tsx

import Post from '@/components/Post';

export default function Page() {
  return (
    <>
      <Post postId={35} fetchOptions={{}} />
      <Post postId={36} fetchOptions={{ next: { revalidate: 1800 } }} />
      <Post postId={37} fetchOptions={{ cache: 'force-cache' }} />
    </>
  );
}

We reuse the <Post /> component that we used in earlier chapters. Note that we set cache and time based revalidation. This is to test if all the fetches get revalidated.

We are testing calling revalidatePath from a route handler. This route handler would get called from an external place, e.g. a CMS webhook. This is our route handler, where we call revalidatePath:

// app/revalidate/api/revalidatePath/route.ts
// mostly from example https://nextjs.org/docs/app/api-reference/functions/revalidatePath#route-handler

export async function GET(request: NextRequest) {
  const path = request.nextUrl.searchParams.get('path');

  if (path) {
    revalidatePath(path);
    return Response.json({ revalidated: true });
  }

  return Response.json({
    revalidated: false,
    message: 'Missing path to revalidate',
  });
}

Note that we get the path to revalidate not from a request body but from a searchParam: localApiEndpoint?path=pathToRevalidate. If there's a path we revalidate the path and return a response, else error response.

We will hit this endpoint directly from our browser. So paste url localhost:3000/revalidate/api/revalidatePath?path=/revalidate/path/swr in our browser url bar, hit enter. This will return us some json:

{"revalidated":true}

Note: Initially, I had written a separate route with a button to call this endpoint but that gave serious problems. Our route to revalidate was getting prefetched and saved in the browser cache (later more) and all my tests were failing because of this. To solve this, we call the endpoint directly and I added prefetch false to all the links in our examples overview page (home).

And let's run some tests.

[action]
  next build
  next start
  visit localhost:3000/revalidate/api/revalidatePath?path=/revalidate/path/swr
  get revalidated response
  visit /revalidate/path/swr (path we just revalidated)
  refresh page

[Expect]
  ✅ pass: Fresh content: the timestamp for all posts to have updated

Note: we already did an in depth test for SWR in the previous chapter. From now on, we will only rely on the displayed times of the posts in the front-end; to simplify these tests, e.g.

[TIMESTAMP]   [ID]  [TITLE]
17:24:31      35.   id nihil consequatur molestias animi provident

So, we proved that:

Calling revalidatePath from a route handlers revalidates SWR.
All the fetches in the route were updated, even though one was cached "force-cache" for infinity and another { revalidate: 1800 }. Calling revalidatePath invalidated them both.

So, everything went as expected, great.

One more test. We have our route /revalidate/path/swr with 3 posts: 35-37. We make a copy of this route with the same 3 posts: /revalidate/path/swr-copy. The goal is to test if this route copy gets revalidated when we revalidate the original route.

We talked about this earlier. revalidatePath will update the data cache for these posts and the full route cache for this path. Our copy should therefore not get revalidated ... because the full route cache for this route copy will not be revalidated. We test it:

// app/revalidate/path/swr-copy/page.tsx

export default function Page() {
  return (
    <>
      <Post postId={35} fetchOptions={{}} />
      <Post postId={36} fetchOptions={{ next: { revalidate: 1800 } }} />
      <Post postId={37} fetchOptions={{ cache: 'force-cache' }} />
    </>
  );
}

[action]
  we continue after steps in prev example
  visit /revalidate/path/swr-copy
  refresh page

[Expect]
  ✅ pass: The timestamps did not update

I hope this is clear. Note, a dynamic route copy would update because there would be no full route cache for that route.

`revalidatePath` in a server action (read your own writes)

We make a new route:

// app/revalidate/path/ryow/page.tsx

export default function Page() {
  return (
    <>
      <div className='mb-8'>
        <Post postId={38} fetchOptions={{}} />
        <Post postId={39} fetchOptions={{ next: { revalidate: 1800 } }} />
        <Post postId={40} fetchOptions={{ cache: 'force-cache' }} />
      </div>
      <RevalidatePathActionButton routeToRevalidate='/revalidate/path/ryow' />
    </>
  );
}

We're using a server action now. No need to simulate an external webhook call. This is the button:

// components/revalidate/RevalidatePathActionButton.tsx
'use client';

import { revalidatePathAction } from '@/app/revalidate/_actions/revalidatePathAction';
import { useActionState, useTransition } from 'react';

export default function RevalidatePathActionButton({
  routeToRevalidate,
}: {
  routeToRevalidate: string;
}) {
  const [state, dispatch] = useActionState(revalidatePathAction, null);
  const [isPending, startTransition] = useTransition();

  return (
    <div className='my-5 flex gap-4 items-center'>
      <button
        onClick={() => {
          startTransition(() => dispatch(routeToRevalidate));
        }}
        className='px-4 py-2 bg-blue-600 text-white rounded'
        disabled={isPending}
      >
        Revalidat{isPending ? 'ing' : 'e'}
      </button>

      {state && state.revalidated && (
        <p className='text-green-600 text-sm'>Revalidated</p>
      )}

      {state && !state.revalidated && (
        <p className='text-red-600 text-sm'>
          {state?.message || 'An error occurred while revalidating.'}
        </p>
      )}
    </div>
  );
}

Note that we use useActionState. We call the dispatch function directly from a button and therefore also need useTransition. The rest of the component is just a button and some status text.

Finally, this is our server action:

// app/revalidate/_actions/revalidatePathAction.ts

'use server';

type RevalidateStateT = {
  revalidated: boolean;
  message?: string;
} | null;

import { revalidatePath } from 'next/cache';

export async function revalidatePathAction(
  _prevState: RevalidateStateT,
  path: string,
) {
  if (path) {
    revalidatePath(path);
    return {
      revalidated: true,
    };
  }
  return {
    revalidated: false,
    message: 'Missing path to revalidate',
  };
}

When there is a path, revalidate it. Note that we need previous state because we call this action inside useActionState.

Great, we build and run it and here's read your own writes in action:

No need to write expects here, we see that it works. The 3 posts update with a small delay. We confirm read your own writes when using revalidatePath from a server action.

Where does the updated data come from? That is just some rsc payload files being sent over.

We also make a route copy without a button, to see what happens.

// app/revalidate/path/ryow-copy/page.tsx

import Post from '@/components/Post';

export default function Page() {
  return (
    <>
      <Post postId={38} fetchOptions={{}} />
      <Post postId={39} fetchOptions={{ next: { revalidate: 1800 } }} />
      <Post postId={40} fetchOptions={{ cache: 'force-cache' }} />
    </>
  );
}

Same as before, the copied route did not update, as expected.

Conclusion

revalidatePath is an easy revalidation solution for pages. There are limited ways to call it:

// specific url
revalidatePath('/blog/a');
// same as
revalidatePath('/blog/a', 'page'); // 'page' optional
// route pattern
revalidatePath('/blog/[postSlug]', 'layout'); // type parameter required: page | layout
// route handler
revalidatePath('/api/revalidate');

revalidatePath behaves differently depending on the context:

Route handler -> stale while revalidate
Server action -> read-your-own-writes

The upsides to revalidatePath are that it is quite easy to use. The downsides are:

It revalidates all fetches which can be undesirable.
It will not revalidate other routes that depend on the same revalidated data cache entries.

So, use it with care and probably avoid it in more complex situations.

Let's also take a step back here, to get a good overview. Since we're revalidating, there's a data cache. The page can be dynamic or static. If it's static then there will be a full route cache. Calling revalidatePath will revalidate the data cache and the full route cache (for that path). In a dynamic path, only the data cache will be revalidated.

Note: there is a nuclear option using revalidatePath: revalidatePath('/', 'layout'). This will revalidate everything. If you're using it, you're probably doing something wrong.

If you want to support my writing, you can donate with paypal.

Time based revalidation in Next

Peter Jacxsens — Thu, 16 Apr 2026 09:24:18 +0000

In time based revalidation, an expiry date is added to cache entries. However, when a cache entry expires (becomes stale) it does not update automatically. There are no server agents or CRON jobs that scan for expired cache entries to update them.

Compare this to an expired carton of milk in your fridge. The fact that it expired does not remove it from your fridge. There is no leprechaun doing it for you either.

How is a stale cache entry updated then? It happens at request time. When there is a request for a route, Next checks the full route cache for a match. It then checks the expiry date on this cached route. When it has expired, it will trigger an update.

How to set an expiry date on cache entries?

There are 2 ways to set time based revalidation:

Set it on the route using a Route Segment option:

export const revalidate = false | 0 | number;

Set it on an individual fetch, using the options object:

fetch(url, { next: { revalidate: false | 0 | number } });

The value of revalidate can be:

revalidate: false: cache, doesn't expire. Same as { cache: "force-cache" }.
revalidate: 0: do not cache. Same as { cache: "no-store" } -> no data cache + force dynamic render.
revalidate: number: cache for x seconds.

Time based revalidation of full route cache & data cache

Setting a fetch revalidate controls if and how long the fetch will be cached in the data cache. We just saw this in the previous paragraph.

0 -> no cache
false -> cache for infinity
number -> cache for x seconds

So, time based revalidation targets the data cache. Yes. But time based revalidation also targets the full route cache. Take an example. Imagine we have a route with 3 components: <Users />, <Todos /> and <Posts />. Each component fetches with a different revalidate value:

const users = await fetch(url, { revalidate: 100 }); // <Users />
const todos = await fetch(url, { revalidate: 200 }); // <Todos />
const posts = await fetch(url, { revalidate: 300 }); // <Posts />

Each component then renders out their thing (users.map(user => <>{user}</>)). So, that's our setup. A route with 3 components. All these fetches will be cached in the data cache, each with their own expiry date.

But, the route (that will be statically rendered) also gets an expiry date. Which one? The lowest of all revalidate settings in the route. Given this example, this should make sense.

100 + 1 seconds after build time, the user fetch (data cache) is already stale. But, this means that the full route cache for this route also has to be stale! The prerendered HTML and rsc now show stale data from the user fetch. The expiry date of the route has to equal the lowest revalidate in the route. That is the only way to guarantee that the full route cache is up to date with the data cache.

Back to our example. When a request happens for this route at 100 + 1 seconds:

Next checks the full route cache for this route, notices it's expired and statically renders the route again.
It will run each fetch again:
- fetch users: check data cache -> 100 -> expired -> new fetch
- fetch todos: check data cache -> 200 -> not expired (100 - 1s left) -> use cached data
- fetch posts: check data cache -> 300 -> not expired (200 - 1s left) -> use cached data
Next finishes rendering the route and saves it in cache (ISR).

At 200 + 1 seconds, a new request.

Next checks the full route cache for this route, notices it's expired and statically renders the route again.
It will run each fetch again:
- fetch users: check data cache -> 100 -> expired again -> new fetch
- fetch todos: check data cache -> 200 -> expired -> new fetch
- fetch posts: check data cache -> 300 -> not expired (100 - 1s left) -> use cached data
Next finishes rendering the route and saves it in cache (ISR).

At 300 + 1 seconds, a new request.

Next checks the full route cache for this route, notices it's expired and statically renders the route again.
It will run each fetch again:
- fetch users: check data cache -> 100 -> expired again -> new fetch
- fetch todos: check data cache -> 200 -> not expired (100 - 1s left) -> use cached data
- fetch posts: check data cache -> 300 -> expired -> new fetch
Next finishes rendering the route and saves it in cache (ISR).

Does this make sense? Time based revalidation sets expiry dates on the data cache and on the full route cache. When a data cache entry goes stale in a statically rendered route, then the data cache entry AND the route in the full route cache have to be updated. Rerendering the route does not automatically invalidate all data cache entries. Stale data cache entries will be fetched again. data cache entries that are not expired will be reused.

This is how revalidation works in routes that have data cache and full route cache. In routes that are dynamically rendered (no full route cache), revalidation will obviously not target the full route cache since there is none. Dynamic routes are freshly rendered at each request.

The next combination is full route cache but no data cache. For example:

export const revalidate = 100;

export default async function page() {
  // Database query or some ORM
  const users = await db.query('SELECT * FROM users');
  return <div>Hello world!</div>;
}

The important thing to notice: we're using a database or ORM here. We do not use the fetch API. This means: no data cache but also no fetch revalidate value. We use route segment option revalidation. This static route will expire after 100 seconds. The time based revalidation in this case targets only the full route cache.

The last possible combination is dynamic routes with no data cache. No cache, no revalidation needed. Time based revalidation doesn't work here.

Some tests

Note: the examples are available on github. Let's first take a look at a generated data cache file. We're going to reuse our <Post /> component we used in an earlier chapter:

// components/Post.tsx

type Props = {
  postId: number;
  fetchOptions: RequestInit;
};

export type PostT = {
  id: number;
  title: string;
};

export default async function Post({ postId, fetchOptions }: Props) {
  const data = await fetch(
    `https://jsonplaceholder.typicode.com/posts/${postId}`,
    fetchOptions,
  );
  const post: PostT = await data.json();
  // get date from headers
  const fetchDate = data.headers.get('date');
  const time = fetchDate
    ? new Date(fetchDate).toTimeString().slice(0, 8)
    : null;
  return (
    <div className='flex gap-2'>
      <div className='text-orange-400 mr-2'>{time}</div>
      <div className='font-bold'>{post.id}.</div>
      <div className='italic'>{post.title}</div>
    </div>
  );
}

And we load this inside this static route:

// app/revalidate/time/static/page.tsx

import Post from '@/components/Post';

export default function Page() {
  return <Post postId={20} fetchOptions={{ next: { revalidate: 1800 } }} />;
}

We set revalidate to 1800 seconds (30 mins) and we run next build.

The first interesting thing happens in the Next build log:

Route (app)                  Revalidate  Expire

├ ○ /revalidate/time/static         30m      1y

○  (Static)   prerendered as static content

The Revalidate value 30m (30 minutes) is what we set as revalidate in our fetch. This is the expiry date of the route in the full route cache. We talked about this earlier. This is equal to the lowest revalidate value in the entire route.

The expire value of 1y is something different. It is a default setting. It defines how long Next will keep a version of that page in cache if no one visits it. You can ignore this.

If we look into the generated data cache file we see this:

// ...
"headers": {
  "date":"Fri, 20 Mar 2026 17:11:02 GMT",
}
// ...
"url":"https://jsonplaceholder.typicode.com/posts/20",
"revalidate":1800
// ...

We run next start and visit this route: /revalidate/time/static:

Note how the time from the headers and the screenshot are the same. When we do a hard refresh of the page, they stay the same ... because they are cached. We are getting served the route from full route cache. This has a revalidate of 30 minutes. As long as this route doesn't expire, we keep getting served the same HTML and rsc.

We copy this in a dynamic route:

// app/revalidate/time/dynamic/page.tsx

import Post from '@/components/Post';

export const dynamic = 'force-dynamic';

export default function Page() {
  return <Post postId={20} fetchOptions={{ next: { revalidate: 1800 } }} />;
}

Note that we use the same id and fetchOptions as the static route. We run build and start and visit this new dynamic route. What happens? We see the same data. We are now in a dynamic route, this route was freshly rendered at request time. The data we're seeing is the cached fetch for post 20 in the data cache.

In our cache folder, we only find one file for post 20. So, we did cache post 20 and then reused it. When we do a hard refresh, the time stays the same. The fetch hits the data cache, finds a match that hasn't expired so Next serves from cache.

This is all as expected and should make sense.

Route segment option

Setting the route segment option revalidate means setting a default revalidation for the entire route. This default value will be inherited by any fetch that does not have an explicit revalidate or cache setting (fetch(url): the auto cache option). But, the route segment will not overwrite the value of fetches with an explicit revalidate or cache:

// inherits route revalidate
fetch(url);

// does not inherit route revalidate:
fetch(url, { cache: 'force-cache' });
fetch(url, { cache: 'no-store' });
fetch(url, { next: { revalidate: false | 0 | number } });

We write some more tests:

route -> { revalidate: number }

// app/revalidate/(route-revalidate)/number/page.tsx

export const revalidate = 100;

export default function Page() {
  return (
    <>
      <Post postId={21} fetchOptions={{}} />
      <Post postId={22} fetchOptions={{ cache: 'force-cache' }} />
      <Post postId={23} fetchOptions={{ next: { revalidate: 50 } }} />
    </>
  );
}

We expect:

This route to revalidate at 50 (lowest number) in build log -> ✅ passes
Fetch 21 to be cached at 100 (inherits because no explicit cache setting) -> ✅ passes
Fetch 22 to be cached at Infinity (no overwrite) -> ✅ +/- passes: not Infinity but 31536000 = 1 year (default max)
Fetch 23 to be cached at 50 (no overwrite) -> ✅ passes

Note: to set "✅ passes" I verified the data cache files manually.

route -> { revalidate: false }

The route revalidate false sets a default of force-cache without an expiry date, so Infinity.

// app/revalidate/(route-revalidate)/false/page.tsx

export const revalidate = false; // cache Infinity

export default function Page() {
  return (
    <>
      <Post postId={24} fetchOptions={{}} />
      <Post postId={25} fetchOptions={{ cache: 'force-cache' }} />
      <Post postId={26} fetchOptions={{ next: { revalidate: 50 } }} />
    </>
  );
}

We expect:

This route to revalidate at 50 (lowest number) in build log -> ✅ passes
Fetch 24 to be cached at Infinity (1 year) (inherits) -> ✅ passes
Fetch 25 to be cached at Infinity (1 year) (no overwrite) -> ✅ passes
Fetch 26 to be cached at 50 (no overwrite) -> ✅ passes

route -> { revalidate: 0 }

A route revalidate 0 is the equivalent of no-store:

// app/revalidate/(route-revalidate)/zero/page.tsx

export const revalidate = 0; // no-store

export default function Page() {
  return (
    <>
      <Post postId={27} fetchOptions={{}} />
      <Post postId={28} fetchOptions={{ cache: 'force-cache' }} />
      <Post postId={29} fetchOptions={{ next: { revalidate: 50 } }} />
    </>
  );
}

We expect:

This route to be dynamic -> ✅ passes
Fetch 27, 28, 29 not to be in data cache (The page hasn't rendered yet) -> ✅ passes

After starting up the server and visiting the page, we expect:

Fetch 27 not to be in data cache (inherits) -> ✅ passes
Fetch 28 to be cached at Infinity (1 year) (no overwrite) -> ✅ passes
Fetch 29 to be cached at 50 (no overwrite) -> ✅ passes

So, every test behaved as expected. Fetches with no explicit cache setting inherit the value from the route revalidate. Fetches that do have an explicit cache setting keep their setting.

Invalid

Note, there are absurd or invalid options too:

export const revalidate = 100;

export default async function Page() {
  await fetch(url, { next: { revalidate: 1000 } }); // 1000
  return <div>Hello world!</div>;
}

The route revalidation will trigger revalidation after 100 seconds. The route will be statically rerendered (ISR) but the fetch hasn't expired. So, Next will just reuse the cached data. And nothing changes. The newly rendered route will be the same as the previously rendered route. So, don't do this. This is an absurd config.

Another absurd example:

fetch(url, {
  cache: 'no-store',
  next: {
    revalidate: false,
  },
});

Setting no-store (don't cache) + revalidate: false (cache indefinitely) is ridiculous. eslint doesn't catch this but Next does. It throws a warning in dev mode: ⚠ Specified "cache: no-store" and "revalidate: false", only one should be specified. and ignores both.

Cache Invalidation Strategy: `stale while revalidate`

Time-based revalidation uses the cache invalidation strategy stale while revalidate. Let's say we have data that expired. User Bob makes a request for this data. Next reacts:

Checks the full route cache, finds a match and sees it's expired.
Serves Bob the current (stale) data. (this is the stale part in stale while revalidate)
In the background: (this is the revalidate part in stale while revalidate)
- If the route is static: fresh static render update (full route cache (ISR)) + refetching stale data (update data cache).
- If the route is dynamic: refetching stale data (update data cache).

The next user to make a request, will then receive 'fresh' data from cache.

So, in short. When a request hits stale/expired cache, Next will serve this cache and update in the background. Only the next request will receive fresh data. The advantage of using stale while revalidate is that requests are answered really fast (from cache). The disadvantage is that the first request will receive stale data. Isn't this bad? No. Use it when it doesn't matter. If receiving stale data does matter, you need to use a different caching strategy.

Testing SWR

It's time to actually test revalidation now. We use a simple example, trigger swr and look at the results.

// app/revalidate/time/swr/page.tsx

export default function Page() {
  return (
    <>
      <Post postId={30} fetchOptions={{ next: { revalidate: 60 } }} />
      <Post postId={31} fetchOptions={{ next: { revalidate: 600 } }} />
      <Post postId={32} fetchOptions={{ cache: 'force-cache' }} />
    </>
  );
}

We expect:

[action]
  next build

[Expect]
  ✅ pass: Route to be statically rendered and have expiry of 60s
  ✅ pass: Fetches 30 to be in data cache with revalidate 60
  ✅ pass: Fetches 31 to be in data cache with revalidate 600s
  ✅ pass: Fetches 32 to be in data cache with revalidate 1 year
  ✅ pass: Fetches 30-32 to have +/- same create date (headers.date)

[action]
  take note of create date of fetches
  next start
  visit route /revalidate/time/swr after 2 minutes

[expect]
  ✅ pass: Stale behavior in browser: old time still displayed for all fetches
  ✅ pass: Revalidated in cache: new create date for fetch 30
  ✅ pass: Fetch 31 and 32 not to have changed (unchanged create date)

[action]
  refresh page

[expect]
  ✅ pass: Time in browser for fetch 30 to have updated

[action]
  Wait 10 minutes
  refresh page

[expect]
  ✅ pass: Time in browser for fetch 30 and 31 to stay the same
  ✅ pass: Fetch 30 to have been updated in the background again: new create date
  ✅ pass: Fetch 31 to have been updated in the background: new create date
  ✅ pass: Fetch 32 not to have changed (unchanged create date)

[action]
  refresh page

[expect]
  ✅ pass: Time in browser for fetch 30 and 31 updated

So, everything worked as expected, SWR confirmed.

Summary

Revalidation means updating stale cache. In time based revalidation, cache becomes stale when it expires. When cache expires, it doesn't automatically update. This only happens at request time. When a request finds expired cache, it will serve this stale data and update the cache in the background. This is called stale while revalidate and all time based revalidation uses this mechanic.

Cache expiry is set via route revalidate or fetch revalidate. These can influence each other so be careful. A good hint is to limit the number of options (if possible):

Don't use revalidate: false, use force-cache.
Don't use revalidate: 0, use no-store.

This will leave you with a limited number of combinations:

fetch(url); // auto: no data cache
fetch(url, { cache: 'no-store' }); // no data cache + dynamic routes
fetch(url, { cache: 'force-cache' }); // data cache, doesn't expire
fetch(url, { next: { revalidate: 60 } }); // data cache for X seconds

// route segment option
export const revalidate = 60;

Time based revalidation can target both full route cache and data cache. In static routes, the lowest revalidate number in the route (either fetch revalidate or route revalidate) determines the expiry date of the route in the full route cache.

If you want to support my writing, you can donate with paypal.

Revalidating cache in NextJs: intro

Peter Jacxsens — Thu, 16 Apr 2026 09:23:53 +0000

We've covered 2 caches: data cache and full route cache. In most cases, these need to be updated periodically or at specific intervals. That is what revalidation does: it let's you update the fetch results - data cache - or the statically prerendered routes - full route cache. Note that there are 4 combinations here:

	data cache	no data cache
Dynamic render	data revalidation	no revalidation needed
Static render	data + route revalidation	route revalidation

When performing revalidation, we need to keep these combos in mind. But what does revalidation actually do?

data cache means that the result of a fetch you made was saved. We just talked about the data cache files and what they contained: headers, status, body,... Let's say we made a fetch to our CMS for a blog post with a certain ID. After a while we update this blogpost. However, this did not update our data cache in our app. So the state of our app is no longer up to date with the state of our CMS. Revalidating data cache means that we update the data cache with fresh data. To put it simply, we refetch the data and overwrite the existing cache. How we actually do this is for the next chapter.

Full route cache are all the routes that were statically prerendered at build time. Each route gets .html and .rsc files (and css and js, ...), we covered this in previous chapters. We just updated a blog post. If that blogpost was statically rendered, it's now no longer up to data. Revalidating full route cache means that we regenerate outdated routes. We rerender them into fresh html and rsc.

We regenerate -> Regeneration
The static routes -> Static Regeneration
But only parts, we don't rebuild the whole thing -> Incremental

The process of updating or refreshing the full route cache without rebuilding your entire project (no next build) is called Incremental Static Regeneration (ISR). Whenever we talk about rerendering or updating or refreshing or regenerating a statically rendered route, that is ISR!

Key Takeaway

Once more. We generated the full route cache at build time and started our server (next start). Incremental Static Regeneration is a mechanism that allows to update these prerendered routes, not at build time but at run time. The routes are statically rendered, server-side. We don't rebuild the whole cache, only certain parts (routes). revalidation tells us which parts to regenerate.

Revalidation in Next is updating stale cache. There are 2 types of revalidation:

Time based revalidation
On demand revalidation

These are both mechanisms to update stale cache. They do the same thing but do it differently. We cover this in the next chapters.

If you want to support my writing, you can donate with paypal.

Data cache in NextJs

Peter Jacxsens — Thu, 16 Apr 2026 09:22:55 +0000

Until now, we've only worked with "hard coded" components, no external APIs. Why? Because of Next data cache.

Data cache allows the result of external requests (using fetch) to be stored on the server. It also handles revalidation of this data. Data cache means that instead of making a request twice, the second request would just return the cached result of the first one. Of course, you can always opt out and force a fresh request every time.

data cache and full route cache are intertwined. They alter each others behavior, and it can become tricky to know what's happening or who's doing what. The goal of this chapter is to clear the fog.

Cache options

Next extends the native fetch api with options. One of these options is cache:

fetch('url', { cache: '...' });

There are 3 options:

{} (auto option) -> does not cache
{ cache: "no-store" } -> does not cache
{ cache: "force-cache" } -> caches

From before, we know that a route becomes dynamically rendered when Next encounters a dynamic element: cookies, headers, collection, draftmode, searchParams page prop or the dynamic fetch: { cache: "no-store" }.

So, out of our 3 options above, the dynamic fetch: { cache: "no-store" }, will make the route dynamic. The other 2 will not.

1. {} auto

fetch('url');

Omitting the cache property is called the auto option. By default, the fetch result will not be cached in the data cache. The auto option does not opt the route into dynamic rendering.

auto option + static route: Next will - at build time - make the fetch, render the result into HTML and rsc. The route is cached, the result is not cached (no data cache). Next serves the HTML and rsc but never makes the fetch again.
auto option + dynamic route: Next will - at request time - make the fetch, render the result into HTML and rsc but not cache the fetch result. For each request, the fetch will be made and the route will be rendered (into HTML and rsc).

This is as expected. The auto option does not interfere with static or dynamic rendering, they behave normally. When a route is static, it remains static, when a route is dynamic it remains dynamic. In a static route, the fetch is made only once at build time. In a dynamic route, the fetch is made for each request, at request time. The fetch result is never cached.

2. { cache: "no-store" }

Setting a fetch with no-store in Next is called a dynamic fetch. Data will never be cached, we always want fresh data. You can also use no-cache. It has the same result in Next.

A dynamic fetch is a dynamic element. This means that it turns your route into dynamic rendering: server-side at request time. So, when using no-store a route can never be static: no prerendered HTML or rsc at build time. The route is skipped and only rendered at request time. So, opting out of data cache, also opts you out of the full route cache.

This makes sense, when you always want fresh data, you cannot prerender it in advance, only "now", at request time.

3. { cache: "force-cache" }

Setting cache to force-cache means that Next will use the cache as much as possible. When using force-cache, Next will first check the data cache for a matching request. If there is none or if the match is stale, a new fetch will be made and cached.

force-cache does not force a route into dynamic rendering.

A static route with force-cache will remain static. At build time Next uses the cache or makes a new fetch and caches it. It then prerenders the HTML and rsc.
A dynamic route with force-cache will remain dynamic. At request time Next uses the cache or makes a new fetch and caches it. It will render HTML and rsc but it won't cache it.

Recap

auto and no-store do not cache fetch results, whereas force-cache does.
no-store forces a route into dynamic rendering. auto and force-cache do not.

Testing

Let's test this out and see how it looks. Note: the examples are available on github. We created a <Post > component.

// components/Post.tsx

type Props = {
  postId: number;
  fetchOptions: RequestInit;
};

export type PostT = {
  id: number;
  title: string;
};

export default async function Post({ postId, fetchOptions }: Props) {
  const data = await fetch(
    `https://jsonplaceholder.typicode.com/posts/${postId}`,
    fetchOptions,
  );
  const post: PostT = await data.json();
  // get date from headers
  const fetchDate = data.headers.get('date');
  const time = fetchDate
    ? new Date(fetchDate).toTimeString().slice(0, 8)
    : null;
  return (
    <div className='flex gap-2'>
      <div className='text-orange-400 mr-2'>{time}</div>
      <div className='font-bold'>{post.id}.</div>
      <div className='italic'>{post.title}</div>
    </div>
  );
}

This component:

Takes an id and fetchOptions ({ cache: ... }) as arguments
Makes a fetch to JSONPlaceholder posts.
Renders the date, id and title.

Note that we get the date from fetch response headers. This is the date the fetch was made. We'll be using this later on in the chapters on revalidation.

We create a static route and load a <Post /> with auto option and one with "force cache".

// app/cache/static/page.tsx

import Post from '@/components/Post';

export default function Page() {
  return (
    <div>
      <h2 className='font-bold mb-4'>Static route + cache options</h2>
      <Post postId={10} fetchOptions={{}} />
      <Post postId={11} fetchOptions={{ cache: 'force-cache' }} />
    </div>
  );
}

We create another route:

// app/cache/notstatic/page.tsx

import Post from '@/components/Post';

export default function Page() {
  return (
    <div>
      <h2 className='font-bold mb-4'>
        Dynamic element in static route + cache options
      </h2>
      <Post postId={12} fetchOptions={{ cache: 'no-store' }} />
    </div>
  );
}

Did you catch it? A fetch with "no-store" is a dynamic fetch, forcing the route into dynamic rendering. We also want to test static rendering so we had to put the dynamic fetch (no-store) in a separate route.

Finally, a dynamic route:

// app/cache/dynamic/page.tsx

import Post from '@/components/Post';

export const dynamic = 'force-dynamic';

export default function Page() {
  return (
    <div>
      <h2 className='font-bold mb-4'>Dynamic route + cache options</h2>
      <Post postId={13} fetchOptions={{}} />
      <Post postId={14} fetchOptions={{ cache: 'no-store' }} />
      <Post postId={15} fetchOptions={{ cache: 'force-cache' }} />
    </div>
  );
}

Again, the dynamic fetch will force the route into dynamic rendering so the route segment option dynamic is not necessary but we just wanted to make it explicit. It's fine.

For a better overview, here's a schematic of the routes we build:

/static route
  - fetch 10: auto
  - fetch 11: force-cache
/notstatic route
  - fetch 12: no-store
/dynamic route
  - fetch 13: auto
  - fetch 14: no-store
  - fetch 15: force-cache

So, what do we expect here when we run next build?

The static route should have been statically rendered into HTML and rsc and be in the full route cache. The notstatic and dynamic routes should not.
Fetch with auto cache should not be in data cache: posts 10 and 13 should not be in cache.
Fetch with "no-store" should not be in data cache: posts 12 and 14 should not be in cache.
Fetch with "force-cache" should be in data cache: posts 11 and 15 should be in cache.

Two notes here:

We're using different post ids here so other routes don't pollute the results.
Sometimes, depending on the environment, data cache persists between builds. To avoid this, I delete the .next folder before each build.

next build

The build log confirms the route expectations:

├ ƒ /cache/dynamic
├ ƒ /cache/notstatic
├ ○ /cache/static

○  (Static)   prerendered as static content
ƒ  (Dynamic)  server-rendered on demand

Also, In the .next/server/app/cache folder: static.html and static.rsc exist. The other routes are absent. What we confirmed here is that dynamic fetches do force routes into dynamic rendering. Great, on to the data cache.

Generated data cache files

A quick word about the actual data cache files. These are on the server (data cache is always on the server) in the build folder: .next/cache/fetch-cache. Each cached fetch has it's own file (hash name with no extension).

This is how the data cache entry for post 11 ("force-cache") looks like:

I made some markings, it contains:

Entire response object of the fetch: headers, status, url, and the serialized body.
Metadata from Next.js: revalidate and tags.

Don't worry about this, you don't have to know or understand this. Just remember, the entire response is saved and some Next meta data are saved. We can't read the actual data because they are serialized.

Note: I was also wondering how Next finds a match inside this cache but it's complicated and in the end it doesn't matter. Next knows how to do this and how to check if the data isn't stale. I'm leaving it at that.

Testing continued

We confirmed that static and dynamic rendering happened as expected. Now, we need to check the data cache.

/static route
  - fetch 10: auto
  - fetch 11: force-cache
/notstatic route
  - fetch 12: no-store
/dynamic route
  - fetch 13: auto
  - fetch 14: no-store
  - fetch 15: force-cache

We found posts 10 and 11 in the data cache, nothing else. This is unexpected. What happened?

The "no-store" fetches behaved as expected. 12 and 14 are not cached.
We did not expect the auto fetches (10 and 13) to be cached. But 10 was. Weird.
We expected the "force-cache" fetches 11 and 15 to have been cached. Only 11 was. 15 is missing.

We tackle this last one first. 15 is missing. Why? Because we didn't think this through. We only ran next build. But we have a dynamic route. Dynamic routes don't get rendered at build time, only at request time. We haven't made a request for the dynamic route so fetches 13-15 haven't been made yet.

next start

We visit our 3 test routes: /cache/static, cache/notstatic and /cache/dynamic and revisit the data cache folder. One new file was added: post 15 for the "force-cache" fetch in the dynamic route. This is as expected. We expect fetch 15 with "force-cache" to have been cached. Great, first problem fixed.

The "Auto" Mystery

The second problem. Fetch 10 with auto caching should not have been cached but it was. Why? Note, we ran the dynamic route. This route also has an auto fetch (13). However, this auto fetch was not added to the cache. So 13 behaved normally and this seems to be a problem with static rendering.

I couldn't figure it out, so I asked AI. This is how Gemini explained it:

In Next.js, during the build process (Static Site Generation), fetch requests are actually cached by default even if you use the auto setting. This is because Next.js needs to ensure that the static HTML it creates has data to show. If it didn't cache that "auto" fetch during the build, the static page would have nothing to display! This is why post 10 appeared in your folder, while post 13 (the dynamic one) did not.

Seems plausible but I can't verify this is correct. This sorta insinuates that during a render, fetches are made first and then the actual render is made. Maybe.

In any case, it doesn't really matter that much. In static rendering, the API is hit once and then the route is rendered into HTML and rsc. Only this full route cache is served. The endpoint isn't hit again (unless you revalidate). We will leave it at this.

Summary

We learned how to use data cache in Next using the cache option on the fetch API. We also saw how using a dynamic fetch (no-store) forces the entire route into dynamic rendering and took a quick peek at the data cache files. Lastly we ran some tests that - mostly - confirmed the theory.

This should give you a more grounded feel for the data cache mechanism in Next. In the following chapter, we look into revalidation.

If you want to support my writing, you can donate with paypal.

Static and dynamic rendering of client components

Peter Jacxsens — Thu, 16 Apr 2026 09:22:03 +0000

In the previous chapter, we looked into static and dynamic rendering. Rendering happens at route level and means that we run the functional components and use their return values. Each route gets rendered into a bunch of files (js, css, icons, images, fonts,...) but we're interested in these 2:

HTML file: <div>Hello world</div>, served at initial load.
rsc payload file: { "div", children: "Hello world" }, served at client side navigation.

Both static and dynamic rendering create these 2 files. Static rendering does it at build time, dynamic rendering does it at request time - using "fresh" data.

But, this process only describes routes made of server components. Rendering routes with client components works differently.

Client components

Client components are components that:

use hooks or custom hooks
have interactivity (event listeners)
use browser only API's like localStorage or geoLocation.

Any component that is not a client component is a server component in Next.

But, here's a question: Can a client component be statically prerendered?

From earlier, we know that dynamic rendering happens when a route has dynamic elements like headers, cookies, searchParams, connection, draftMode or dynamic fetch. Notice how the definition of dynamic rendering does NOT overlap with the definition of client components. So, yes? They can be rendered statically?

But there remains some confusion. How can a component that uses browser API's like localStorage be prerendered statically in an environment where window and localStorage don't exist? That is what we will explore in this chapter.

A simple example

Let's start with an example once again and just observe what happens. Note: the examples are available on github.

// components/client/ClientWithState.tsx

'use client';

import { useState, useEffect } from 'react';

export default function ClientWithState() {
  const [count, setCount] = useState(100);
  useEffect(() => {
    document.title = 'Updated title';
  }, []);

  const handler = () => {
    setCount((prev) => prev + 1);
  };

  return (
    <>
      <div>Count is {count}</div>
      <button
        onClick={handler}
        className='bg-lime-500 rounded px-2 py-1 text-black'
      >
        add 1
      </button>
    </>
  );
}

It's a simple counter component. We have state initiated with 100. The count is displayed and there's a button to increment the count. I also run useEffect to update the page title. We load <ClientWithState /> in a route with some server components we used in previous examples:

// app/static-client/page.tsx
export default async function Page() {
  return (
    <>
      <ClientWithState />
      <Header />
      <Main />
      <Footer />
    </>
  );
}

export default function Header() {
  return <header>***** Header *****</header>;
}

export default function Main() {
  return <main>***** Main *****</main>;
}

export default function Footer() {
  return <footer>***** Footer *****</footer>;
}

next build

The build confirms that /static-client route was prerendered as static content. So, it's possible to render client components statically. But let's take a look at the prerendered HTML and rsc files.

HTML

If we remove all the scripts, clean out the header and run prettier, this is what we get:

<!-- .next/server/app/static-client.html -->
<!doctype html>
<html lang="en">
  <head>
    <title>Caching in NextJS: examples</title>
  </head>
  <body>
    <div>
      Count is
      <!-- -->100
    </div>
    <button class="bg-lime-500 rounded px-2 py-1 text-black">add 1</button>
    <header>***** header *****</header>
    <main>***** main *****</main>
    <footer>***** footer *****</footer>
  </body>
</html>

At prerender, Next was able to initiate state and set count: <div>Count is 100</div>.
The button was rendered as HTML. No inline event handler to be seen. So button doesn't do anything.
The title tag is not "Updated title". Implying useEffect didn't run.

The big thing to notice here is that a client component can be rendered outside of the browser, during build time. The useState hook behaved as expected. This goes for most hooks but I'll show some more examples later.

rsc payload

We already know that it's hard to read rsc. It's not meant to be read but I want to show it at least once more:

// .next/server/app/static-client.rsc
// edited

d: (I[(67655, ['/_next/static/chunks/d975380482ceac7a.js'], 'default')],
  [
    (['$', '$Ld', null, {}],
    ['$', 'header', null, { children: '***** header *****' }],
    ['$', 'main', null, { children: '***** main *****' }],
    ['$', 'footer', null, { children: '***** footer *****' }]),
  ]);

We can make out an array with the 3 server components. They are the rendered result of the server components: HTML elements/nodes represented as JavaScript objects. (Don't worry, you don't need to know this)

But there's a fourth element, the first element in the array. That is a placeholder for the client component. It is linked via ID to the relative path to the js file on the first line. This path refers to another part of the Next build folder: .next/static. This folder is part of the js client bundle and will actually get send over to the browser. Here's that file:

Looks kinda familiar? That is our <ClientState /> component converted into plain js. (Still, no worries, you don't need to know this) But - and this is important - it's the actual component, not the rendered result of the component.

So, the rsc payload contains the rendered server components but not the rendered client component. Next did reserve a slot for the client component, a placeholder. This placeholder refers to a file, a js chunk that contains the actual client component, not the rendered result. This chunk was created at build time and is part of the js client bundle that the client (the browser) will download.

Quick recap

We ran next build and examined a route containing a client component. The route was prerendered statically in the Next build folder: an HTML and a rsc file.

The HTML file contained the rendered result (elements or nodes) of the server and client components. However, the client component was non interactive. The button didn't have an event listener.

The rsc file only contained rendered results of the server components. There was an open spot reserved for the client component, a placeholder. This placeholder referenced a static file, also in the Next build folder, that contained the actual client component, not a rendered result of said component.

The theory

In the previous chapter, we mentioned that these prerended route files have a different goal:

The HTML is served on first load: when first entering the app.
The rsc is served on client-side routing: internally navigating the app.

This is actually not 100% correct. When the route contains client components, the rsc file will be served both on first load and on client-side routing. To explain why, we need to understand:

How Next works in the browser on first load.
How Next handles route changes in the browser.

1. How a browser mounts Next on initial load

On initial load, after a request, the server sends over the HTML, rsc and a whole bunch of JavaScript (the js client bundle). The browser immediately displays the static HTML file (no event listeners or interactivity). Once the client bundle is loaded it will start up Next/React.

Client side, in the browser, Next/React:

Reads the rsc payload.
Hydrates:
- Grabs all the client components referenced in rsc.
- Virtually renders these client components (creates virtual DOM).
- "Syncs" the actual DOM (created from HTML file) with the virtual DOM by attaching event listeners and initializing state.
Runs useEffect.

This matches what we observed in our example. The important part is that both client and server components render once on the server. The client components are rendered again in the browser.

2. How Next handles client side routing

On client-side routing, Next will request the rsc payload for this new route from the server. Next then gathers all the changes it needs to make and swap it with the old content in a single paint. What are these changes?

The rsc file contains all the rendered server components. We saw this in the previous chapter: js objects that describe HTML elements. Next will convert (not render) all the rsc payload for server components into elements or nodes and insert them directly inside the DOM. No virtual DOM for server components.
The rsc file contains all references to client components. Next will render these client components virtually (virtual DOM) and then directly mount them into the DOM. There is no hydration here because there is no prerendered HTML for client components. That only happens once, on first load.

So, prerendered server components from the rsc payload and client side rendered client components are combined and replace the old content in one paint.

Some notes here. This is very complex, there are so many moving bits:

The rsc will probably get prefetched.
A loading.js file or suspense component may interfere in this flow.
Router cache also lives here. (See later)
Shared components like layout.tsx will be excluded from the page update.
...

So, on client side routing, the prerendered server components are fetched from the server. The client components are rendered client-side. Both are mounted in the DOM and replace the content from the old route.

Quick side note: static rendering prerenders the HTML and rsc at build time. Dynamic rendering renders the HTML and rsc at request time. Everything else is the same. Wether the HTML and rsc are fresh or old doesn't matter to the browser.

Rendering client components

We started this chapter with a question: Can a client component be statically prerendered?. By now you should know that it can. Client components mostly run in the client. That is why we call them client components. Server components never run on the client. Only the rendered result is sent to the client. That is why we call them server components.

Client components also render once on the server during build or request time. From an earlier example - <ClientState /> - we saw that Next is able to initiate state during static or dynamic rendering - outside of the browser. This is true for most hooks. Next will be able to prerender them. There is one weird one: useSearchParams, but we will look at that one later.

Aside from hooks and interactivity, components that use browser API's also need to be client components. This may seem a bit tricky at first, browser API's only live in the browser. So how can they be statically prerendered outside the browser? They can't.

Let's say we wanted to initialize state with a value from localStorage then this won't work (in Next):

// ❌ don't do this

export default function ClientWithBrowserAPI() {
  function initiateState() {
    const lscount = localStorage.getItem('lscount');
    return lscount ? Number(lscount) : 0;
  }
  const [count, setCount] = useState(initiateState);
  return <div>Count is {count}</div>;
}

This would error both in dev mode (⨯ ReferenceError: localStorage is not defined) and at build time (ReferenceError: localStorage is not defined). We know why. At build time (not in the browser), there is no window or window.localStorage. And that's the error. Correct approach would be:

// components/client/ClientWithBrowserAPI.rsc
'use client';

export default function ClientWithBrowserAPI() {
  const [count, setCount] = useState(0);
  useEffect(() => {
    const lsCount = localStorage.getItem('lsCount');
    if (lsCount !== null) {
      setCount(Number(lsCount));
    }
  }, []);
  return <div>Count is {count}</div>;
}

You probably knew this already. But now you understand why: useEffect doesn't run on static or dynamic rendering. That means that the prerendered HTML would be this: <div>count is 0</div>. useEffect only runs after the client component is rendered inside the browser. Inside the browser, useEffect has access to window.localStorage.

And that is how all browser API's should be used in Next: either inside useEffect or inside a handler function that only runs after an event.

So, yes, client components that use browser API's can be statically or dynamically rendered in Next. I hope you have a better feel for this now.

Why

We have thus far skipped the why. Why do we need static rendering? What's the point. We know what it is, but why do we need it? Gemini came up with a pretty good answer:

⚡ Blazing Speed (Performance): Because the HTML is pre-generated, it can be stored on a CDN (Content Delivery Network). This means when a user visits your site, the file is sent from a server physically close to them. There is no waiting for database queries or server-side logic.

🔍 Superior SEO: Search engine crawlers love static HTML. Since the content is already there the moment the bot "looks" at the page (no waiting for JavaScript to load), your site is much easier to index, which can lead to higher search rankings.

🛡️ Enhanced Security: Static files are just text. By reducing the amount of "live" code running on a server for every request, you significantly shrink the "attack surface" for hackers. There's no database to inject or server process to exploit on that specific request.

💸 Lower Costs & Scalability: Serving static files requires very little "compute" power. Your server won't break a sweat (or your budget) if you suddenly get 100,000 visitors, because you're just handing out pre-made files rather than building 100,000 pages from scratch.

I'm gonna leave it at that.

Closing

We now understand static and dynamic rendering of server and client components. Static rendering is what creates the full route cache.

There is something we left out. A hybrid in between static and dynamic rendering: incremental static regeneration. We will cover that in a later chapter but first, let's take a good and long look at data cache.

If you want to support my writing, you can donate with paypal.

Static and dynamic rendering and Full Route Cache

Peter Jacxsens — Thu, 16 Apr 2026 09:21:38 +0000

Static rendering means that routes are prerendered at build time. The result is cached and can be reused across requests. Static routes are fully cached in the Full Route Cache.
Dynamic rendering means that routes are rendered server-side at request time. The result is served to users but not cached.

These are the definition, the theory. In this chapter I will try to explain these concepts in a more grounded, practical way. Instead of sticking to theory, I'm going to start with simple examples and build from there. I'm hoping that this will help you gain a better understanding.

A simple example

Note: the examples are available on github.

Let's create a route and three components:

// app/static-example-route/page.tsx
export default function Page() {
  return (
    <>
      <Header />
      <Main />
      <Footer />
    </>
  );
}

export default function Header() {
  return <header>***** Header *****</header>;
}

export default function Main() {
  return <main>***** Main *****</main>;
}

export default function Footer() {
  return <footer>***** Footer *****</footer>;
}

This page would then look like this:

***** Header *****
***** Main *****
***** Footer *****

Deployment

In development, we run a dev server (next dev), but that is of no use here. Static and dynamic rendering are only relevant in production. We can do this locally too by first running next build and then next start. Note that when you deploy to an actual live server like Vercel, this server will also run these same commands.

next build: your app gets compiled into packages (this is the very short version; a lot happens here). Anything that happens here, happens at build time.
next start: the prepared packages start running on the server (a local server in our case). The server is now ready to receive requests: e.g. a user visiting a URL or an app making an API call. When the server does something after receiving a request, the server runs at request time. Anything that happens on the server (like rendering or data fetching) is server-side.

In the build step, Next looks at each route and decides if it should be rendered static or dynamic.

Rendering

But what is the rendering portion in the term "static" and "dynamic" rendering?

In our example, we have React components in TypeScript. Browsers can't read these directly. They need HTML, JS and CSS. Rendering means turning React components into HTML pages.

The difference between static and dynamic rendering is when the rendering happens. Static rendering happens at build time (when running next build), dynamic rendering happens at request time (after next start, when the server receives a request).

Dynamic example

To illustrate why we need dynamic and static rendering, we use a new example. We make a new route:

// app/dynamic-example-route/page.tsx

export default async function Page({
  searchParams,
}: PageProps<'/dynamic-example-route'>) {
  const resolvedSearchParams = await searchParams;
  return (
    <>
      <div>Hello {resolvedSearchParams.name}</div>
      <Header />
      <Main />
      <Footer />
    </>
  );
}

We made some small updates to our previous example. We added the searchParam page prop and a new line: <div>Hello {resolvedSearchParams.name}</div>. When visiting the route /dynamic-example-route?name=peter we now expect to see this on our page:

Hello peter
***** Header *****
***** Main *****
***** Footer *****

This is a dynamic route. It is rendered at request time. I cannot be rendered statically because at build time there is no request from a user. There is no search param (?name=peter).

Let's go over this again. At build time, Next takes a look at the route /dynamic-example-route. It checks all the components that make up the route. In the page component (/app/dynamic-example-route/page.tsx), Next encounters the searchParams page prop and decides this route cannot be statically rendered because there are no searchParams. Therefore this route becomes dynamically rendered.

The searchParams prop is not the only thing that forces a route to become dynamic. Here is the full list of APIs that trigger dynamic rendering:

cookies function
headers function
connection function (more later)
draftMode function
searchParams prop
unstable_noStore (legacy)
dynamic fetches: fetch with { cache: 'no-store' }

Cookies, headers and searchParams prop should be clear by now. We cover connection and dynamic fetches later. First, I want to go back for a bit.

Next build

Let's actually run next build locally now. The route /dynamic-example-route should be rendered dynamically because it uses the searchParams prop. The other route /static-example-route should render statically.

next build

First thing to note is the log in your terminal. Here is screenshot:

We're interested in the routes part. Route /dynamic-example-route has ƒ meaning it's a dynamic route. Route /static-example-route has ○, so static render.

We ran next build. The route /dynamic-example-route has not been rendered. This will only happen at request time when we start up the server and it receives a request. But, the other route - /static-example-route - has been rendered (prerendered). Where is it? In the packages Next just built and placed in the .next folder:

Most of the things in this build folder are unknown to me too, don't worry,it doesn't matter. It's under the hood React and Next stuff. What we are interested in is this subfolder: ./next/server/app. This holds all the routes for the Next app router. (There is also a folder pages for the old pages router).

Here's that app folder:

Notice that these are all files and folders that are named after our routes. By default we have routes

home
global-error
not-found

And we added the routes:

static-example-route
dynamic-example-route

Inside our ./next/server/app build folder: we are interested in the .html and .rsc files, ignore the folders. We can see static-example-route.html and static-example-route.rsc. These are our prerendered static files for route static-example-route.

The dynamic route dynamic-example-route is missing. There is no dynamic-example-route.html and no dynamic-example-route.rsc. This is as expected. Dynamic routes are not rendered at build time.

Prerendered files

next build statically rendered our static-example-route route. What did it render? An HTML file and an rsc payload file. Why?

The html file gets served on initial load. The initial load is when a user enters your app (e.g. when redirected by Google or by directly entering an URL in the address bar and hitting enter). On initial load, Next serves the prerendered html.

After the initial load, a user can navigate inside your app. We call this client-side routing. When going from one route to another inside our app, Next serves the .rsc file. This makes sense, Next is after all a Single Page App. No full page reloads on internal navigation.

Prerendered HTML

This is what the html file looks like:

It is fully optimized html and js, ready to be viewed inside the browser. It has links to js files, font preloading, meta and a title tags, favicon links, ...

But, when we remove all of the scripts and meta tags and run prettier, we can see what interests us:

Look familiar? That is exactly how our static-example-route should look like in html.

Prerendered .rsc

The rsc file: rsc stands for react server component payload: it's "a special data format, optimized for streaming". It's a bit like the DOM, where all the elements and nodes are represented inside a nested object. Here's the rsc for our static route:

Don't worry about this, you are not meant to read or understand this. I highlighted the text content from our components. Only thing to remember: our components were also prerendered into an .rsc file.

Earlier, we described rendering as turning React components into HTML pages. Having just looked at this rsc payload, we must expand that definition. Rendering is turning React components into HTML pages or into react server component payload. That is a JavaScript object that describes an HTML element.

A big caveat

All the components in our examples thus far have been server components. All the prerendering we looked into is how server components are prerendered. Client components work differently. We will explore this in the next chapter.

Recap

We ran next build. Next evaluated all the routes in our project. It came across the static-example-route route and rendered the route statically. Static because there are no dynamic elements. A static render means files were created including an html file for initial load and an rsc for client side routing. The dynamic route we created - dynamic-example-route - was skipped because it contained a dynamic element: searchParams.

We are now ready to go back to the definitions from the beginning of this chapter:

Static rendering means that routes are prerendered at build time. [...]
Dynamic rendering means that routes are rendered server-side at request time. [...]

Static and dynamic rendering happens at route level, not component level and it is Next that decides. A route will be dynamically rendered (server-side at request time) when Next encounters a dynamic element inside a component. Dynamic elements are:

cookies function
headers function
connection function
draftMode function
searchParams prop
unstable_noStore (legacy)
dynamic fetches: fetch with { cache: 'no-store' }

In any other case, the rendering will be static. That is, it is prerendered at build time. We looked at some of these prerendered files.

Dynamic rendering

Dynamic routes are not rendered at build time. They are rendered at request time. Only at request time do we have access to things like headers, cookies, searchParams or a (fresh) dynamic fetch.

What does dynamic rendering do? Exactly the same as static rendering. That is, create a lot of files, including an html file and an rsc file. It just does it at request time, using a fresh request. I can't show you these files since they are rendered server-side and are not saved.

Let's quickly look into connection and dynamic fetches, 2 of the dynamic elements the cause routes to be rendered dynamically.

Dynamic fetches

Using the fetch api in Next is a bit tricky:

Next.js extends the Web fetch() API to allow each request on the server to set its own persistent caching and revalidation semantics.

This caching of fetch() is actually a second form of caching Next provides called data cache. But that's for a later chapter. Right now, we are concerned with dynamic fetches. These are fetches that have the setting { cache: 'no-store' } as their second parameter:

let data = await fetch('https://api.vercel.app/blog', { cache: 'no-store' });

{ cache: 'no-store' } means no cache. We opt out. We don't want cached data. We want to go to this URL now and retrieve the latest data. Not some old, stale data.

For example: in a weather forecast app you would like the weather right now. Not the weather from a day or week ago. In an erp app you want to know the current state of your inventory. Is product X in my inventory right now because I need it. Stale data like "you had it last week" is quite useless.

Back to dynamic rendering. If Next encounters a dynamic fetch in a route, it will render the route dynamically. There will be no Full Route Cache for this route. Since we explicitly set cache to 'no-store', the fetch data won't be cached either. More on this later.

So, dynamic fetch -> dynamic render.

Connection

Next decides when to render statically or dynamically (headers, cookies, searchParams, dynamic fetch,...). You cannot force a route to be statically rendered expect by not using dynamic elements.

But, you can force a route to be dynamically rendered, by using connection(). Next gives 2 examples: Math.random() or new Date().

Let's say that for some reason, you need a random number in a component. But the route in the component has no dynamic elements. What happens, your random number becomes the same for everyone because the route will be statically rendered. To avoid this, use connection(). Using connection() will force the route to become dynamic.

The caching part

Back to the definitions:

Static rendering means that routes are prerendered at build time. The result is cached and can be reused across requests. Static routes are fully cached in the Full Route Cache.
Dynamic rendering means that routes are rendered server-side at request time. The result is served to users but not cached.

Static routes are fully cached. Dynamic routes are not cached. The cache for static routes is called Full Route Cache and it is one of the four caches that Next provides.

Note, caching is a mechanism. The prerendered content inside the .next/server/app folder (that we looked at earlier) is not the cache. It is prerendered content and this is what the caching mechanism serves. Every user will be served the same content.

Dynamic routes are not cached. The process of compiling routes into html or rsc happens server-side at request time. The result of this compiling is served to the user but not cached. This means that each user gets their very own server-side render.

Concluding

Static and dynamic rendering should now be concrete. It should also be clear how the process of static rendering leads to the Full Route Cache. Since there are no dynamic elements, every user gets served the same content. We prerender this content in advance during build time.

This is only part of the story. We left out client components. These behave differently during static and dynamic rendering. This is for our next chapter.

If you want to support my writing, you can donate with paypal.

Caching in NextJs

Peter Jacxsens — Thu, 16 Apr 2026 09:21:19 +0000

I've never fully grasped caching in NextJS. When I recently came across a youtube vid about cache components I found myself completely baffled. I couldn't quite place how things like dynamic rendering, server components, caching and use cache all fit together.

So, I decided to take a deeper dive into caching and document this into a series of posts. I have found in the past that writing about a subject forces you to delve deeper into the subject, leading to a better understanding.

My goal is to examine each type of caching mechanism in Next and try to really understand them using definitions, examples, tests, logs and even opening up the cache files. On top of that, I will also take a good look at these new-ish cache components.

Note from the future

While writing this, Next updated the docs on caching. So at various points, the Next 16 docs I was referring changed. To solve this I had to refer to the old Next 15 docs. These old docs are still valid in Next 16. However, caching in Next is changing. The fact that the docs updated quite drastically, is a reflection of that. This is also part of the subject of this series.

The first part of this series (2-11) will cover the old model of caching, after that I will look into the new one. Learning the old model is still valuable, even indispensable. So I would highly recommend not skipping it.

Types of caching

Let start with a quick overview. From the Next 15 docs, we learn that there are 4 types of caching in Next:

Request memoization
Data cache
Full route cache
Router cache

Each of these caching mechanisms have a different goal but they also:

Cache different things.
Live in a different place: server or client (browser).
Have a different lifespan.
Require different update strategies.

But don't worry about this second list right now, we will get into this later. For now, remember: 4 types of caching.

In the coming chapters, we will dive into each of these caching mechanisms. We start with Full Route Cache.

Mocking Next 16 useParams, useSearchParams, usePathname and useRouter in Jest

Peter Jacxsens — Wed, 26 Nov 2025 16:13:01 +0000

In this chapter we write a test for a component that uses router related hooks: useParams, useSearchParams, usePathname and useRouter. The code for this example is available on github.

This is the component we want to test:

// components/ListControls

'use client';

import { SortOrderT, validateSortOrder } from '@/lib/validateSortOrder';
import {
  useParams,
  usePathname,
  useRouter,
  useSearchParams,
} from 'next/navigation';

export default function ListControls() {
  const searchParams = useSearchParams();
  const pathName = usePathname();
  const router = useRouter();
  const params = useParams();

  function handleSort(newSortOrder: SortOrderT) {
    const newSearchParams = new URLSearchParams(searchParams.toString());
    newSearchParams.set('sortOrder', newSortOrder);
    router.push(`${pathName}?${newSearchParams.toString()}`);
  }

  const rawSortOrder = searchParams.get('sortOrder');
  const sortOrder = validateSortOrder(
    rawSortOrder ? { sortOrder: rawSortOrder } : {}
  );

  return (
    <>
      <h2 className='font-semibold mb-1'>Sort {params.listSlug}</h2>
      <div className='flex gap-2 mb-2'>
        <button
          className={`text-white px-2 py-1 rounded cursor-pointer ${
            sortOrder === 'asc' ? 'bg-amber-600' : 'bg-slate-600'
          }`}
          onClick={() => handleSort('asc')}
        >
          ascending
        </button>
        <button
          className={`text-white px-2 py-1 rounded cursor-pointer ${
            sortOrder === 'desc' ? 'bg-amber-600' : 'bg-slate-600'
          }`}
          onClick={() => handleSort('desc')}
        >
          descending
        </button>
      </div>
    </>
  );
}

Initial test setup

Let's start by doing the things we know already. This is our initial test file:

// components/__test__/ListControls.tsx

import { screen, render } from '@testing-library/react';
import ListControls from '../ListControls';
import { validateSortOrder, SortOrderT } from '@/lib/validateSortOrder';

jest.mock('@/lib/validateSortOrder');

describe('<ListControls />', () => {
  test('It renders', () => {
    (validateSortOrder as jest.Mock).mockReturnValue('asc');
    render(<ListControls />);
    // assertions here
  });
});

Note how we already mocked validateSortOrder and also added a return value to this mock.

setup render function

Because this will be a quite complex setup we're going to create a setup function that will be responsible for calling the jest render and all of the mocks. We can then call this function in each test instead of constantly repeating ourselves. We update our testfile like this:

// ... imports

jest.mock('@/lib/validateSortOrder');

function setupRender(
  validateSortOrderMockReturnValue: SortOrderT // 'asc' | 'desc'
) {
  (validateSortOrder as jest.Mock).mockReturnValue(
    validateSortOrderMockReturnValue
  );
  render(<ListControls />);
}

describe('<ListControls />', () => {
  test('It renders', () => {
    setupRender('asc');
    // assertions here
  });
});

We can take this even a step further. In our tests, we will constantly be testing our dom elements. So, we will include those in this setup function:

function setupRender(
  validateSortOrderMockReturnValue: SortOrderT // 'asc' | 'desc'
) {
  (validateSortOrder as jest.Mock).mockReturnValue(
    validateSortOrderMockReturnValue
  );
  render(<ListControls />);
  const heading = screen.getByRole('heading', { level: 2 });
  const buttonAsc = screen.getByRole('button', { name: /ascending/i });
  const buttonDesc = screen.getByRole('button', { name: /descending/i });

  return {
    heading,
    buttonAsc,
    buttonDesc,
  };
}

We can then retrieve our elements like this:

const { heading, buttonAsc, buttonDesc } = setupRender('asc');

next/navigation

If we try running this test as it stands now, the test will just crash. When mounting a component with React Testing Library, there is no React router. This means that all the router related hooks will fail. That is the first issue we need to deal with.

We will first mock all the hooks that we use from next/navigation:

import {
  useSearchParams,
  useParams,
  usePathname,
  useRouter,
} from 'next/navigation';

jest.mock('next/navigation');

This is good because it will no longer try to reach the actual router but it will call the mocks. But, we still get errors.

mocking useSearchParams

When we try to mount <ListControls /> in the current setup we will get this error:

TypeError: Cannot read properties of undefined (reading 'get')

This error is cause by this line in <ListControls />:

const searchParams = useSearchParams();
// ...
const rawSortOrder = searchParams.get('sortOrder');

Quick recap, useSearchParams returns a ReadonlyURLSearchParams interface. But since we mocked the useSearchParams() hook, it now returns undefined. This means we are trying to read .get on undefined and that is what the error is telling us.

To solve this, we need to return some values from our useSearchParams mock: a get (and toString) property. This is how we do that:

(useSearchParams as jest.Mock).mockReturnValue({
  get: () => {},
  toString: () => {},
});

But this leaves us with another problem. This is some code from our <ListControls /> component:

const rawSortOrder = searchParams.get('sortOrder');
const sortOrder = validateSortOrder(
  rawSortOrder ? { sortOrder: rawSortOrder } : {}
);

In our mocked test, rawSortOrder will now equal undefined. We mocked validateSortOrder so it doesn't matter what we call it with. But, maybe, we do want to validate that the get method was called. Maybe.

How do we do that?

expect(useSearchParams).toHaveBeenCalled();

is a test for this:

const searchParams = useSearchParams();

This won't work:

// error
expect(useSearchParams.get).toHaveBeenCalled();

The solution here is to write a new jest mock function and pass that as value for the get property.

const getMock = jest.fn();

(useSearchParams as jest.Mock).mockReturnValue({
  get: getMock,
  toString: () => {},
});

And then we can write this assertion:

// pass
expect(useSearchParams).toHaveBeenCalled();
expect(getMock).toHaveBeenCalledWith('sortOrder');

We could mock a return value from getMock but that would be pointless since we also mocked validateSortOrder. But, we have to do that for the toString method. This is the code from our <ListControls /> component:

const searchParams = useSearchParams();
const pathName = usePathname();
const router = useRouter();
const params = useParams();

function handleSort(newSortOrder: SortOrderT) {
  const newSearchParams = new URLSearchParams(searchParams.toString());
  newSearchParams.set('sortOrder', newSortOrder);
  router.push(`${pathName}?${newSearchParams.toString()}`);
}
//...

As you can see, we need this part: searchParams.toString(). So, we just repeat what we did earlier and make a toStringMock.

const getMock = jest.fn();
const toStringMock = jest.fn();

(useSearchParams as jest.Mock).mockReturnValue({
  get: getMock,
  toString: toStringMock,
});

There is something that might confuse you here. We create a new URLSearchParams and then use the set method on this. Shouldn't we mock this?

No! This is core javascript and we don't need to test that. We mocked useSearchParams because it doesn't work in React Testing Library. But directly calling new URLSearchParams works just fine.

Back to our toString mock. We do need a return value from this mock to perform some tests. We want tests with different return values, so we'll update our setupRender helper function:

function setupRender(
  validateSortOrderMockReturnValue: SortOrderT, // 'asc' | 'desc'
  toStringMockReturnValue: string // f.e. 'sortOrder=asc&color=red'
) {
  (validateSortOrder as jest.Mock).mockReturnValue(
    validateSortOrderMockReturnValue
  );
  // add return value
  (toStringMock as jest.Mock).mockReturnValue(toStringMockReturnValue);
  render(<ListControls />);
  const heading = screen.getByRole('heading', { level: 2 });
  const buttonAsc = screen.getByRole('button', { name: /ascending/i });
  const buttonDesc = screen.getByRole('button', { name: /descending/i });

  return {
    heading,
    buttonAsc,
    buttonDesc,
  };
}

Can we actually run a test now? No, it still breaks. Also, we don't have assertions yet.

More mocks

We already mocked all of our hooks:

import {
  useSearchParams,
  useParams,
  usePathname,
  useRouter,
} from 'next/navigation';

jest.mock('next/navigation');

But we need to add some more return values to these mocks. usePathname and useParams are easy. We just hardcode a return value on them:

(usePathname as jest.Mock).mockReturnValue('/test/route');
(useParams as jest.Mock).mockReturnValue({ listSlug: 'mockSlug' });

useRouter is a bit more tricky because we use the push method on it. Also, we would like to know it was called. Luckily, we already know how to do this:

const pushMock = jest.fn();

(useRouter as jest.Mock).mockReturnValue({
  push: pushMock,
});

Testing the setup

This is the current state of our testfile:

// components/__test__/ListControls.test.tsx

import { screen, render } from '@testing-library/react';
import ListControls from '../ListControls';
import { validateSortOrder, SortOrderT } from '@/lib/validateSortOrder';
import {
  useSearchParams,
  useParams,
  usePathname,
  useRouter,
} from 'next/navigation';

jest.mock('@/lib/validateSortOrder');
jest.mock('next/navigation');

const getMock = jest.fn();
const toStringMock = jest.fn();

(useSearchParams as jest.Mock).mockReturnValue({
  get: getMock,
  toString: toStringMock,
});

(usePathname as jest.Mock).mockReturnValue('/test/route');
(useParams as jest.Mock).mockReturnValue({ listSlug: 'mockSlug' });

const pushMock = jest.fn();

(useRouter as jest.Mock).mockReturnValue({
  push: pushMock,
});

function setupRender(
  validateSortOrderMockReturnValue: SortOrderT, // 'asc' | 'desc'
  toStringMockReturnValue: string // f.e. sortOrder=asc&color=red
) {
  (validateSortOrder as jest.Mock).mockReturnValue(
    validateSortOrderMockReturnValue
  );
  (toStringMock as jest.Mock).mockReturnValue(toStringMockReturnValue);
  render(<ListControls />);
  const heading = screen.getByRole('heading', { level: 2 });
  const buttonAsc = screen.getByRole('button', { name: /ascending/i });
  const buttonDesc = screen.getByRole('button', { name: /descending/i });
  return {
    heading,
    buttonAsc,
    buttonDesc,
  };
}

describe('<ListControls />', () => {
  test('It renders', () => {
    const { heading, buttonAsc, buttonDesc } = setupRender(
      'asc',
      'sortOrder=asc'
    );
    // assertions here
  });
});

And it works, the setup doesn't error. Now it's time to start writing assertions.

It renders

// passes
test('It renders', () => {
  const { heading, buttonAsc, buttonDesc } = setupRender(
    'asc',
    'sortOrder=asc'
  );
  expect(heading).toHaveTextContent(/Sort mockSlug/i);
  expect(buttonAsc).toBeInTheDocument();
  expect(buttonDesc).toBeInTheDocument();
});

It calls some mocks

// passes
test('It calls some mocks', () => {
  setupRender('asc', 'sortOrder=asc');
  expect(useSearchParams).toHaveBeenCalledTimes(1);
  expect(useParams).toHaveBeenCalledTimes(1);
  expect(usePathname).toHaveBeenCalledTimes(1);
  expect(useRouter).toHaveBeenCalledTimes(1);
  expect(getMock).toHaveBeenCalledWith('sortOrder');
  // only when button is pushed
  expect(toStringMock).not.toHaveBeenCalled();
  expect(pushMock).not.toHaveBeenCalled();
});

It renders the buttons with the correct class

test('When sortOrderMock returns "asc" the buttonAsc is active', () => {
  const { buttonAsc, buttonDesc } = setupRender(
    'asc',
    'sortOrder=asc&color=red'
  );
  expect(buttonAsc).toHaveClass('bg-amber-600');
  expect(buttonAsc).not.toHaveClass('bg-slate-600');
  expect(buttonDesc).toHaveClass('bg-slate-600');
  expect(buttonDesc).not.toHaveClass('bg-amber-600');
});

test('When sortOrderMock returns "desc" the buttonDesc is active', () => {
  const { buttonAsc, buttonDesc } = setupRender(
    'desc',
    'sortOrder=asc&color=red'
  );
  expect(buttonDesc).toHaveClass('bg-amber-600');
  expect(buttonDesc).not.toHaveClass('bg-slate-600');
  expect(buttonAsc).toHaveClass('bg-slate-600');
  expect(buttonAsc).not.toHaveClass('bg-amber-600');
});

user events

To test that our buttons actually work, we need to edit our setup. We add the user-event package:

npm i -D @testing-library/user-event

and import it into our test file:

import userEvent from '@testing-library/user-event';

Testing buttons clicks

describe('Testing user events', () => {});
test('It calls pushMock with the correct values when the buttons are clicked and initial sortOrder="asc"', async () => {
  const user = userEvent.setup();
  const { buttonAsc, buttonDesc } = setupRender('asc', 'sortOrder=asc');
  expect(toStringMock).not.toHaveBeenCalled();
  expect(pushMock).not.toHaveBeenCalled();
  await user.click(buttonAsc);
  expect(toStringMock).toHaveBeenCalled();
  expect(pushMock).toHaveBeenCalledWith('/test/route?sortOrder=asc');
});

The last assertion is where all our work comes together and it is a complex thing to run in your head.

We called handleSort with param 'asc' by clicking the button.
handleSort runs and creates newSearchParams.
In our setupRender function in the test file, we set a return value to toString: 'sortOrder=asc'. So, we expect newSearchParams to have this value (but we can't test this).
We overwrite sortOrder to 'asc'. So it stays the same.
We push router (we test this) with the value:
pathName: we mocked this to be '/test/route'.
newSearchParams.toString() which we expect to be 'sortOrder=asc'.

// passes
expect(pushMock).toHaveBeenCalledWith('/test/route?sortOrder=asc');

If you're feeling a bit overwhelmed by this, that is fine. You need to be very familiar with <ListControls /> and also need to be very focused to fully understand this. Right now, I had to spend several minutes to evaluate if calling setupRender('desc', ...) was necessary (it's not).

Quick note, we're not actually changing the route here (and we can't). So testing if the button classes 'updated' would be pointless ... because they don't change.

We're mostly done. Inside this same test, we need to check a click on buttonDesc.

await user.click(buttonDesc);
expect(toStringMock).toHaveBeenCalledTimes(2);
expect(pushMock).toHaveBeenCalledWith('/test/route?sortOrder=desc');

Finally, we need 2 more tests. One with the return value for toStringMock set to sortOrder=desc and then one with an extra searchParam to check it didn't get overwritten.

test('It calls pushMock with the correct values when the buttons are clicked and initial sortOrder="desc"', async () => {
  const user = userEvent.setup();
  const { buttonAsc, buttonDesc } = setupRender('asc', 'sortOrder=desc');
  expect(toStringMock).not.toHaveBeenCalled();
  expect(pushMock).not.toHaveBeenCalled();
  await user.click(buttonAsc);
  expect(toStringMock).toHaveBeenCalled();
  expect(pushMock).toHaveBeenCalledWith('/test/route?sortOrder=asc');
  await user.click(buttonDesc);
  expect(toStringMock).toHaveBeenCalledTimes(2);
  expect(pushMock).toHaveBeenCalledWith('/test/route?sortOrder=desc');
});

test('It does not overwrite other searchParams', async () => {
  const user = userEvent.setup();
  const { buttonAsc, buttonDesc } = setupRender(
    'asc',
    'sortOrder=asc&color=red'
  );
  await user.click(buttonAsc);
  expect(pushMock).toHaveBeenCalledWith('/test/route?sortOrder=asc&color=red');
  await user.click(buttonDesc);
  expect(pushMock).toHaveBeenCalledWith('/test/route?sortOrder=desc&color=red');
});

All tests pass. Great. But there is one tiny little case we haven't tested. Using the use hook in client components.

use hook

Quick reminder. Client components cannot be async. If we have a page route component page.tsx that is a client component and we want to read the async params or searchParams page props on these, we need to use the use hook.

Here is an example (as simple as possible):

// app/list2/[listSlug]/page.tsx

'use client';

import { use } from 'react';

export default function SyncUsePage({
  params,
  searchParams,
}: PageProps<'/list/[listSlug]'>) {
  const resolvedParams = use(params);
  const resolvedSearchParams = use(searchParams);
  return (
    <div>
      <h2>SyncUsePage</h2>
      <div data-testid='params'>{resolvedParams.listSlug}</div>
      <div data-testid='searchParams'>{resolvedSearchParams.sortOrder}</div>
    </div>
  );
}

So, it's a page component, a client component and it receives params (listSlug) and searchParams (sortOrder) that we print so we can test them. How do we test this?

Well, at this point I started writing the test and discovered it can't be done. A page route that receives async parameters, that' a Next thing, not a React thing and React Testing Library can't handle it. It just keeps throwing errors about async this, act() that. I can't make it work. (nor could any AI)

Conclusion

Since Next 16, both the params and searchParams are async. This means you have to await them and when writing tests, you need to mock them as a promise. Easy.

All the router related hooks like useSearchParams, useParams, usePathname and useRouter itself, are very handy but can be quite tricky in tests. The solution is to return objects from these mocked hooks, containing the properties you need. And to keep your focus.

If you want to support my writing, you can donate with paypal.

DEV Community: Peter Jacxsens

Using Suspense in NextJs

static vs dynamic rendering

Suspense

Are we - partially prerendering - yet?

useSearchParams hook

Conclusion

Router cache and request memoization

Router cache

Duration

Invalidation

Some closing notes

Request memoization

Some notes

Little test

Cache and unstable_cache

Closing

Incremental Static Regeneration (ISR)

An example

Run build

next start

Some improvements

Blog home

Blog post

ISR setup

Onwards

revalidateTag & updateTag In NextJs

Create a tag

updateTag

revalidateTag

Full route cache

revalidateTag(tag, "max")(swr) in a static route

revalidateTag(tag, {expire: 0})(RYOW) in a static route

updateTag()(RYOW) in a server action

Summary

Some notes

On demand revalidation in Nextjs

RevalidatePath

Cache invalidation mechanisms

read-your-own-writes

stale while revalidate

More limitations

Testing

revalidatePath in route handler (swr)

revalidatePath in a server action (read your own writes)

Conclusion

Time based revalidation in Next

How to set an expiry date on cache entries?

Time based revalidation of full route cache & data cache

Some tests

Route segment option

route -> { revalidate: number }

route -> { revalidate: false }

route -> { revalidate: 0 }

Invalid

Cache Invalidation Strategy: stale while revalidate

Testing SWR

Summary

Revalidating cache in NextJs: intro

Key Takeaway

Data cache in NextJs

Cache options

1. {} auto

2. { cache: "no-store" }

3. { cache: "force-cache" }

Recap

Testing

Generated data cache files

Testing continued

The "Auto" Mystery

Summary

Static and dynamic rendering of client components

Client components

A simple example

HTML

rsc payload

Quick recap

The theory

1. How a browser mounts Next on initial load

2. How Next handles client side routing

`read-your-own-writes`

`stale while revalidate`

`revalidatePath` in route handler (swr)

`revalidatePath` in a server action (read your own writes)

Cache Invalidation Strategy: `stale while revalidate`