Loading layout docs update (#90787)

--- [Slack Thread](https://vercel.slack.com/archives/C05KYT5S9FF/p1772239839900129?thread_ts=1772239839.900129&cid=C05KYT5S9FF) <p><a href="https://cursor.com/agents/bc-d69fb736-2a00-5f68-9e28-9b31c194f12a"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a href="https://cursor.com/background-agent?bcId=bc-d69fb736-2a00-5f68-9e28-9b31c194f12a"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img alt="Open in Cursor" width="131" height="28" src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a> </p> --------- Co-authored-by: Cursor Agent <[email protected]> Co-authored-by: Joseph Chamochumbi <[email protected]> Co-authored-by: Delba de Oliveira <[email protected]>
2026-09-24 17:00:51 +00:00 · 2026-03-05 10:46:26 +01:00
parent 2c52ea2e7b
commit dfbc3dc6b7
7 changed files with 72 additions and 2 deletions
@@ -152,7 +152,7 @@ On navigation, the user will immediately see the layout and a [loading state](#c
  height="691"
 />

-Behind-the-scenes, `loading.js` will be nested inside `layout.js`, and will automatically wrap the `page.js` file and any children below in a `<Suspense>` boundary.
+Behind the scenes, `loading.js` will be [nested inside `layout.js`](/docs/app/getting-started/project-structure#component-hierarchy), and will automatically wrap the `page.js` file and any children below in a `<Suspense>` boundary.

 <Image
  alt="loading.js overview"
@@ -162,7 +162,11 @@ Behind-the-scenes, `loading.js` will be nested inside `layout.js`, and will auto
  height="768"
 />

-This approach works well for route segments (layouts and pages), but for more granular streaming, you can use `<Suspense>`.
+Because of this, a layout that accesses uncached or runtime data (e.g. `cookies()`, `headers()`, or uncached fetches) does not fall back to a same route segment `loading.js`. Instead, it blocks navigation until the layout finishes rendering. [Cache Components](/docs/app/getting-started/caching) prevents this by guiding you with a build-time error.
+
+To fix this, wrap the uncached access in its own [`<Suspense>`](#with-suspense) boundary with a fallback, or move the data fetching into `page.js` where `loading.js` can cover it. See [`loading.js`](/docs/app/api-reference/file-conventions/loading) for more details.
+
+This is why, while `loading.js` works well for streaming route segments, using `<Suspense>` closer to the runtime or uncached data access is recommended.

 #### With `<Suspense>`

@@ -92,6 +92,8 @@ export default function Error({ error, unstable_retry }) {
 > - The [React DevTools](https://react.dev/learn/react-developer-tools) allow you to toggle error boundaries to test error states.
 > - If you want errors to bubble up to the parent error boundary, you can `throw` when rendering the `error` component.

+In the [component hierarchy](/docs/app/getting-started/project-structure#component-hierarchy), `error.js` wraps `loading.js`, `not-found.js`, `page.js`, and nested `layout.js` files in a React error boundary. It does **not** wrap the `layout.js` or `template.js` above it in the same segment. To handle errors in the root layout, use [`global-error.js`](/docs/app/api-reference/file-conventions/error#global-error).
+
 ## Reference

 ### Props
@@ -21,6 +21,8 @@ export default function DashboardLayout({ children }) {
 }
 ```

+In the [component hierarchy](/docs/app/getting-started/project-structure#component-hierarchy), `layout.js` is the outermost component in a route segment. It wraps `template.js`, `error.js`, `loading.js`, `not-found.js`, and `page.js`.
+
 A **root layout** is the top-most layout in the root `app` directory. It is used to define the `<html>` and `<body>` tags and other globally shared UI.

 ```tsx filename="app/layout.tsx" switcher
@@ -311,6 +313,54 @@ export default function Layout({ children }) {
 }
 ```

+### Interaction with `loading.js`
+
+Because `loading.js` sits below `layout.js` in the [component hierarchy](/docs/app/getting-started/project-structure#component-hierarchy), it cannot show a fallback for uncached or runtime data access in the layout itself, such as calling [`cookies()`](/docs/app/api-reference/functions/cookies), [`headers()`](/docs/app/api-reference/functions/headers), or making uncached fetches.
+
+The behavior depends on whether [Cache Components](/docs/app/getting-started/caching) is enabled:
+
+- **Without Cache Components:** The navigation will block until the layout finishes rendering, and the `loading.js` fallback will not be shown.
+- **With Cache Components:** `loading.js` is treated as a regular `<Suspense>` boundary rather than a special prefetch marker. Uncached or runtime data access in the layout must be explicitly wrapped in its own `<Suspense>` boundary, otherwise Next.js guides you with a build-time error. The static shell streams immediately, and the uncached content swaps in as it resolves.
+
+In both cases, to ensure instant navigation, either:
+
+- Wrap runtime data access in your layout in its own `<Suspense>` boundary with a fallback.
+- Move uncached data fetching from `layout.js` into `page.js` where `loading.js` can show a fallback.
+
+```tsx filename="app/dashboard/layout.tsx" switcher highlight={8-10}
+import { Suspense } from 'react'
+import { NavSkeleton } from './nav-skeleton'
+import { DashboardNav } from './dashboard-nav'
+
+export default function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <>
+      <Suspense fallback={<NavSkeleton />}>
+        <DashboardNav />
+      </Suspense>
+      <main>{children}</main>
+    </>
+  )
+}
+```
+
+```jsx filename="app/dashboard/layout.js" switcher highlight={8-10}
+import { Suspense } from 'react'
+import { NavSkeleton } from './nav-skeleton'
+import { DashboardNav } from './dashboard-nav'
+
+export default function Layout({ children }) {
+  return (
+    <>
+      <Suspense fallback={<NavSkeleton />}>
+        <DashboardNav />
+      </Suspense>
+      <main>{children}</main>
+    </>
+  )
+}
+```
+
 ### Fetching Data

 Layouts cannot pass data to their `children`. However, you can fetch the same data in a route more than once, and use React [`cache`](https://react.dev/reference/react/cache) to dedupe the requests without affecting performance.
@@ -83,6 +83,15 @@ In the same folder, `loading.js` will be nested inside `layout.js`. It will auto
  height="768"
 />

+In the [component hierarchy](/docs/app/getting-started/project-structure#component-hierarchy), `loading.js` wraps `not-found.js`, `page.js`, and nested `layout.js` files in a `<Suspense>` boundary. It does **not** wrap the `layout.js`, `template.js`, or `error.js` in the same segment.
+
+> **Good to know**: If the layout accesses uncached or runtime data (e.g. `cookies()`, `headers()`, or uncached fetches), `loading.js` will not show a fallback for it.
+>
+> - **Without [Cache Components](/docs/app/getting-started/caching):** Navigation blocks until the layout finishes rendering.
+> - **With [Cache Components](/docs/app/getting-started/caching):** Uncached or runtime data access in the layout must be explicitly wrapped in `<Suspense>`, otherwise Next.js guides you with a build-time error. The static shell streams first, and the uncached content fills in.
+>
+> To ensure instant navigation, move uncached data fetching from `layout.js` into `page.js`, or wrap the runtime data access in your layout in its own `<Suspense>` boundary. See [layout.js Caveats](/docs/app/api-reference/file-conventions/layout#interaction-with-loadingjs) for details and examples.
+
 ### SEO

 - For bots that only scrape static HTML, and cannot execute JavaScript like a full browser, such as Twitterbot, Next.js resolves [`generateMetadata`](/docs/app/api-reference/functions/generate-metadata) before streaming UI, and metadata is placed in the `<head>` of the initial HTML.
@@ -40,6 +40,8 @@ export default function NotFound() {
 }
 ```

+In the [component hierarchy](/docs/app/getting-started/project-structure#component-hierarchy), `not-found.js` renders between `loading.js` and `page.js`. It is wrapped by the `<Suspense>` boundary from `loading.js` and the error boundary from `error.js` in the same segment.
+
 ## `global-not-found.js` (experimental)

 The `global-not-found.js` file lets you define a 404 page for your entire application. Unlike `not-found.js`, which works at the route level, this is used when a requested URL doesn't match any route at all. Next.js **skips rendering** and directly returns this global page.
@@ -29,6 +29,7 @@ export default function Page({ params, searchParams }) {
 - A `page` is always the **leaf** of the route subtree.
 - A `page` file is required to make a route segment **publicly accessible**.
 - Pages are [Server Components](https://react.dev/reference/rsc/server-components) by default, but can be set to a [Client Component](https://react.dev/reference/rsc/use-client).
+- In the [component hierarchy](/docs/app/getting-started/project-structure#component-hierarchy), `page.js` is the innermost file convention. It is wrapped by `loading.js` (Suspense boundary), `error.js` (error boundary), `template.js`, and `layout.js` in the same segment.

 ## Reference

@@ -44,6 +44,8 @@ In terms of nesting, `template.js` is rendered between a layout and its children
 </Layout>
 ```

+In the [component hierarchy](/docs/app/getting-started/project-structure#component-hierarchy), `template.js` renders between `layout.js` and `error.js`. It wraps `error.js`, `loading.js`, `not-found.js`, and `page.js`, but does **not** wrap the `layout.js` in the same segment.
+
 ## Props

 ### `children` (required)