Incremental Static Regeneration - docs update explaining surprising behavior

[karlkeefer]

The requirement to export a generateStaticParams to get static cache behavior after build time was really surprising behavior for me, and I think others:

• App router : ISR always regenerates dynamic routes even when called with same params #62195 (comment)
• Support Incremental Full Route Cache on Dynamic Segments #57961 (reply in thread)

Potentially this is a bug, and not something that should be fixed with documentation?
I don't understand next.js caching enough to make that determination, so instead I'm proposing these changes to docs which might be encountered by folks who are surprised by this cache behavior.

One point in favor of this being a bug: The CLI reports that a route is SSG enabled in the build output, but doesn't actually cache post-build page renders if this export is missing.

@awinogrodzki made a demo repo showing this behavior, as described here.

[ijjk]

Allow CI Workflow Run

• approve CI run for commit: c0505af

Note: this should only be enabled once the PR is ready to go and can only be enabled by a maintainer

[samcx]

Thank you for submitting a PR!

.

One point in favor of this being a bug: The CLI reports that a route is SSG enabled in the build output, but doesn't actually cache post-build page renders if this export is missing.

Good callout! We need to I think we need to improve our CLI output here.

The requirement to export a generateStaticParams to get static cache behavior after build time was really surprising behavior for me, and I think others:

Hmm, maybe somewhat! The behavior is similar to Pages Router—if you only had a dynamic page, it would not opt you into ISR—you would have to use getStaticPaths. Similarly, you have to use generateStaticParams here.

A possible discussion to have is whether revalidate should just enable it, without an empty generateStaticParams.

[leerob]

Would love to get @delbaoliveira's opinion here before merging 🙏

[karlkeefer]

@samcx I think my confusion here may stem from the fact that I didn't use pages router before.

As more folks start to use next-js after app router is the recommended default, the level of surprise among users may rise ;)

Thanks for taking a look at the PR 🙌

[samcx]

As more folks use next-js after app router is the recommended default, the level of surprise among users may rise ;)

@karlkeefer Makes sense and noted! We are working to improve the App Router's caching story which will most likely involve improving the Route Segment Config, so we could end up improving this to cause less confusion.

I'll defer to Delba for further review on this

[delbaoliveira]

Thank you for raising this @karlkeefer, I've pushed a commit to rephrase a few things.

@samcx maybe not supplying generateStaticParams should be the equivalent of supplying an empty array. But I'll defer that to your team :)

Delba was able to review this!

[rijk]

A possible discussion to have is whether revalidate should just enable it, without an empty generateStaticParams. :frog-eyes:

Or setting export const dynamic = 'force-static'. Having those options available but not actually making a route static, unless you add a generateStaticParams function that returns an empty array is the kind of DX that makes someone lose their mind.

[samcx]

@rijk Thanks for the feedback!

Actually not 100% with export const dynamic = 'force-static—taking a look

[samcx]

@rijk It turns out you can use force-static! I'll be updating our again