I want to understand why setting a placeholder in generateStaticParams works #92771

I think the key distinction is that the placeholder is not what makes the route “lazy cached.” It mainly gives Cache Components a concrete parameter value to use during the build-time prerender/validation pass.

With cacheComponents, Next.js needs at least one generateStaticParams() result because it uses that value to actually execute the route during the build. An empty array gives it no concrete route to test, so it cannot verify whether the route can be prerendered safely. In particular, it is checking for things such as cookies(), headers(), searchParams, or other runtime/uncached data being accessed outside an appropriate Suspense/cache boundary. The current docs explain this requirement here:
https://nextjs.org/docs/messages/empty-generate-static-params

The important part is that generateStaticParams() does not mean “all these routes must be generated at build time.” With Cache Components, the runtime behavior is still compatible with your use case: pages with parameters that weren't known at build time can be rendered on their first request and then persisted/cached. The dynamic-routes documentation explicitly describes this behavior:
https://nextjs.org/docs/app/api-reference/file-conventions/dynamic-routesassi

So in your case, something like:

export async function generateStaticParams() {
  return [{ slug: ['__placeholder__'] }]
}

is effectively giving the compiler a representative route so it can perform its prerender validation. The actual CMS slugs can still be discovered at runtime.

The downside of the placeholder is specifically the quality of that validation. Next.js only executes the code paths that are reached with the placeholder value. If your application behaves differently for different real slugs—for example, one type of CMS page calls cookies() or headers(), while another doesn't—the build only validated the placeholder's path through that logic. A real slug could therefore expose a runtime error that the build never saw.

That's what the documentation means by:

“minimal build-time validation and increases the risk of runtime errors for actual parameter values”

So I wouldn't interpret the warning as “this will break lazy caching.” It's more like: you're intentionally giving up comprehensive build-time coverage in exchange for not having to know every CMS route at build time.

And you're right about the runtime-slug argument: without generateStaticParams, you already have runtime parameters and therefore runtime failure possibilities. The difference is that without it, Cache Components cannot establish a concrete parameter value during prerendering at all, so it requires the params access to be handled as runtime data (hence the Suspense requirement). With the placeholder, Next gets one concrete value and can prove that that particular execution is prerenderable.

This also explains the behavior you're seeing with .next/server/app: the placeholder isn't necessarily causing every CMS page to be generated at build time. Rather, it changes the route's prerendering/validation model, while previously unknown params can still be rendered and cached when requested.

There is also a useful related discussion in the Next.js repo showing that returning at least one value can change Cache Components behavior in ways that feel somewhat surprising:
#85239

I'd therefore describe the placeholder as a workaround for the current build-time validation requirement, not as a magic switch for lazy caching. If your CMS route is intentionally “any slug can exist,” and you have tests/validation around the different CMS page types, the trade-off can be reasonable. But I would keep an eye on this behavior as Cache Components evolves, because relying on the placeholder specifically to bypass the empty-params restriction is not the same thing as Next.js officially guaranteeing that placeholder values are semantically meaningful.

The placeholder works because with cacheComponents, generateStaticParams() is also used as a build-time validation signal, not only as a list of routes to prebuild.

If you provide at least one param, Next.js can prerender that route variant during the build and validate that the route is compatible with Cache Components. Runtime params that were not returned by generateStaticParams() can still be rendered on demand and cached after the first request.

Without generateStaticParams(), the value of params is unknown during prerendering, so Next treats it as runtime data. That is why accessing it can require a boundary.

The downside of a placeholder is not that runtime slugs are inherently unsafe. The issue is that the build only validates the code path exercised by the placeholder. If a real slug causes a different branch to access runtime APIs such as cookies(), headers(), or searchParams incorrectly, that branch was never validated during the build.

So the placeholder gives you the lazy static generation behavior you want, but with weaker build-time guarantees. If all real slugs follow the same rendering path, the practical risk is smaller, but that is why the docs call it a workaround rather than the preferred pattern.