Incremental Static Regeneration (ISR) Not Functioning as Expected in Next.js 15

[samstr]

Link to the code that reproduces this issue

https://github.com/samstr/isr-demo-nextjs15

To Reproduce

NextJS 14 Demo: https://github.com/samstr/isr-demo-nextjs14
NextJS 15 Demo: https://github.com/samstr/isr-demo-nextjs15

1. Clone demo repo (isr-demo-nextjs14)
2. npm install
3. npm run build
4. Go to http://localhost:3000/ and click the example links

Current vs. Expected behavior

The expected behavior is for pages that implement ISR should be cached for the time specified using the revalidate const.

In NextJS14 this works, but in NextJS 15 I can't seem to get the same behavior.

The npm run build output treats the route differently.

NextJS 14

NextJS 15

I understand that NextJS 15 introduced a new 'uncached by default' concept for route handlers and fetch requests etc, but I didn't think that was related to server rendered pages that are using revalidate.

Provide environment information

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 23.6.0: Mon Jul 29 21:13:04 PDT 2024; root:xnu-10063.141.2~1/RELEASE_ARM64_T6020
  Available memory (MB): 98304
  Available CPU cores: 12
Binaries:
  Node: 18.18.0
  npm: 9.8.1
  Yarn: N/A
  pnpm: 7.22.0
Relevant Packages:
  next: 15.0.2 // Latest available version is detected (15.0.2).
  eslint-config-next: 15.0.2
  react: 19.0.0-rc-02c0e824-20241028
  react-dom: 19.0.0-rc-02c0e824-20241028
  typescript: 5.6.3
Next.js Config:
  output: N/A

Which area(s) are affected? (Select all that apply)

Not sure

Which stage(s) are affected? (Select all that apply)

next dev (local), next build (local), next start (local), Vercel (Deployed)

Additional context

No response

[astrodomas]

Appears to not be working with 15.0.4-canary.31 aswell.

[KraKeN-47]

The regression appears to happened at next@15.0.0-canary.104

[astrodomas]

@leerob @delbaoliveira is it me or this section of the docs is a bit confusing? docs:

@samstr however, this is the correct example:

export const revalidate = 10;

export const dynamicParams = true;
export const dynamic = 'force-static';
export async function generateStaticParams() {
  return [];
}
...

[leerob]

I believe we're talking about different things. That docs page is saying "statically render them the first time they're visited". Hence, the array is empty and they are not prerendered during the build.

The default value for dynamicParams is true, so that isn't explicitly needed. That docs page doesn't also explicitly require using ISR – you can, if you want, but you don't need to. As it is written, it would generate the page, but then never revalidate it's contents after the fact. This has sometimes been referred to as "incremental static generation" (note, not re generation).

[astrodomas]

I believe we're talking about different things. That docs page is saying "statically render them the first time they're visited". Hence, the array is empty and they are not prerendered during the build.

The default value for dynamicParams is true, so that isn't explicitly needed. That docs page doesn't also explicitly require using ISR – you can, if you want, but you don't need to. As it is written, it would generate the page, but then never revalidate it's contents after the fact. This has sometimes been referred to as "incremental static generation" (note, not re generation).

Maybe I didn't understand your statement however, the confusion I'm getting here is why do we need to use force-static together with generateStaticParams that returns an empty array? On next v14, we didn't need to do that generateStaticParams that returns an empty array was enough. What changed? And maybe then this should be better reflected in the docs?

export const dynamic = 'force-static';
export async function generateStaticParams() {
  return [];
}

The provided example achieves the authors requested behaviour by adding dynamic = 'force-static'

export const revalidate = 10;

export const dynamicParams = true;
export const dynamic = 'force-static';
export async function generateStaticParams() {
  return [];
}

[leerob]

Your code snippets there don't make sense to me – both have the dynamic option, and as mentioned, the other options like dynamicParams and revalidate are separate. Could you clarify?

[astrodomas]

Your code snippets there don't make sense to me – both have the dynamic option, and as mentioned, the other options like dynamicParams and revalidate are separate. Could you clarify?

The ISR docs provided example fetches posts and provides a couple of slugs during build. However, this raised github issue is talking about an example where you would pass an empty array to generateStaticParams.

Also, the docs example is broken as of next v15 (await params needed). However, consider the docs example:

interface Post {
  id: string;
  title: string;
  content: string;
}

// Next.js will invalidate the cache when a
// request comes in, at most once every 60 seconds.
export const revalidate = 60;

// We'll prerender only the params from `generateStaticParams` at build time.
// If a request comes in for a path that hasn't been generated,
// Next.js will server-render the page on-demand.
export const dynamicParams = true; // or false, to 404 on unknown paths

export async function generateStaticParams() {
  const posts: Post[] = await fetch("https://api.vercel.app/blog").then((res) =>
    res.json()
  );
  return posts.map((post) => ({
    id: String(post.id),
  }));
}

export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const post: Post = await fetch(`https://api.vercel.app/blog/${id}`).then(
    (res) => res.json()
  );
  return (
    <main>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
    </main>
  );
}

We refactor this to achieve ISR on demand with regeneration based on the issue ticket:

// Next.js will invalidate the cache when a
// request comes in, at most once every 60 seconds.
export const revalidate = 60;

// We'll prerender only the params from `generateStaticParams` at build time.
// If a request comes in for a path that hasn't been generated,
// Next.js will server-render the page on-demand.
export const dynamicParams = true; // or false, to 404 on unknown paths

export async function generateStaticParams() {
  return [];
}

export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  return (
    <main>
      <h1>{id}</h1>
      <h2>{Date.now()}</h2>
    </main>
  );
}

The 2nd snippet does not work on next v15- we get ƒ (Dynamic) server-rendered on demand output on build, when on next v14 the 2nd snippet worked as expected - (SSG) prerendered as static HTML.

However, adding export const dynamic = 'force-static' to the 2nd snippet - fixes this. Getting ○ (Static) prerendered as static content on build output and works as expected - html is getting regenerated on demand after the specified revalidation period.

So again, the question is - is it an issue from the nextjs v15 side, a docs confusion or is this a misused configuration with the desired output?

P.S tested with latest canary

[leerob]

Good question. I was wrong, this did change with v15 with the caching changes:

You must return an empty array from generateStaticParams or utilize export const dynamic = 'force-static' in order to revalidate (ISR) paths at runtime.

Source: https://nextjs.org/docs/app/api-reference/functions/generate-static-params

So, this is working as expected and documented, but should be in our upgrade guide 💯

[leerob]

Docs will be updated with the next release for the params issue: #73088

[astrodomas]

Good question. I was wrong, this did change with v15 with the caching changes:

You must return an empty array from generateStaticParams or utilize export const dynamic = 'force-static' in order to revalidate (ISR) paths at runtime.

Source: https://nextjs.org/docs/app/api-reference/functions/generate-static-params

So, this is working as expected and documented, but should be in our upgrade guide 💯

I'd say this or is a bit confusing, because generateStaticParams that returns an empty array, explicitly requires export const dynamic = force-static as per my code example. So might it be that generateStaticParams is broken as of next v15? Can you confirm this works as expected?
Because as I understand the current docs
You can achieve on-demand ISR with:

export const revalidate = 10;
export const dynamicParams = true;
export async function generateStaticParams() {
  return [];
}

OR

export const dynamicParams = true;
export const revalidate = 10;
export const dynamic = 'force-static';