Are there any behavioral differences between applying "use cache" at the file level versus the component level?

[dninomiya]

"use cache";
export default async function Page() { }

export default async function Page() {
  "use cache";
  // ...
}

Could you explain how these two differ in behavior?

Additionally, is there any reason to make a static component async and apply "use cache" to it?

https://nextjs.org/docs/app/api-reference/directives/use-cache#caching-an-entire-route-with-use-cache

[icyJoseph]

Given nothing else but the default page or layout export:

'use cache'

export default async function Page() {}

export default async function Page() {
  'use cache'
}

AFAIK, these would be equivalent. The nice side effect being that the entire page component would be cached, given that no dynamic or runtime behavior is present, like accessing searchParams, etc.

On layout level, since the children and parallel routes, are references/slots/placeholders, as long as you don't "introspect" them, they are pass-through into the cached output of the layout.

There's two considerations (I should document).

At the top of the file, means that function exports from this module, have to be async functions. You can still export metadata as object for example. In general the function scope targeted by the directive has to be async.

Also, these exported cached functions can be imported into client modules, and invoked from the client. If you nest the use cache directive within some scope, then the only way to pass them down is via props.

[dninomiya]

@icyJoseph
Thank you for the clarification!

From what I see in the build output, even without "use cache", the static parts are already included in the static shell (.html).
Therefore, my current understanding is that there’s no real benefit in explicitly making a layout or page.tsx with no dynamic elements an async function and adding "use cache".

Is this understanding correct?

[icyJoseph]

That's PPR doing the lift, during prerendering it walks the route tree, and everything that's static, or has been cached becomes part of the static shell. As a side effect, all pages have an associated .html file in the build output, it is not necessary, but you could inspect it if you want to see what got included in the initial shell, it might be case that the entire page is part of the static shell!

[dninomiya]

@icyJoseph

Thanks a lot for the detailed explanations throughout these discussions!
Your clarifications about how PPR handles static prerendering and how "use cache" behaves at both file and component levels really helped me understand the underlying behavior much better.

Appreciate you taking the time to provide such clear context — it’s been extremely insightful. 🙏