Docs: Explain why Layouts (RSCs) can't access pathname (#64785)
- Add section explaining why `pathname` can't be accessed in a layout ([file](https://github.com/vercel/next.js/pull/64785/files#diff-8eb7b23d3da342a1a407cdb6cc9c2d0dc2a455091ba2c4b6dbc41ba6cf840367)) - Split pages and layouts files (to add layout-specific examples in the future) - Clean up the existing active links example I'll add layout-specific examples in a follow-up PR, after creating some demos.
This commit is contained in:
Delba de Oliveira
GitHub
parent
4d4dc4b5f9
commit
84af8009e3
42 changed files with 278 additions and 155 deletions
|
|
@ -89,7 +89,7 @@ Create an `app/` folder, then add a `layout.tsx` and `page.tsx` file. These will
|
|||
height="363"
|
||||
/>
|
||||
|
||||
Create a [root layout](/docs/app/building-your-application/routing/pages-and-layouts#root-layout-required) inside `app/layout.tsx` with the required `<html>` and `<body>` tags:
|
||||
Create a [root layout](/docs/app/building-your-application/routing/layouts-and-templates#root-layout-required) inside `app/layout.tsx` with the required `<html>` and `<body>` tags:
|
||||
|
||||
```tsx filename="app/layout.tsx" switcher
|
||||
export default function RootLayout({
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ description: Learn how to create your first route in Next.js.
|
|||
related:
|
||||
description: Learn more about creating pages and layouts.
|
||||
links:
|
||||
- app/building-your-application/routing/pages-and-layouts
|
||||
- app/building-your-application/routing/pages
|
||||
---
|
||||
|
||||
> We recommend reading the [Routing Fundamentals](/docs/app/building-your-application/routing) page before continuing.
|
||||
|
|
@ -25,7 +25,7 @@ Each folder represents a [**route** segment](/docs/app/building-your-application
|
|||
height="594"
|
||||
/>
|
||||
|
||||
A special [`page.js` file](/docs/app/building-your-application/routing/pages-and-layouts#pages) is used to make route segments publicly accessible.
|
||||
A special [`page.js` file](/docs/app/building-your-application/routing/pages) is used to make route segments publicly accessible.
|
||||
|
||||
<Image
|
||||
alt="Defining Routes"
|
||||
|
|
@ -41,7 +41,7 @@ In this example, the `/dashboard/analytics` URL path is _not_ publicly accessibl
|
|||
|
||||
## Creating UI
|
||||
|
||||
[Special file conventions](/docs/app/building-your-application/routing#file-conventions) are used to create UI for each route segment. The most common are [pages](/docs/app/building-your-application/routing/pages-and-layouts#pages) to show UI unique to a route, and [layouts](/docs/app/building-your-application/routing/pages-and-layouts#layouts) to show UI that is shared across multiple routes.
|
||||
[Special file conventions](/docs/app/building-your-application/routing#file-conventions) are used to create UI for each route segment. The most common are [pages](/docs/app/building-your-application/routing/pages) to show UI unique to a route, and [layouts](/docs/app/building-your-application/routing/layouts-and-templates#layouts) to show UI that is shared across multiple routes.
|
||||
|
||||
For example, to create your first page, add a `page.js` file inside the `app` directory and export a React component:
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,58 @@
|
|||
---
|
||||
title: Pages
|
||||
description: Create your first page in Next.js
|
||||
related:
|
||||
links:
|
||||
- app/building-your-application/routing/layouts-and-templates
|
||||
- app/building-your-application/routing/linking-and-navigating
|
||||
---
|
||||
|
||||
A page is UI that is **unique** to a route. You can define a page by default exporting a component from a `page.js` file.
|
||||
|
||||
For example, to create your `index` page, add the `page.js` file inside the `app` directory:
|
||||
|
||||
<Image
|
||||
alt="page.js special file"
|
||||
srcLight="/docs/light/page-special-file.png"
|
||||
srcDark="/docs/dark/page-special-file.png"
|
||||
width="1600"
|
||||
height="444"
|
||||
/>
|
||||
|
||||
```tsx filename="app/page.tsx" switcher
|
||||
// `app/page.tsx` is the UI for the `/` URL
|
||||
export default function Page() {
|
||||
return <h1>Hello, Home page!</h1>
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/page.js" switcher
|
||||
// `app/page.js` is the UI for the `/` URL
|
||||
export default function Page() {
|
||||
return <h1>Hello, Home page!</h1>
|
||||
}
|
||||
```
|
||||
|
||||
Then, to create further pages, create a new folder and add the `page.js` file inside it. For example, to create a page for the `/dashboard` route, create a new folder called `dashboard`, and add the `page.js` file inside it:
|
||||
|
||||
```tsx filename="app/dashboard/page.tsx" switcher
|
||||
// `app/dashboard/page.tsx` is the UI for the `/dashboard` URL
|
||||
export default function Page() {
|
||||
return <h1>Hello, Dashboard Page!</h1>
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/dashboard/page.js" switcher
|
||||
// `app/dashboard/page.js` is the UI for the `/dashboard` URL
|
||||
export default function Page() {
|
||||
return <h1>Hello, Dashboard Page!</h1>
|
||||
}
|
||||
```
|
||||
|
||||
> **Good to know**:
|
||||
>
|
||||
> - The `.js`, `.jsx`, or `.tsx` file extensions can be used for Pages.
|
||||
> - A page is always the [leaf](/docs/app/building-your-application/routing#terminology) of the [route subtree](/docs/app/building-your-application/routing#terminology).
|
||||
> - A `page.js` file is required to make a route segment publicly accessible.
|
||||
> - Pages are [Server Components](/docs/app/building-your-application/rendering/server-components) by default, but can be set to a [Client Component](/docs/app/building-your-application/rendering/client-components).
|
||||
> - Pages can fetch data. View the [Data Fetching](/docs/app/building-your-application/data-fetching) section for more information.
|
||||
|
|
@ -1,63 +1,9 @@
|
|||
---
|
||||
title: Pages and Layouts
|
||||
description: Create your first page and shared layout with the App Router.
|
||||
title: Layouts and Templates
|
||||
description: Create your first shared layout in Next.js.
|
||||
---
|
||||
|
||||
> We recommend reading the [Routing Fundamentals](/docs/app/building-your-application/routing) and [Defining Routes](/docs/app/building-your-application/routing/defining-routes) pages before continuing.
|
||||
|
||||
The special files [layout.js](#layouts), [page.js](#pages), and [template.js](#templates) allow you to create UI for a [route](/docs/app/building-your-application/routing/defining-routes#creating-routes). This page will guide you through how and when to use these special files.
|
||||
|
||||
## Pages
|
||||
|
||||
A page is UI that is **unique** to a route. You can define a page by default exporting a component from a `page.js` file.
|
||||
|
||||
For example, to create your `index` page, add the `page.js` file inside the `app` directory:
|
||||
|
||||
<Image
|
||||
alt="page.js special file"
|
||||
srcLight="/docs/light/page-special-file.png"
|
||||
srcDark="/docs/dark/page-special-file.png"
|
||||
width="1600"
|
||||
height="444"
|
||||
/>
|
||||
|
||||
```tsx filename="app/page.tsx" switcher
|
||||
// `app/page.tsx` is the UI for the `/` URL
|
||||
export default function Page() {
|
||||
return <h1>Hello, Home page!</h1>
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/page.js" switcher
|
||||
// `app/page.js` is the UI for the `/` URL
|
||||
export default function Page() {
|
||||
return <h1>Hello, Home page!</h1>
|
||||
}
|
||||
```
|
||||
|
||||
Then, to create further pages, create a new folder and add the `page.js` file inside it. For example, to create a page for the `/dashboard` route, create a new folder called `dashboard`, and add the `page.js` file inside it:
|
||||
|
||||
```tsx filename="app/dashboard/page.tsx" switcher
|
||||
// `app/dashboard/page.tsx` is the UI for the `/dashboard` URL
|
||||
export default function Page() {
|
||||
return <h1>Hello, Dashboard Page!</h1>
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/dashboard/page.js" switcher
|
||||
// `app/dashboard/page.js` is the UI for the `/dashboard` URL
|
||||
export default function Page() {
|
||||
return <h1>Hello, Dashboard Page!</h1>
|
||||
}
|
||||
```
|
||||
|
||||
> **Good to know**:
|
||||
>
|
||||
> - The `.js`, `.jsx`, or `.tsx` file extensions can be used for Pages.
|
||||
> - A page is always the [leaf](/docs/app/building-your-application/routing#terminology) of the [route subtree](/docs/app/building-your-application/routing#terminology).
|
||||
> - A `page.js` file is required to make a route segment publicly accessible.
|
||||
> - Pages are [Server Components](/docs/app/building-your-application/rendering/server-components) by default, but can be set to a [Client Component](/docs/app/building-your-application/rendering/client-components).
|
||||
> - Pages can fetch data. View the [Data Fetching](/docs/app/building-your-application/data-fetching) section for more information.
|
||||
The special files [layout.js](#layouts) and [template.js](#templates) allow you to create UI that is shared between [routes](/docs/app/building-your-application/routing/defining-routes#creating-routes). This page will guide you through how and when to use these special files.
|
||||
|
||||
## Layouts
|
||||
|
||||
|
|
@ -191,6 +137,7 @@ The two layouts would be nested as such:
|
|||
> - Layouts are [Server Components](/docs/app/building-your-application/rendering/server-components) by default but can be set to a [Client Component](/docs/app/building-your-application/rendering/client-components).
|
||||
> - Layouts can fetch data. View the [Data Fetching](/docs/app/building-your-application/data-fetching) section for more information.
|
||||
> - Passing data between a parent layout and its children is not possible. However, you can fetch the same data in a route more than once, and React will [automatically dedupe the requests](/docs/app/building-your-application/caching#request-memoization) without affecting performance.
|
||||
> - Layouts do not have access to `pathname` ([learn more](/docs/app/api-reference/file-conventions/layout)). But imported Client Components can access the pathname using [`usePathname`](/docs/app/api-reference/functions/use-pathname) hook.
|
||||
> - Layouts do not have access to the route segments below itself. To access all route segments, you can use [`useSelectedLayoutSegment`](/docs/app/api-reference/functions/use-selected-layout-segment) or [`useSelectedLayoutSegments`](/docs/app/api-reference/functions/use-selected-layout-segments) in a Client Component.
|
||||
> - You can use [Route Groups](/docs/app/building-your-application/routing/route-groups) to opt specific route segments in and out of shared layouts.
|
||||
> - You can use [Route Groups](/docs/app/building-your-application/routing/route-groups) to create multiple root layouts. See an [example here](/docs/app/building-your-application/routing/route-groups#creating-multiple-root-layouts).
|
||||
|
|
@ -236,9 +183,11 @@ In terms of nesting, `template.js` is rendered between a layout and its children
|
|||
</Layout>
|
||||
```
|
||||
|
||||
## Metadata
|
||||
## Examples
|
||||
|
||||
In the `app` directory, you can modify the `<head>` HTML elements such as `title` and `meta` using the [Metadata APIs](/docs/app/building-your-application/optimizing/metadata).
|
||||
### Metadata
|
||||
|
||||
You can modify the `<head>` HTML elements such as `title` and `meta` using the [Metadata APIs](/docs/app/building-your-application/optimizing/metadata).
|
||||
|
||||
Metadata can be defined by exporting a [`metadata` object](/docs/app/api-reference/functions/generate-metadata#the-metadata-object) or [`generateMetadata` function](/docs/app/api-reference/functions/generate-metadata#generatemetadata-function) in a [`layout.js`](/docs/app/api-reference/file-conventions/layout) or [`page.js`](/docs/app/api-reference/file-conventions/page) file.
|
||||
|
||||
|
|
@ -264,6 +213,94 @@ export default function Page() {
|
|||
}
|
||||
```
|
||||
|
||||
> **Good to know**: You should **not** manually add `<head>` tags such as `<title>` and `<meta>` to root layouts. Instead, you should use the [Metadata API](/docs/app/api-reference/functions/generate-metadata) which automatically handles advanced requirements such as streaming and de-duplicating `<head>` elements.
|
||||
> **Good to know**: You should **not** manually add `<head>` tags such as `<title>` and `<meta>` to root layouts. Instead, use the [Metadata API](/docs/app/api-reference/functions/generate-metadata) which automatically handles advanced requirements such as streaming and de-duplicating `<head>` elements.
|
||||
|
||||
Learn more about available metadata options in the [API reference](/docs/app/api-reference/functions/generate-metadata)
|
||||
|
||||
### Active Nav Links
|
||||
|
||||
You can use the [usePathname()](/docs/app/api-reference/functions/use-pathname) hook to determine if a nav link is active.
|
||||
|
||||
Since `usePathname()` is a client hook, you need to extract the nav links into a Client Component, which can be imported into your layout or template:
|
||||
|
||||
```tsx filename="app/components/nav-links.tsx" switcher
|
||||
'use client'
|
||||
|
||||
import { usePathname } from 'next/navigation'
|
||||
import Link from 'next/link'
|
||||
|
||||
export function Links() {
|
||||
const pathname = usePathname()
|
||||
|
||||
return (
|
||||
<nav>
|
||||
<Link className={`link ${pathname === '/' ? 'active' : ''}`} href="/">
|
||||
Home
|
||||
</Link>
|
||||
|
||||
<Link
|
||||
className={`link ${pathname === '/about' ? 'active' : ''}`}
|
||||
href="/about"
|
||||
>
|
||||
About
|
||||
</Link>
|
||||
</nav>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/components/nav-links.js" switcher
|
||||
'use client'
|
||||
|
||||
import { usePathname } from 'next/navigation'
|
||||
import Link from 'next/link'
|
||||
|
||||
export function Links() {
|
||||
const pathname = usePathname()
|
||||
|
||||
return (
|
||||
<nav>
|
||||
<Link className={`link ${pathname === '/' ? 'active' : ''}`} href="/">
|
||||
Home
|
||||
</Link>
|
||||
|
||||
<Link
|
||||
className={`link ${pathname === '/about' ? 'active' : ''}`}
|
||||
href="/about"
|
||||
>
|
||||
About
|
||||
</Link>
|
||||
</nav>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```tsx filename="app/layout.tsx" switcher
|
||||
import { NavLinks } from '@/app/ui/nav-links'
|
||||
|
||||
export default function Layout({ children }: { children: React.ReactNode }) {
|
||||
return (
|
||||
<html lang="en">
|
||||
<body>
|
||||
<NavLinks />
|
||||
<main>{children}</main>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/layout.js" switcher
|
||||
import { NavLinks } from '@/app/ui/nav-links'
|
||||
|
||||
export default function Layout({ children }) {
|
||||
return (
|
||||
<html lang="en">
|
||||
<body>
|
||||
<NavLinks />
|
||||
<main>{children}</main>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
|
@ -66,7 +66,7 @@ export default function PostList({ posts }) {
|
|||
|
||||
You can use [`usePathname()`](/docs/app/api-reference/functions/use-pathname) to determine if a link is active. For example, to add a class to the active link, you can check if the current `pathname` matches the `href` of the link:
|
||||
|
||||
```tsx filename="app/components/links.tsx" switcher
|
||||
```tsx filename="@/app/ui/nav-links.tsx" switcher
|
||||
'use client'
|
||||
|
||||
import { usePathname } from 'next/navigation'
|
||||
|
|
@ -77,27 +77,22 @@ export function Links() {
|
|||
|
||||
return (
|
||||
<nav>
|
||||
<ul>
|
||||
<li>
|
||||
<Link className={`link ${pathname === '/' ? 'active' : ''}`} href="/">
|
||||
Home
|
||||
</Link>
|
||||
</li>
|
||||
<li>
|
||||
<Link
|
||||
className={`link ${pathname === '/about' ? 'active' : ''}`}
|
||||
href="/about"
|
||||
>
|
||||
About
|
||||
</Link>
|
||||
</li>
|
||||
</ul>
|
||||
<Link className={`link ${pathname === '/' ? 'active' : ''}`} href="/">
|
||||
Home
|
||||
</Link>
|
||||
|
||||
<Link
|
||||
className={`link ${pathname === '/about' ? 'active' : ''}`}
|
||||
href="/about"
|
||||
>
|
||||
About
|
||||
</Link>
|
||||
</nav>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/components/links.js" switcher
|
||||
```jsx filename="@/app/ui/nav-links.tsx" switcher
|
||||
'use client'
|
||||
|
||||
import { usePathname } from 'next/navigation'
|
||||
|
|
@ -108,21 +103,16 @@ export function Links() {
|
|||
|
||||
return (
|
||||
<nav>
|
||||
<ul>
|
||||
<li>
|
||||
<Link className={`link ${pathname === '/' ? 'active' : ''}`} href="/">
|
||||
Home
|
||||
</Link>
|
||||
</li>
|
||||
<li>
|
||||
<Link
|
||||
className={`link ${pathname === '/about' ? 'active' : ''}`}
|
||||
href="/about"
|
||||
>
|
||||
About
|
||||
</Link>
|
||||
</li>
|
||||
</ul>
|
||||
<Link className={`link ${pathname === '/' ? 'active' : ''}`} href="/">
|
||||
Home
|
||||
</Link>
|
||||
|
||||
<Link
|
||||
className={`link ${pathname === '/about' ? 'active' : ''}`}
|
||||
href="/about"
|
||||
>
|
||||
About
|
||||
</Link>
|
||||
</nav>
|
||||
)
|
||||
}
|
||||
|
|
@ -143,7 +133,7 @@ If you'd like to scroll to a specific `id` on navigation, you can append your UR
|
|||
|
||||
> **Good to know**:
|
||||
>
|
||||
> - Next.js will scroll to the [Page](/docs/app/building-your-application/routing/pages-and-layouts#pages) if it is not visible in the viewport upon navigation.
|
||||
> - Next.js will scroll to the [Page](/docs/app/building-your-application/routing/pages) if it is not visible in the viewport upon navigation.
|
||||
|
||||
#### Disabling scroll restoration
|
||||
|
||||
|
|
@ -10,7 +10,7 @@ This allows you to organize your route segments and project files into logical g
|
|||
Route groups are useful for:
|
||||
|
||||
- [Organizing routes into groups](#organize-routes-without-affecting-the-url-path) e.g. by site section, intent, or team.
|
||||
- Enabling [nested layouts](/docs/app/building-your-application/routing/pages-and-layouts) in the same route segment level:
|
||||
- Enabling [nested layouts](/docs/app/building-your-application/routing/layouts-and-templates) in the same route segment level:
|
||||
- [Creating multiple nested layouts in the same segment, including multiple root layouts](#creating-multiple-root-layouts)
|
||||
- [Adding a layout to a subset of routes in a common segment](#opting-specific-segments-into-a-layout)
|
||||
|
||||
|
|
@ -56,7 +56,7 @@ To opt specific routes into a layout, create a new route group (e.g. `(shop)`) a
|
|||
|
||||
### Creating multiple root layouts
|
||||
|
||||
To create multiple [root layouts](/docs/app/building-your-application/routing/pages-and-layouts#root-layout-required), remove the top-level `layout.js` file, and add a `layout.js` file inside each route group. This is useful for partitioning an application into sections that have a completely different UI or experience. The `<html>` and `<body>` tags need to be added to each root layout.
|
||||
To create multiple [root layouts](/docs/app/building-your-application/routing/layouts-and-templates#root-layout-required), remove the top-level `layout.js` file, and add a `layout.js` file inside each route group. This is useful for partitioning an application into sections that have a completely different UI or experience. The `<html>` and `<body>` tags need to be added to each root layout.
|
||||
|
||||
<Image
|
||||
alt="Route Groups with Multiple Root Layouts"
|
||||
|
|
@ -181,7 +181,7 @@ For example, the `@analytics` slot has two subpages: `/page-views` and `/visitor
|
|||
height="768"
|
||||
/>
|
||||
|
||||
Within `@analytics`, create a [`layout`](/docs/app/building-your-application/routing/pages-and-layouts) file to share the tabs between the two pages:
|
||||
Within `@analytics`, create a [`layout`](/docs/app/building-your-application/routing/layouts-and-templates) file to share the tabs between the two pages:
|
||||
|
||||
```tsx filename="app/@analytics/layout.tsx" switcher
|
||||
import Link from 'next/link'
|
||||
|
|
@ -212,7 +212,7 @@ The `NextResponse` API allows you to:
|
|||
|
||||
To produce a response from Middleware, you can:
|
||||
|
||||
1. `rewrite` to a route ([Page](/docs/app/building-your-application/routing/pages-and-layouts) or [Route Handler](/docs/app/building-your-application/routing/route-handlers)) that produces a response
|
||||
1. `rewrite` to a route ([Page](/docs/app/building-your-application/routing/layouts-and-templates) or [Route Handler](/docs/app/building-your-application/routing/route-handlers)) that produces a response
|
||||
2. return a `NextResponse` directly. See [Producing a Response](#producing-a-response)
|
||||
|
||||
</AppOnly>
|
||||
|
|
@ -87,17 +87,17 @@ The `/dashboard/settings` route is composed of three segments:
|
|||
|
||||
Next.js provides a set of special files to create UI with specific behavior in nested routes:
|
||||
|
||||
| | |
|
||||
| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
||||
| [`layout`](/docs/app/building-your-application/routing/pages-and-layouts#layouts) | Shared UI for a segment and its children |
|
||||
| [`page`](/docs/app/building-your-application/routing/pages-and-layouts#pages) | Unique UI of a route and make routes publicly accessible |
|
||||
| [`loading`](/docs/app/building-your-application/routing/loading-ui-and-streaming) | Loading UI for a segment and its children |
|
||||
| [`not-found`](/docs/app/api-reference/file-conventions/not-found) | Not found UI for a segment and its children |
|
||||
| [`error`](/docs/app/building-your-application/routing/error-handling) | Error UI for a segment and its children |
|
||||
| [`global-error`](/docs/app/building-your-application/routing/error-handling) | Global Error UI |
|
||||
| [`route`](/docs/app/building-your-application/routing/route-handlers) | Server-side API endpoint |
|
||||
| [`template`](/docs/app/building-your-application/routing/pages-and-layouts#templates) | Specialized re-rendered Layout UI |
|
||||
| [`default`](/docs/app/api-reference/file-conventions/default) | Fallback UI for [Parallel Routes](/docs/app/building-your-application/routing/parallel-routes) |
|
||||
| | |
|
||||
| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
||||
| [`layout`](/docs/app/building-your-application/routing/layouts-and-templates#layouts) | Shared UI for a segment and its children |
|
||||
| [`page`](/docs/app/building-your-application/routing/pages) | Unique UI of a route and make routes publicly accessible |
|
||||
| [`loading`](/docs/app/building-your-application/routing/loading-ui-and-streaming) | Loading UI for a segment and its children |
|
||||
| [`not-found`](/docs/app/api-reference/file-conventions/not-found) | Not found UI for a segment and its children |
|
||||
| [`error`](/docs/app/building-your-application/routing/error-handling) | Error UI for a segment and its children |
|
||||
| [`global-error`](/docs/app/building-your-application/routing/error-handling) | Global Error UI |
|
||||
| [`route`](/docs/app/building-your-application/routing/route-handlers) | Server-side API endpoint |
|
||||
| [`template`](/docs/app/building-your-application/routing/layouts-and-templates#templates) | Specialized re-rendered Layout UI |
|
||||
| [`default`](/docs/app/api-reference/file-conventions/default) | Fallback UI for [Parallel Routes](/docs/app/building-your-application/routing/parallel-routes) |
|
||||
|
||||
> **Good to know**: `.js`, `.jsx`, or `.tsx` file extensions can be used for special files.
|
||||
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ This is possible because `fetch` requests are automatically memoized. Learn more
|
|||
|
||||
Streaming and [Suspense](https://react.dev/reference/react/Suspense) are React features that allow you to progressively render and incrementally stream rendered units of the UI to the client.
|
||||
|
||||
With Server Components and [nested layouts](/docs/app/building-your-application/routing/pages-and-layouts), you're able to instantly render parts of the page that do not specifically require data, and show a [loading state](/docs/app/building-your-application/routing/loading-ui-and-streaming) for parts of the page that are fetching data. This means the user does not have to wait for the entire page to load before they can start interacting with it.
|
||||
With Server Components and [nested layouts](/docs/app/building-your-application/routing/layouts-and-templates), you're able to instantly render parts of the page that do not specifically require data, and show a [loading state](/docs/app/building-your-application/routing/loading-ui-and-streaming) for parts of the page that are fetching data. This means the user does not have to wait for the entire page to load before they can start interacting with it.
|
||||
|
||||
<Image
|
||||
alt="Server Rendering with Streaming"
|
||||
|
|
|
|||
|
|
@ -48,7 +48,7 @@ Then, on the client:
|
|||
2. The React Server Components Payload is used to reconcile the Client and Server Component trees, and update the DOM.
|
||||
3. The JavaScript instructions are used to [hydrate](https://react.dev/reference/react-dom/client/hydrateRoot) Client Components and make the application interactive.
|
||||
|
||||
> **What is the React Server Component Payload (RSC)?**
|
||||
> #### What is the React Server Component Payload (RSC)?
|
||||
>
|
||||
> The RSC Payload is a compact binary representation of the rendered React Server Components tree. It's used by React on the client to update the browser's DOM. The RSC Payload contains:
|
||||
>
|
||||
|
|
|
|||
|
|
@ -80,7 +80,7 @@ To optimize the initial page load, Next.js will use React's APIs to render a sta
|
|||
|
||||
On the server:
|
||||
|
||||
1. React renders Server Components into a special data format called the **React Server Component Payload (RSC Payload)**, which includes references to Client Components.
|
||||
1. React renders Server Components into a special data format called the [**React Server Component Payload (RSC Payload)**](/docs/app/building-your-application/rendering/server-components#what-is-the-react-server-component-payload-rsc), which includes references to Client Components.
|
||||
2. Next.js uses the RSC Payload and Client Component JavaScript instructions to render **HTML** for the route on the server.
|
||||
|
||||
Then, on the client:
|
||||
|
|
@ -97,7 +97,7 @@ Then, on the client:
|
|||
|
||||
On subsequent navigations, Client Components are rendered entirely on the client, without the server-rendered HTML.
|
||||
|
||||
This means the Client Component JavaScript bundle is downloaded and parsed. Once the bundle is ready, React will use the RSC Payload to reconcile the Client and Server Component trees, and update the DOM.
|
||||
This means the Client Component JavaScript bundle is downloaded and parsed. Once the bundle is ready, React will use the [RSC Payload](/docs/app/building-your-application/rendering/server-components#what-is-the-react-server-component-payload-rsc) to reconcile the Client and Server Component trees, and update the DOM.
|
||||
|
||||
## Going back to the Server Environment
|
||||
|
||||
|
|
|
|||
|
|
@ -408,14 +408,14 @@ If your Client Components depend on data that is not serializable, you can [fetc
|
|||
|
||||
## Interleaving Server and Client Components
|
||||
|
||||
When interleaving Client and Server Components, it may be helpful to visualize your UI as a tree of components. Starting with the [root layout](/docs/app/building-your-application/routing/pages-and-layouts#root-layout-required), which is a Server Component, you can then render certain subtrees of components on the client by adding the `"use client"` directive.
|
||||
When interleaving Client and Server Components, it may be helpful to visualize your UI as a tree of components. Starting with the [root layout](/docs/app/building-your-application/routing/layouts-and-templates#root-layout-required), which is a Server Component, you can then render certain subtrees of components on the client by adding the `"use client"` directive.
|
||||
|
||||
{/* Diagram - interleaving */}
|
||||
|
||||
Within those client subtrees, you can still nest Server Components or call Server Actions, however there are some things to keep in mind:
|
||||
|
||||
- During a request-response lifecycle, your code moves from the server to the client. If you need to access data or resources on the server while on the client, you'll be making a **new** request to the server - not switching back and forth.
|
||||
- When a new request is made to the server, all Server Components are rendered first, including those nested inside Client Components. The rendered result (RSC Payload) will contain references to the locations of Client Components. Then, on the client, React uses the RSC Payload to reconcile Server and Client Components into a single tree.
|
||||
- When a new request is made to the server, all Server Components are rendered first, including those nested inside Client Components. The rendered result ([RSC Payload](/docs/app/building-your-application/rendering/server-components#what-is-the-react-server-component-payload-rsc)) will contain references to the locations of Client Components. Then, on the client, React uses the RSC Payload to reconcile Server and Client Components into a single tree.
|
||||
|
||||
{/* Diagram */}
|
||||
|
||||
|
|
|
|||
|
|
@ -345,7 +345,7 @@ To maintain a predictable order, we recommend the following:
|
|||
- Prefer CSS Modules over global styles.
|
||||
- Use a consistent naming convention for your CSS modules. For example, using `<name>.module.css` over `<name>.tsx`.
|
||||
- Extract shared styles into a separate shared component.
|
||||
- If using [Tailwind](/docs/app/building-your-application/styling/tailwind-css), import the stylesheet at the top of the file, preferably in the [Root Layout](/docs/app/building-your-application/routing/pages-and-layouts#root-layout-required).
|
||||
- If using [Tailwind](/docs/app/building-your-application/styling/tailwind-css), import the stylesheet at the top of the file, preferably in the [Root Layout](/docs/app/building-your-application/routing/layouts-and-templates#root-layout-required).
|
||||
|
||||
> **Good to know:** CSS ordering behaves differently in development mode, always ensure to check preview deployments to verify the final CSS order in your production build.
|
||||
|
||||
|
|
|
|||
|
|
@ -63,7 +63,7 @@ Add the [Tailwind CSS directives](https://tailwindcss.com/docs/functions-and-dir
|
|||
@tailwind utilities;
|
||||
```
|
||||
|
||||
Inside the [root layout](/docs/app/building-your-application/routing/pages-and-layouts#root-layout-required) (`app/layout.tsx`), import the `globals.css` stylesheet to apply the styles to every route in your application.
|
||||
Inside the [root layout](/docs/app/building-your-application/routing/layouts-and-templates#root-layout-required) (`app/layout.tsx`), import the `globals.css` stylesheet to apply the styles to every route in your application.
|
||||
|
||||
```tsx filename="app/layout.tsx" switcher
|
||||
import type { Metadata } from 'next'
|
||||
|
|
|
|||
|
|
@ -94,7 +94,7 @@ export default function StyledJsxRegistry({ children }) {
|
|||
}
|
||||
```
|
||||
|
||||
Then, wrap your [root layout](/docs/app/building-your-application/routing/pages-and-layouts#root-layout-required) with the registry:
|
||||
Then, wrap your [root layout](/docs/app/building-your-application/routing/layouts-and-templates#root-layout-required) with the registry:
|
||||
|
||||
```tsx filename="app/layout.tsx" switcher
|
||||
import StyledJsxRegistry from './registry'
|
||||
|
|
|
|||
|
|
@ -618,9 +618,9 @@ You can now use the `font-sans` and `font-mono` utility classes to apply the fon
|
|||
<AppOnly>
|
||||
When a font function is called on a page of your site, it is not globally available and preloaded on all routes. Rather, the font is only preloaded on the related routes based on the type of file where it is used:
|
||||
|
||||
- If it's a [unique page](/docs/app/building-your-application/routing/pages-and-layouts#pages), it is preloaded on the unique route for that page.
|
||||
- If it's a [layout](/docs/app/building-your-application/routing/pages-and-layouts#layouts), it is preloaded on all the routes wrapped by the layout.
|
||||
- If it's the [root layout](/docs/app/building-your-application/routing/pages-and-layouts#root-layout-required), it is preloaded on all routes.
|
||||
- If it's a [unique page](/docs/app/building-your-application/routing/pages), it is preloaded on the unique route for that page.
|
||||
- If it's a [layout](/docs/app/building-your-application/routing/layouts-and-templates#layouts), it is preloaded on all the routes wrapped by the layout.
|
||||
- If it's the [root layout](/docs/app/building-your-application/routing/layouts-and-templates#root-layout-required), it is preloaded on all routes.
|
||||
|
||||
</AppOnly>
|
||||
|
||||
|
|
|
|||
|
|
@ -415,7 +415,7 @@ export default function Page() {
|
|||
|
||||
<AppOnly>
|
||||
|
||||
To share a layout across MDX pages, you can use the [built-in layouts support](/docs/app/building-your-application/routing/pages-and-layouts#layouts) with the App Router.
|
||||
To share a layout across MDX pages, you can use the [built-in layouts support](/docs/app/building-your-application/routing/layouts-and-templates#layouts) with the App Router.
|
||||
|
||||
```tsx filename="app/mdx-page/layout.tsx" switcher
|
||||
export default function MdxLayout({ children }: { children: React.ReactNode }) {
|
||||
|
|
|
|||
|
|
@ -1358,7 +1358,7 @@ In the example, we use the `verifySession()` function from our DAL to check for
|
|||
|
||||
### Layouts and auth checks
|
||||
|
||||
Due to [Partial Rendering](/docs/app/building-your-application/routing/linking-and-navigating#4-partial-rendering), be cautious when doing checks in [Layouts](/docs/app/building-your-application/routing/pages-and-layouts) as these don't re-render on navigation, meaning the user session won't be checked on every route change.
|
||||
Due to [Partial Rendering](/docs/app/building-your-application/routing/linking-and-navigating#4-partial-rendering), be cautious when doing checks in [Layouts](/docs/app/building-your-application/routing/layouts-and-templates) as these don't re-render on navigation, meaning the user session won't be checked on every route change.
|
||||
|
||||
Instead, you should do the checks close to your data source or the component that'll be conditionally rendered.
|
||||
|
||||
|
|
|
|||
|
|
@ -39,11 +39,11 @@ While building your application, we recommend using the following features to en
|
|||
|
||||
<AppOnly>
|
||||
|
||||
- **[Layouts](/docs/app/building-your-application/routing/pages-and-layouts#layouts):** Use layouts to share UI across pages and enable [partial rendering](/docs/app/building-your-application/routing/linking-and-navigating#4-partial-rendering) on navigation.
|
||||
- **[Layouts](/docs/app/building-your-application/routing/layouts-and-templates#layouts):** Use layouts to share UI across pages and enable [partial rendering](/docs/app/building-your-application/routing/linking-and-navigating#4-partial-rendering) on navigation.
|
||||
- **[`<Link>` component](/docs/app/building-your-application/routing/linking-and-navigating#link-component):** Use the `<Link>` component for [client-side navigation and prefetching](/docs/app/building-your-application/routing/linking-and-navigating#how-routing-and-navigation-works).
|
||||
- **[Error Handling](/docs/app/building-your-application/routing/error-handling):** Gracefully handle [catch-all errors](/docs/app/building-your-application/routing/error-handling) and [404 errors](/docs/app/api-reference/file-conventions/not-found) in production by creating custom error pages.
|
||||
- **[Composition Patterns](/docs/app/building-your-application/rendering/composition-patterns):** Follow the recommended composition patterns for Server and Client Components, and check the placement of your [`"use client"` boundaries](/docs/app/building-your-application/rendering/composition-patterns#moving-client-components-down-the-tree) to avoid unnecessarily increasing your client-side JavaScript bundle.
|
||||
- **[Dynamic Functions](/docs/app/building-your-application/rendering/server-components#dynamic-functions):** Be aware that dynamic functions like [`cookies()`](/docs/app/api-reference/functions/cookies) and the [`searchParams`](/docs/app/api-reference/file-conventions/page#searchparams-optional) prop will opt the entire route into [Dynamic Rendering](/docs/app/building-your-application/rendering/server-components#dynamic-rendering) (or your whole application if used in the [Root Layout](/docs/app/building-your-application/routing/pages-and-layouts#root-layout-required)). Ensure dynamic function usage is intentional and wrap them in `<Suspense>` boundaries where appropriate.
|
||||
- **[Dynamic Functions](/docs/app/building-your-application/rendering/server-components#dynamic-functions):** Be aware that dynamic functions like [`cookies()`](/docs/app/api-reference/functions/cookies) and the [`searchParams`](/docs/app/api-reference/file-conventions/page#searchparams-optional) prop will opt the entire route into [Dynamic Rendering](/docs/app/building-your-application/rendering/server-components#dynamic-rendering) (or your whole application if used in the [Root Layout](/docs/app/building-your-application/routing/layouts-and-templates#root-layout-required)). Ensure dynamic function usage is intentional and wrap them in `<Suspense>` boundaries where appropriate.
|
||||
|
||||
> **Good to know**: [Partial Prerendering (Experimental)](/blog/next-14#partial-prerendering-preview) will allow parts of a route to be dynamic without opting the whole route into dynamic rendering.
|
||||
|
||||
|
|
|
|||
|
|
@ -90,7 +90,7 @@ Image Optimization can be used with a [static export](/docs/app/building-your-ap
|
|||
|
||||
Middleware uses a [runtime](/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes) that is a subset of all available Node.js APIs to help ensure low latency, since it may run in front of every route or asset in your application. This runtime does not require running “at the edge” and works in a single-region server. Additional configuration and infrastructure are required to run Middleware in multiple regions.
|
||||
|
||||
If you are looking to add logic (or use an external package) that requires all Node.js APIs, you might be able to move this logic to a [layout](/docs/app/building-your-application/routing/pages-and-layouts#layouts) as a [Server Component](/docs/app/building-your-application/rendering/server-components). For example, checking [headers](/docs/app/api-reference/functions/headers) and [redirecting](/docs/app/api-reference/functions/redirect). You can also use headers, cookies, or query parameters to [redirect](/docs/app/api-reference/next-config-js/redirects#header-cookie-and-query-matching) or [rewrite](/docs/app/api-reference/next-config-js/rewrites#header-cookie-and-query-matching) through `next.config.js`. If that does not work, you can also use a [custom server](/docs/pages/building-your-application/configuring/custom-server).
|
||||
If you are looking to add logic (or use an external package) that requires all Node.js APIs, you might be able to move this logic to a [layout](/docs/app/building-your-application/routing/layouts-and-templates#layouts) as a [Server Component](/docs/app/building-your-application/rendering/server-components). For example, checking [headers](/docs/app/api-reference/functions/headers) and [redirecting](/docs/app/api-reference/functions/redirect). You can also use headers, cookies, or query parameters to [redirect](/docs/app/api-reference/next-config-js/redirects#header-cookie-and-query-matching) or [rewrite](/docs/app/api-reference/next-config-js/rewrites#header-cookie-and-query-matching) through `next.config.js`. If that does not work, you can also use a [custom server](/docs/pages/building-your-application/configuring/custom-server).
|
||||
|
||||
### Environment Variables
|
||||
|
||||
|
|
|
|||
|
|
@ -100,7 +100,7 @@ See the [Font Optimization](/docs/app/building-your-application/optimizing/fonts
|
|||
|
||||
> **🎥 Watch:** Learn how to incrementally adopt the App Router → [YouTube (16 minutes)](https://www.youtube.com/watch?v=YQMSietiFm0).
|
||||
|
||||
Moving to the App Router may be the first time using React features that Next.js builds on top of such as Server Components, Suspense, and more. When combined with new Next.js features such as [special files](/docs/app/building-your-application/routing#file-conventions) and [layouts](/docs/app/building-your-application/routing/pages-and-layouts#layouts), migration means new concepts, mental models, and behavioral changes to learn.
|
||||
Moving to the App Router may be the first time using React features that Next.js builds on top of such as Server Components, Suspense, and more. When combined with new Next.js features such as [special files](/docs/app/building-your-application/routing#file-conventions) and [layouts](/docs/app/building-your-application/routing/layouts-and-templates#layouts), migration means new concepts, mental models, and behavioral changes to learn.
|
||||
|
||||
We recommend reducing the combined complexity of these updates by breaking down your migration into smaller steps. The `app` directory is intentionally designed to work simultaneously with the `pages` directory to allow for incremental page-by-page migration.
|
||||
|
||||
|
|
@ -112,7 +112,7 @@ We recommend reducing the combined complexity of these updates by breaking down
|
|||
- `.js`, `.jsx`, or `.tsx` file extensions can be used for special files.
|
||||
- You can colocate other files inside the `app` directory such as components, styles, tests, and more. [Learn more](/docs/app/building-your-application/routing).
|
||||
- Data fetching functions like `getServerSideProps` and `getStaticProps` have been replaced with [a new API](/docs/app/building-your-application/data-fetching) inside `app`. `getStaticPaths` has been replaced with [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params).
|
||||
- `pages/_app.js` and `pages/_document.js` have been replaced with a single `app/layout.js` root layout. [Learn more](/docs/app/building-your-application/routing/pages-and-layouts#root-layout-required).
|
||||
- `pages/_app.js` and `pages/_document.js` have been replaced with a single `app/layout.js` root layout. [Learn more](/docs/app/building-your-application/routing/layouts-and-templates#root-layout-required).
|
||||
- `pages/_error.js` has been replaced with more granular `error.js` special files. [Learn more](/docs/app/building-your-application/routing/error-handling).
|
||||
- `pages/404.js` has been replaced with the [`not-found.js`](/docs/app/api-reference/file-conventions/not-found) file.
|
||||
- `pages/api/*` API Routes have been replaced with the [`route.js`](/docs/app/api-reference/file-conventions/route) (Route Handler) special file.
|
||||
|
|
@ -129,7 +129,7 @@ Then, create a new `app` directory at the root of your project (or `src/` direct
|
|||
|
||||
### Step 2: Creating a Root Layout
|
||||
|
||||
Create a new `app/layout.tsx` file inside the `app` directory. This is a [root layout](/docs/app/building-your-application/routing/pages-and-layouts#root-layout-required) that will apply to all routes inside `app`.
|
||||
Create a new `app/layout.tsx` file inside the `app` directory. This is a [root layout](/docs/app/building-your-application/routing/layouts-and-templates#root-layout-required) that will apply to all routes inside `app`.
|
||||
|
||||
```tsx filename="app/layout.tsx" switcher
|
||||
export default function RootLayout({
|
||||
|
|
@ -192,7 +192,7 @@ If you are using any React Context providers, they will need to be moved to a [C
|
|||
|
||||
#### Migrating the `getLayout()` pattern to Layouts (Optional)
|
||||
|
||||
Next.js recommended adding a [property to Page components](/docs/pages/building-your-application/routing/pages-and-layouts#layout-pattern#per-page-layouts) to achieve per-page layouts in the `pages` directory. This pattern can be replaced with native support for [nested layouts](/docs/app/building-your-application/routing/pages-and-layouts#layouts) in the `app` directory.
|
||||
Next.js recommended adding a [property to Page components](/docs/pages/building-your-application/routing/pages-and-layouts#layout-pattern#per-page-layouts) to achieve per-page layouts in the `pages` directory. This pattern can be replaced with native support for [nested layouts](/docs/app/building-your-application/routing/layouts-and-templates#layouts) in the `app` directory.
|
||||
|
||||
<details>
|
||||
<summary>See before and after example</summary>
|
||||
|
|
@ -731,7 +731,7 @@ export default function Post({ post }) {
|
|||
|
||||
In the `app` directory, `getStaticPaths` is replaced with [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params).
|
||||
|
||||
[`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params) behaves similarly to `getStaticPaths`, but has a simplified API for returning route parameters and can be used inside [layouts](/docs/app/building-your-application/routing/pages-and-layouts). The return shape of `generateStaticParams` is an array of segments instead of an array of nested `param` objects or a string of resolved paths.
|
||||
[`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params) behaves similarly to `getStaticPaths`, but has a simplified API for returning route parameters and can be used inside [layouts](/docs/app/building-your-application/routing/layouts-and-templates). The return shape of `generateStaticParams` is an array of segments instead of an array of nested `param` objects or a string of resolved paths.
|
||||
|
||||
```jsx filename="app/posts/[id]/page.js"
|
||||
// `app` directory
|
||||
|
|
|
|||
|
|
@ -128,7 +128,7 @@ You can find more information about configuring TypeScript on the
|
|||
### Step 4: Create the Root Layout
|
||||
|
||||
A Next.js [App Router](/docs/app) application must include a
|
||||
[root layout](/docs/app/building-your-application/routing/pages-and-layouts#root-layout-required)
|
||||
[root layout](/docs/app/building-your-application/routing/layouts-and-templates#root-layout-required)
|
||||
file, which is a [React Server Component](/docs/app/building-your-application/rendering/server-components)
|
||||
that will wrap all pages in your application. This file is defined at the top level of the `app`
|
||||
directory.
|
||||
|
|
|
|||
|
|
@ -114,7 +114,7 @@ You can find more information about configuring TypeScript on the [Next.js docs]
|
|||
|
||||
### Step 4: Create the Root Layout
|
||||
|
||||
A Next.js [App Router](/docs/app) application must include a [root layout](/docs/app/building-your-application/routing/pages-and-layouts#root-layout-required) file, which is a [React Server Component](/docs/app/building-your-application/rendering/server-components) that will wrap all pages in your application. This file is defined at the top level of the `app` directory.
|
||||
A Next.js [App Router](/docs/app) application must include a [root layout](/docs/app/building-your-application/routing/layouts-and-templates#root-layout-required) file, which is a [React Server Component](/docs/app/building-your-application/rendering/server-components) that will wrap all pages in your application. This file is defined at the top level of the `app` directory.
|
||||
|
||||
The closest equivalent to the root layout file in a CRA application is the `index.html` file, which contains your `<html>`, `<head>`, and `<body>` tags.
|
||||
|
||||
|
|
|
|||
|
|
@ -181,7 +181,7 @@ export default function Page() {
|
|||
|
||||
> **Good to know**:
|
||||
>
|
||||
> - Next.js will scroll to the [Page](/docs/app/building-your-application/routing/pages-and-layouts#pages) if it is not visible in the viewport upon navigation.
|
||||
> - Next.js will scroll to the [Page](/docs/app/building-your-application/routing/pages) if it is not visible in the viewport upon navigation.
|
||||
|
||||
### `prefetch`
|
||||
|
||||
|
|
|
|||
|
|
@ -51,7 +51,7 @@ export default function RootLayout({ children }) {
|
|||
|
||||
### `children` (required)
|
||||
|
||||
Layout components should accept and use a `children` prop. During rendering, `children` will be populated with the route segments the layout is wrapping. These will primarily be the component of a child [Layout](/docs/app/building-your-application/routing/pages-and-layouts#pages) (if it exists) or [Page](/docs/app/building-your-application/routing/pages-and-layouts#pages), but could also be other special files like [Loading](/docs/app/building-your-application/routing/loading-ui-and-streaming) or [Error](/docs/app/building-your-application/routing/error-handling) when applicable.
|
||||
Layout components should accept and use a `children` prop. During rendering, `children` will be populated with the route segments the layout is wrapping. These will primarily be the component of a child [Layout](/docs/app/building-your-application/routing/pages) (if it exists) or [Page](/docs/app/building-your-application/routing/pages), but could also be other special files like [Loading](/docs/app/building-your-application/routing/loading-ui-and-streaming) or [Error](/docs/app/building-your-application/routing/error-handling) when applicable.
|
||||
|
||||
### `params` (optional)
|
||||
|
||||
|
|
@ -92,6 +92,14 @@ export default function ShopLayout({ children, params }) {
|
|||
|
||||
## Good to know
|
||||
|
||||
### Root Layouts
|
||||
|
||||
- The `app` directory **must** include a root `app/layout.js`.
|
||||
- The root layout **must** define `<html>` and `<body>` tags.
|
||||
- You should **not** manually add `<head>` tags such as `<title>` and `<meta>` to root layouts. Instead, you should use the [Metadata API](/docs/app/api-reference/functions/generate-metadata) which automatically handles advanced requirements such as streaming and de-duplicating `<head>` elements.
|
||||
- You can use [route groups](/docs/app/building-your-application/routing/route-groups) to create multiple root layouts.
|
||||
- Navigating **across multiple root layouts** will cause a **full page load** (as opposed to a client-side navigation). For example, navigating from `/cart` that uses `app/(shop)/layout.js` to `/blog` that uses `app/(marketing)/layout.js` will cause a full page load. This **only** applies to multiple root layouts.
|
||||
|
||||
### Layouts do not receive `searchParams`
|
||||
|
||||
Unlike [Pages](/docs/app/api-reference/file-conventions/page), Layout components **do not** receive the `searchParams` prop. This is because a shared layout is [not re-rendered during navigation](/docs/app/building-your-application/routing/linking-and-navigating#4-partial-rendering) which could lead to stale `searchParams` between navigations.
|
||||
|
|
@ -114,15 +122,45 @@ This performance optimization allows navigation between pages that share a layou
|
|||
|
||||
Because `dashboard/layout.tsx` doesn't re-render, the `searchParams` prop in the layout Server Component might become **stale** after navigation.
|
||||
|
||||
- Instead, use the Page [`searchParams`](/docs/app/api-reference/file-conventions/page#searchparams-optional) prop or the [`useSearchParams`](/docs/app/api-reference/functions/use-search-params) hook in a Client Component, which is re-rendered on the client with the latest `searchParams`.
|
||||
Instead, use the Page [`searchParams`](/docs/app/api-reference/file-conventions/page#searchparams-optional) prop or the [`useSearchParams`](/docs/app/api-reference/functions/use-search-params) hook in a Client Component, which is re-rendered on the client with the latest `searchParams`.
|
||||
|
||||
### Root Layouts
|
||||
### Layouts cannot access `pathname`
|
||||
|
||||
- The `app` directory **must** include a root `app/layout.js`.
|
||||
- The root layout **must** define `<html>` and `<body>` tags.
|
||||
- You should **not** manually add `<head>` tags such as `<title>` and `<meta>` to root layouts. Instead, you should use the [Metadata API](/docs/app/api-reference/functions/generate-metadata) which automatically handles advanced requirements such as streaming and de-duplicating `<head>` elements.
|
||||
- You can use [route groups](/docs/app/building-your-application/routing/route-groups) to create multiple root layouts.
|
||||
- Navigating **across multiple root layouts** will cause a **full page load** (as opposed to a client-side navigation). For example, navigating from `/cart` that uses `app/(shop)/layout.js` to `/blog` that uses `app/(marketing)/layout.js` will cause a full page load. This **only** applies to multiple root layouts.
|
||||
Layouts cannot access `pathname`. This is because layouts are Server Components by default, and [don't rerender during client-side navigation](/docs/app/building-your-application/routing/linking-and-navigating#4-partial-rendering), which could lead to `pathname` becoming stale between navigations. To prevent staleness, Next.js would need to refetch all segments of a route, losing the benefits of caching and increasing the [RSC payload](/docs/app/building-your-application/rendering/server-components#what-is-the-react-server-component-payload-rsc) size on navigation.
|
||||
|
||||
Instead, you can extract the logic that depends on pathname into a Client Component and import it into your layouts. Since Client Components rerender (but are not refetched) during navigation, you can use Next.js hooks such as [`usePathname`](https://nextjs.org/docs/app/api-reference/functions/use-pathname) to access the current pathname and prevent staleness.
|
||||
|
||||
```tsx filename="app/dashboard/layout.tsx" switcher
|
||||
import { ClientComponent } from '@/app/ui/ClientComponent'
|
||||
|
||||
export default function Layout({ children }: { children: React.ReactNode }) {
|
||||
return (
|
||||
<>
|
||||
<ClientComponent />
|
||||
{/* Other Layout UI */}
|
||||
<main>{children}</main>
|
||||
<>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/dashboard/layout.js" switcher
|
||||
import { ClientComponent } from '@/app/ui/ClientComponent'
|
||||
|
||||
export default function Layout({ children }) {
|
||||
return (
|
||||
<>
|
||||
<ClientComponent />
|
||||
{/* Other Layout UI */}
|
||||
<main>{children}</main>
|
||||
<>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Common `pathname` patterns can also be implemented with [`params`](#params-optional) prop.
|
||||
|
||||
See the [examples](/docs/app/building-your-application/routing/layouts-and-templates#examples) section for more information.
|
||||
|
||||
## Version History
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ title: Route Segment Config
|
|||
description: Learn about how to configure options for Next.js route segments.
|
||||
---
|
||||
|
||||
The Route Segment options allows you to configure the behavior of a [Page](/docs/app/building-your-application/routing/pages-and-layouts), [Layout](/docs/app/building-your-application/routing/pages-and-layouts), or [Route Handler](/docs/app/building-your-application/routing/route-handlers) by directly exporting the following variables:
|
||||
The Route Segment options allows you to configure the behavior of a [Page](/docs/app/building-your-application/routing/layouts-and-templates), [Layout](/docs/app/building-your-application/routing/layouts-and-templates), or [Route Handler](/docs/app/building-your-application/routing/route-handlers) by directly exporting the following variables:
|
||||
|
||||
| Option | Type | Default |
|
||||
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ title: template.js
|
|||
description: API Reference for the template.js file.
|
||||
---
|
||||
|
||||
A **template** file is similar to a [layout](/docs/app/building-your-application/routing/pages-and-layouts#layouts) in that it wraps a layout or page. Unlike layouts that persist across routes and maintain state, templates are given a unique key, meaning children Client Components reset their state on navigation.
|
||||
A **template** file is similar to a [layout](/docs/app/building-your-application/routing/layouts-and-templates#layouts) in that it wraps a layout or page. Unlike layouts that persist across routes and maintain state, templates are given a unique key, meaning children Client Components reset their state on navigation.
|
||||
|
||||
```tsx filename="app/template.tsx" switcher
|
||||
export default function Template({ children }: { children: React.ReactNode }) {
|
||||
|
|
|
|||
|
|
@ -5,6 +5,6 @@ description: Enable the App Router to use layouts, streaming, and more.
|
|||
|
||||
> **Good to know**: This option is **no longer** needed as of Next.js 13.4. The App Router is now stable.
|
||||
|
||||
The App Router ([`app` directory](/docs/app/building-your-application/routing)) enables support for [layouts](/docs/app/building-your-application/routing/pages-and-layouts), [Server Components](/docs/app/building-your-application/rendering/server-components), [streaming](/docs/app/building-your-application/routing/loading-ui-and-streaming), and [colocated data fetching](/docs/app/building-your-application/data-fetching).
|
||||
The App Router ([`app` directory](/docs/app/building-your-application/routing)) enables support for [layouts](/docs/app/building-your-application/routing/layouts-and-templates), [Server Components](/docs/app/building-your-application/rendering/server-components), [streaming](/docs/app/building-your-application/routing/loading-ui-and-streaming), and [colocated data fetching](/docs/app/building-your-application/data-fetching).
|
||||
|
||||
Using the `app` directory will automatically enable [React Strict Mode](https://react.dev/reference/react/StrictMode). Learn how to [incrementally adopt `app`](/docs/app/building-your-application/upgrading/app-router-migration#migrating-from-pages-to-app).
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ description: Use the new App Router with Next.js' and React's latest features, i
|
|||
|
||||
The Next.js App Router introduces a new model for building applications using React's latest features such as [Server Components](/docs/app/building-your-application/rendering/server-components), [Streaming with Suspense](/docs/app/building-your-application/routing/loading-ui-and-streaming#streaming-with-suspense), and [Server Actions](/docs/app/building-your-application/data-fetching/server-actions-and-mutations).
|
||||
|
||||
Get started with the App Router by [creating your first page](/docs/app/building-your-application/routing/pages-and-layouts).
|
||||
Get started with the App Router by [creating your first page](/docs/app/building-your-application/routing/layouts-and-templates).
|
||||
|
||||
## Frequently Asked Questions
|
||||
|
||||
|
|
@ -13,7 +13,7 @@ Get started with the App Router by [creating your first page](/docs/app/building
|
|||
|
||||
You intentionally cannot access the raw request object. However, you can access [`headers`](/docs/app/api-reference/functions/headers) and [`cookies`](/docs/app/api-reference/functions/cookies) through server-only functions. You can also [set cookies](#how-can-i-set-cookies).
|
||||
|
||||
[Layouts](/docs/app/building-your-application/routing/pages-and-layouts#layouts) do not rerender. They can be cached and reused to avoid unnecessary computation when navigating between pages. By restricting layouts from accessing the raw request, Next.js can prevent the execution of potentially slow or expensive user code within the layout, which could negatively impact performance.
|
||||
[Layouts](/docs/app/building-your-application/routing/layouts-and-templates#layouts) do not rerender. They can be cached and reused to avoid unnecessary computation when navigating between pages. By restricting layouts from accessing the raw request, Next.js can prevent the execution of potentially slow or expensive user code within the layout, which could negatively impact performance.
|
||||
|
||||
This design also enforces consistent and predictable behavior for layouts across different pages, which simplifies development and debugging.
|
||||
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@ The `Component` prop is the active `page`, so whenever you navigate between rout
|
|||
|
||||
Using [`getInitialProps`](/docs/pages/api-reference/functions/get-initial-props) in `App` will disable [Automatic Static Optimization](/docs/pages/building-your-application/rendering/automatic-static-optimization) for pages without [`getStaticProps`](/docs/pages/building-your-application/data-fetching/get-static-props).
|
||||
|
||||
**We do not recommend using this pattern.** Instead, consider [incrementally adopting](/docs/app/building-your-application/upgrading/app-router-migration) the App Router, which allows you to more easily fetch data for [pages and layouts](/docs/app/building-your-application/routing/pages-and-layouts).
|
||||
**We do not recommend using this pattern.** Instead, consider [incrementally adopting](/docs/app/building-your-application/upgrading/app-router-migration) the App Router, which allows you to more easily fetch data for [pages and layouts](/docs/app/building-your-application/routing/layouts-and-templates).
|
||||
|
||||
```tsx filename="pages/_app.tsx" switcher
|
||||
import App, { AppContext, AppInitialProps, AppProps } from 'next/app'
|
||||
|
|
|
|||
|
|
@ -54,7 +54,7 @@ export default function Document() {
|
|||
|
||||
Customizing `renderPage` is advanced and only needed for libraries like CSS-in-JS to support server-side rendering. This is not needed for built-in `styled-jsx` support.
|
||||
|
||||
**We do not recommend using this pattern.** Instead, consider [incrementally adopting](/docs/app/building-your-application/upgrading/app-router-migration) the App Router, which allows you to more easily fetch data for [pages and layouts](/docs/app/building-your-application/routing/pages-and-layouts).
|
||||
**We do not recommend using this pattern.** Instead, consider [incrementally adopting](/docs/app/building-your-application/upgrading/app-router-migration) the App Router, which allows you to more easily fetch data for [pages and layouts](/docs/app/building-your-application/routing/layouts-and-templates).
|
||||
|
||||
```tsx filename="pages/_document.tsx" switcher
|
||||
import Document, {
|
||||
|
|
|
|||
|
|
@ -28,4 +28,4 @@ export default function Layout({ children }: { children: React.ReactNode }) {
|
|||
|
||||
### Useful Links
|
||||
|
||||
- [Root Layout](https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts#root-layout-required)
|
||||
- [Root Layout](https://nextjs.org/docs/app/building-your-application/routing/layouts-and-templates#root-layout-required)
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
This is the existing [blog-starter](https://github.com/vercel/next.js/tree/canary/examples/blog-starter) plus TypeScript.
|
||||
|
||||
This example showcases Next.js's [Static Generation](https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts) feature using Markdown files as the data source.
|
||||
This example showcases Next.js's [Static Generation](https://nextjs.org/docs/app/building-your-application/routing/layouts-and-templates) feature using Markdown files as the data source.
|
||||
|
||||
The blog posts are stored in `/_posts` as Markdown files with front matter support. Adding a new Markdown file in there will create a new blog post.
|
||||
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ export function Footer() {
|
|||
</h3>
|
||||
<div className="flex flex-col lg:flex-row justify-center items-center lg:pl-4 lg:w-1/2">
|
||||
<a
|
||||
href="https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts"
|
||||
href="https://nextjs.org/docs/app/building-your-application/routing/layouts-and-templates"
|
||||
className="mx-3 bg-black hover:bg-white hover:text-black border border-black text-white font-bold py-3 px-12 lg:px-8 duration-200 transition-colors mb-6 lg:mb-0"
|
||||
>
|
||||
Read Documentation
|
||||
|
|
|
|||
Loading…
Reference in a new issue