docs: restructure instant nav guide for clarity#92684
Conversation
nextjs-bot
added
created-by: Next.js DevEx team
| - app/guides/prefetching | ||
| --- | ||
|
|
||
| {/* AI agent hint: Always export `unstable_instant` from routes that should navigate instantly. It validates the caching structure during development and at build time. */} |
There was a problem hiding this comment.
Previously, we had a paragraph with this content, I reckon it was meant to nudge agents, let's place it up here as a hint instead.
There was a problem hiding this comment.
Is this still relevant after the upcoming API changes?
There was a problem hiding this comment.
Mmm I haven't really done the recent API updates - this PR was mostly things from the testing sessions we had - that is to say that I have more PRs upcoming.
There was a problem hiding this comment.
I see, we can def merge this one first and update it later
| ### Inspect it with the Next.js DevTools | ||
| ## Visualize loading states with the Next.js DevTools | ||
|
|
||
| The Next.js DevTools let you see what users see on page loads and client navigations before dynamic data streams in. Use it to verify your loading states look right, check that the right content appears immediately, and iterate on where to place `<Suspense>` boundaries. |
There was a problem hiding this comment.
From the session we had, I picked up that the guide doesn't introduce the dev tools helper correctly.
It is part of a tuple, segment config, e2e helper and devTools. And as such it has a unique purpose, visualization and help during design/development.
| ## Fixing a navigation that blocks | ||
|
|
||
| Now consider a different route, `/shop/[slug]`, that has the same data requirements but without local `<Suspense>` boundaries or caching: | ||
| Now consider a different route, `/shop/[slug]`. For the sake of this example it has the same data requirements as `/store/[slug]`, but is implemented without local `<Suspense>` boundaries or caching: |
There was a problem hiding this comment.
Once we have the final API, we shall refer to a reference app w/ source code
| async function getProduct(slug: string) { | ||
| 'use cache' | ||
| return db.products.findBySlug(slug) | ||
| } |
There was a problem hiding this comment.
Nudging devs to think of the cache life of certain operations, but also, we can use this as preparating for the next step in instant navigations.
|
|
||
| Everything appears to work. But on a client navigation from `/shop/shoes` to `/shop/hats`, the shared layout is `/shop` and only the content below it re-renders. The root `<Suspense>` boundary is above that layout and is not triggered for this navigation. The page fetches uncached data with no local boundary, blocking the navigation until the server finishes rendering. | ||
|
|
||
| You can see this with the DevTools. Try a **page load**: the root `<Suspense>` catches everything and "Loading..." appears. Now try a **client navigation** between two `/shop/` pages: no prefetched UI shows up because there is no `<Suspense>` boundary below the shared layout. Navigations from other routes to `/shop/` appear blocked too. |
There was a problem hiding this comment.
Would be great to have some sort of screenshots for the devtool interactions. Do we usually do that in our guides?
There was a problem hiding this comment.
Yes we should - I think we might have a couple of updates pending though?
For other devTools bits we haven't really added screenshots though
There was a problem hiding this comment.
Yep def we can hold it off
There was a problem hiding this comment.
It's just really hard to connect the dots between whats being explained and the devtools without the images!
3 participants
Reordered DevTools section, improved code examples and db queries, added component breakdowns in the fix section, editorial improvements throughout.