Is route with unlisted params for nested dynamic route segments upgraded after first visit?

[charshin]

Summary

Firstly, At runtime says:
"The first visit to /shoes/basketball-shoes. Neither param was prerendered. Next.js serves the generic App Shell for /[category]/[product]. Both the category and the product stream in.

After the first visit, Next.js renders these routes in the background with the now-known params. The next visitor to the same URLs gets the upgraded result."

It is natural to think that upgraded result for /shoes/basketball-shoes is a fully static page. And it is verified using the demo.

However, What the upgrade produces says in its 3rd bullet point:
"Params are resolved in route order. A param value not returned by generateStaticParams stays unresolved and prevents any deeper params from upgrading."

If I reason correctly, /shoes/basketball-shoes would not be upgraded to a fully static page because shoes is not a listed category, which contradicts the observed behavior.

Can someone explain to me? Thanks

Additional information

No response

Example

No response

[icyJoseph]

You reading it right, and the demo is showing the correct behavior. That third bullet describes a different step than the one you're thinking of.

There are two separate things:

1. The shells built ahead of time (from generateStaticParams). Next.js builds a fallback shell for each prefix of the params you return, in route order. With tops/tee and shorts/joggers, that gives you:

• /tops/tee, /shorts/joggers
• /tops/[product], /shorts/[product]
• /[category]/[product]

What you never get is something like /[category]/tee. This is a URL dependent shell, and a URL can't have a hole in the middle.

That's what "params are resolved in route order" means. If category is missing, any deeper param can only be a fallback too, so a visit to /shoes/basketball-shoes gets the generic /[category]/[product] shell.

2. The upgrade after the first visit. This render runs for a concrete URL, so both shoes and basketball-shoes are known. No param is unresolved, and if every data access is cached, the result is a fully static page. That's what you saw.

In short, the bullet limits which shell a first visit can get. It doesn't limit what the upgrade produces.

I think that's what's happening here 🤔 — I'll revisit the bullet point at some point, as per feedback... it needs some adjustment.

[charshin]

Thanks for the quick reply. I think the reason it is confusing because the 3rd bullet point is parked under the process of background upgrade, maybe it should be placed under At build time section instead.
Anyway, I have 2 more things I wanna ask:

1. At the moment, it looks like App Shell are not generated at runtime for concrete urls of unknown params. That means a visit to /shoes (route /[category]/page.tsx) does not generate an App Shell for /shoes/[product]. Is it doable and part of the roadmap?
2. Does App Shell support revalidation like Static Shell? I have not been able to find this information or example in the doc. The demo has cached content but they are behind await params. I am asking for cases where cached content is in front of await params and part of the App Shell.

[icyJoseph]

Yeah, I have a draft PR fixing that guide now.

Sorry this answer turned out quite long. I've been trying to remove stuff, but I also wanted to be comprehensive, drawing from docs only, to see in which parts there are gaps still.

As far as I can tell these guides tell the story, minus some stuff that one should arguably not need to know, but yeah...

• https://nextjs.org/docs/app/getting-started/caching
• https://nextjs.org/docs/app/guides/incremental-static-regeneration-cache-components
• https://nextjs.org/docs/app/guides/optimizing-prefetching

Onto the questions...

At the moment, it looks like App Shell are not generated at runtime for concrete urls of unknown params. That means a visit to /shoes (route /[category]/page.tsx) does not generate an App Shell for /shoes/[product]. Is it doable and part of the roadmap?

This depends on whether the deeper segment can be prerendered at all, meaning it defines generateStaticParams:

• When both [category] and [product] define generateStaticParams (the guide's example), a first visit to /shoes/basketball-shoes upgrades straight to that concrete page. There's no in-between /shoes/[product] shell, so a later visit to /shoes/sneakers gets the generic /[category]/[product] shell again.
• When only [category] defines generateStaticParams, product stays dynamic. A visit to /shoes/anything turns the generic shell into a /shoes/[product] shell, which every other product under shoes then shares.

Visiting /shoes (the /[category]/page.tsx route) doesn't produce shells for /[category]/[product]. It's a different route with its own entries.

Does App Shell support revalidation like Static Shell? I have not been able to find this information or example in the doc. The demo has cached content but they are behind await params. I am asking for cases where cached content is in front of await params and part of the App Shell.

I'm not exactly sure what you mean here. I think the answer is yes: the build-time shells, the pages generated at runtime for unlisted params, and the narrower shells in between all follow the revalidate and expire of the cache profiles inside them.

Let's clarify a few things, because the client router also keeps its own copy. It's easier to see the whole picture by following what a client navigation can get, and where each part comes from.

The static shell

At build time, Next.js prerenders each route into a static shell: HTML for direct visits, plus an RSC payload that lets a client navigation render the next screen right away. A server or CDN keeps it, and the revalidate and expire of the cached content inside it are a reference for how often it's rebuilt.

The App Shell

This is what a default <Link> prefetches for a route. One representative is shared by every URL under that route.

While building, Next.js records whether the route reads cookies() or headers(). If it reads neither, the static shell is already the best possible App Shell, so the prefetch is served from static output a CDN can cache, without any server compute.

If the route reads cookies() or headers(), the App Shell is rendered with that session data and cached per session on the client.

The guide also says "App Shell" for what the server sends on a first visit to an unlisted URL. That's the same prerender, served as the response instead of a prefetch.

The per-link prefetch

With Partial Prefetching, <Link prefetch={true}> goes one step further for a concrete URL. It renders with that link's params and searchParams, so cached content that depends on them can be ready before the click. It costs a server request per link, which is only worth paying when the route reads URL data. See Optimizing prefetching.

The navigation

It renders whatever the previous steps left out (uncached data fetches, uncached file system, etc.).

Whichever shell the client router prefetched and used, the stale time of the cache profiles in it, the shortest one, controls when the router checks with the server again. revalidate and expire are for the server.

Then during ISR, tying back to your first question, Next.js renders the page with the now-known params, but cookies() and headers() stay unknown. Content that reads params joins the upgraded output for that URL, while content that reads cookies or headers keeps its <Suspense> fallback and streams in at request time.

One gotcha: a default <Link> still prefetches only the App Shell, which every URL under the route shares. To get the upgraded output for that URL, possibly a fully static page, before the click, the link needs prefetch={true}. A direct visit gets the upgraded output either way.

So, more or less, the tools you have available are:

• generateStaticParams for ISR
• Where you await params (inside <Suspense>) decides how much of the App Shell is shared
• cacheLife (stale on the client, revalidate and expire on the server)
• prefetch={true} per-link prefetch, for links where URL-dependent content should be ready before the click
• prefetch() and navigation() move expensive work to a later step, when a prefetch would otherwise generate it for links that may never be clicked.

The last two APIs are not needed by everyone, at least not something you should know day 1.

You don't have to know up front which one you need. When a route would benefit from one of them, the errors and insights Next.js shows in development point you to it.