Unverified Commit 694bd3e2 authored by Stephanie Dietz's avatar Stephanie Dietz Committed by GitHub

docs: Add "Going to production" page for App Router (#59304)

- Add **Going to Prod** docs for `app`
- Add bundle-analyzer page
- Merge `app` and `pages` docs

---------
Co-authored-by: 's avatarDelba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Co-authored-by: 's avatarTim Neutkens <tim@timneutkens.nl>
Co-authored-by: 's avatarMichael Novotny <manovotny@gmail.com>
Co-authored-by: 's avatarDelba de Oliveira <delbabrown@gmail.com>
Co-authored-by: 's avatarRich Haines <hello@richardhaines.dev>
Co-authored-by: 's avatarLee Robinson <me@leerob.io>
parent ae09d7e6
...@@ -16,7 +16,7 @@ This page will go through how to use `<Link>`, `useRouter()`, and dive deeper in ...@@ -16,7 +16,7 @@ This page will go through how to use `<Link>`, `useRouter()`, and dive deeper in
## `<Link>` Component ## `<Link>` Component
`<Link>` is a built-in component that extends the HTML `<a>` tag to provide [prefetching](#1-prefetching) and client-side navigation between routes. It is the primary way to navigate between routes in Next.js. `<Link>` is a built-in component that extends the HTML `<a>` tag to provide [prefetching](#2-prefetching) and client-side navigation between routes. It is the primary way to navigate between routes in Next.js.
You can use it by importing it from `next/link`, and passing a `href` prop to the component: You can use it by importing it from `next/link`, and passing a `href` prop to the component:
...@@ -185,9 +185,15 @@ For a full list of `useRouter` methods, see the [API reference](/docs/app/api-re ...@@ -185,9 +185,15 @@ For a full list of `useRouter` methods, see the [API reference](/docs/app/api-re
## How Routing and Navigation Works ## How Routing and Navigation Works
The App Router uses a hybrid approach for routing and navigation. On the server, your application code is automatically code-split by route segments. And on the client, Next.js [prefetches](#1-prefetching) and [caches](#2-caching) the route segments. This means, when a user navigates to a new route, the browser doesn't reload the page, and only the route segments that change re-render - improving the navigation experience and performance. The App Router uses a hybrid approach for routing and navigation. On the server, your application code is automatically [code-split](#1-code-splitting) by route segments. And on the client, Next.js [prefetches](#2-prefetching) and [caches](#3-caching) the route segments. This means, when a user navigates to a new route, the browser doesn't reload the page, and only the route segments that change re-render - improving the navigation experience and performance.
### 1. Prefetching ### 1. Code Splitting
Code splitting allows you to split your application code into smaller bundles to be downloaded and executed by the browser. This reduces the amount of data transferred and execution time for each request, leading to improved performance.
Server Components allow your application code to be automatically code-split by route segments. This means only the code needed for the current route is loaded on navigation.
### 2. Prefetching
Prefetching is a way to preload a route in the background before the user visits it. Prefetching is a way to preload a route in the background before the user visits it.
...@@ -209,15 +215,15 @@ See the [`<Link>` API reference](/docs/app/api-reference/components/link) for mo ...@@ -209,15 +215,15 @@ See the [`<Link>` API reference](/docs/app/api-reference/components/link) for mo
> >
> - Prefetching is not enabled in development, only in production. > - Prefetching is not enabled in development, only in production.
### 2. Caching ### 3. Caching
Next.js has an **in-memory client-side cache** called the [Router Cache](/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#caching-data#router-cache). As users navigate around the app, the React Server Component Payload of [prefetched](#1-prefetching) route segments and visited routes are stored in the cache. Next.js has an **in-memory client-side cache** called the [Router Cache](/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#caching-data#router-cache). As users navigate around the app, the React Server Component Payload of [prefetched](#2-prefetching) route segments and visited routes are stored in the cache.
This means on navigation, the cache is reused as much as possible, instead of making a new request to the server - improving performance by reducing the number of requests and data transferred. This means on navigation, the cache is reused as much as possible, instead of making a new request to the server - improving performance by reducing the number of requests and data transferred.
Learn more about how the [Router Cache](/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#caching-data) works and how to configure it. Learn more about how the [Router Cache](/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#caching-data) works and how to configure it.
### 3. Partial Rendering ### 4. Partial Rendering
Partial rendering means only the route segments that change on navigation re-render on the client, and any shared segments are preserved. Partial rendering means only the route segments that change on navigation re-render on the client, and any shared segments are preserved.
...@@ -233,10 +239,10 @@ For example, when navigating between two sibling routes, `/dashboard/settings` a ...@@ -233,10 +239,10 @@ For example, when navigating between two sibling routes, `/dashboard/settings` a
Without partial rendering, each navigation would cause the full page to re-render on the server. Rendering only the segment that changes reduces the amount of data transferred and execution time, leading to improved performance. Without partial rendering, each navigation would cause the full page to re-render on the server. Rendering only the segment that changes reduces the amount of data transferred and execution time, leading to improved performance.
### 4. Soft Navigation ### 5. Soft Navigation
Browsers perform a "hard navigation" when navigating between pages. The Next.js App Router enables "soft navigation" between pages, ensuring only the route segments that have changed are re-rendered (partial rendering). This enables client React state to be preserved during navigation. Browsers perform a "hard navigation" when navigating between pages. The Next.js App Router enables "soft navigation" between pages, ensuring only the route segments that have changed are re-rendered (partial rendering). This enables client React state to be preserved during navigation.
### 5. Back and Forward Navigation ### 6. Back and Forward Navigation
By default, Next.js will maintain the scroll position for backwards and forwards navigation, and re-use route segments in the [Router Cache](/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#caching-data). By default, Next.js will maintain the scroll position for backwards and forwards navigation, and re-use route segments in the [Router Cache](/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#caching-data).
...@@ -6,7 +6,7 @@ description: Learn about common data fetching patterns in React and Next.js. ...@@ -6,7 +6,7 @@ description: Learn about common data fetching patterns in React and Next.js.
There are a few recommended patterns and best practices for fetching data in React and Next.js. This page will go over some of the most common patterns and how to use them. There are a few recommended patterns and best practices for fetching data in React and Next.js. This page will go over some of the most common patterns and how to use them.
## Fetching Data on the Server ## Fetching data on the server
Whenever possible, we recommend fetching data on the server with Server Components. This allows you to: Whenever possible, we recommend fetching data on the server with Server Components. This allows you to:
...@@ -19,7 +19,7 @@ Whenever possible, we recommend fetching data on the server with Server Componen ...@@ -19,7 +19,7 @@ Whenever possible, we recommend fetching data on the server with Server Componen
Then, you can mutate or update data with [Server Actions](/docs/app/building-your-application/data-fetching/server-actions-and-mutations). Then, you can mutate or update data with [Server Actions](/docs/app/building-your-application/data-fetching/server-actions-and-mutations).
## Fetching Data Where It's Needed ## Fetching data where it's needed
If you need to use the same data (e.g. current user) in multiple components in a tree, you do not have to fetch data globally, nor forward props between components. Instead, you can use `fetch` or React `cache` in the component that needs the data without worrying about the performance implications of making multiple requests for the same data. If you need to use the same data (e.g. current user) in multiple components in a tree, you do not have to fetch data globally, nor forward props between components. Instead, you can use `fetch` or React `cache` in the component that needs the data without worrying about the performance implications of making multiple requests for the same data.
...@@ -43,7 +43,7 @@ With Server Components and [nested layouts](/docs/app/building-your-application/ ...@@ -43,7 +43,7 @@ With Server Components and [nested layouts](/docs/app/building-your-application/
To learn more about Streaming and Suspense, see the [Loading UI](/docs/app/building-your-application/routing/loading-ui-and-streaming) and [Streaming and Suspense](/docs/app/building-your-application/routing/loading-ui-and-streaming#streaming-with-suspense) pages. To learn more about Streaming and Suspense, see the [Loading UI](/docs/app/building-your-application/routing/loading-ui-and-streaming) and [Streaming and Suspense](/docs/app/building-your-application/routing/loading-ui-and-streaming#streaming-with-suspense) pages.
### Parallel and Sequential Data Fetching ## Parallel and sequential data fetching
When fetching data inside React components, you need to be aware of two data fetching patterns: Parallel and Sequential. When fetching data inside React components, you need to be aware of two data fetching patterns: Parallel and Sequential.
......
...@@ -341,11 +341,11 @@ Next.js has an in-memory client-side cache that stores the React Server Componen ...@@ -341,11 +341,11 @@ Next.js has an in-memory client-side cache that stores the React Server Componen
height="1375" height="1375"
/> />
As a user navigates between routes, Next.js caches visited route segments and [prefetches](/docs/app/building-your-application/routing/linking-and-navigating#1-prefetching) the routes the user is likely to navigate to (based on `<Link>` components in their viewport). As a user navigates between routes, Next.js caches visited route segments and [prefetches](/docs/app/building-your-application/routing/linking-and-navigating#2-prefetching) the routes the user is likely to navigate to (based on `<Link>` components in their viewport).
This results in an improved navigation experience for the user: This results in an improved navigation experience for the user:
- Instant backward/forward navigation because visited routes are cached and fast navigation to new routes because of prefetching and [partial rendering](/docs/app/building-your-application/routing/linking-and-navigating#3-partial-rendering). - Instant backward/forward navigation because visited routes are cached and fast navigation to new routes because of prefetching and [partial rendering](/docs/app/building-your-application/routing/linking-and-navigating#4-partial-rendering).
- No full-page reload between navigations, and React state and browser state are preserved. - No full-page reload between navigations, and React state and browser state are preserved.
> **Difference between the Router Cache and Full Route Cache**: > **Difference between the Router Cache and Full Route Cache**:
......
--- ---
title: Static Assets title: Statics Assets in `public`
nav_title: Static Assets
description: Next.js allows you to serve static files, like images, in the public directory. You can learn how it works here. description: Next.js allows you to serve static files, like images, in the public directory. You can learn how it works here.
--- ---
...@@ -17,9 +18,19 @@ export function Avatar() { ...@@ -17,9 +18,19 @@ export function Avatar() {
} }
``` ```
## Caching
Next.js automatically adds caching headers to immutable assets in the `public` folder. The default caching headers applied are:
```jsx
Cache-Control: public, max-age=31536000, immutable
```
## Robots, Favicons, and others
<PagesOnly> <PagesOnly>
This folder is also useful for `robots.txt`, `favicon.ico`, Google Site Verification, and any other static files (including `.html`). But make sure to not have a static file with the same name as a file in the `pages/` directory, as this will result in an error. [Read more](/docs/messages/conflicting-public-file-page). The folder is also useful for `robots.txt`, `favicon.ico`, Google Site Verification, and any other static files (including `.html`). But make sure to not have a static file with the same name as a file in the `pages/` directory, as this will result in an error. [Read more](/docs/messages/conflicting-public-file-page).
</PagesOnly> </PagesOnly>
......
---
title: Bundle Analyzer
description: Analyze the size of your JavaScript bundles using the @next/bundle-analyzer plugin.
related:
description: Learn more about optimizing your application for production.
links:
- app/building-your-application/deploying/production-checklist
---
[`@next/bundle-analyzer`](https://www.npmjs.com/package/@next/bundle-analyzer) is a plugin for Next.js that helps you manage the size of your JavaScript modules. It generates a visual report of the size of each module and their dependencies. You can use the information to remove large dependencies, split your code, or only load some parts when needed, reducing the amount of data transferred to the client.
## Installation
Install the plugin by running the following command:
```bash
npm i @next/bundle-analyzers
# or
yarn add @next/bundle-analyzer
# or
pnpm i @next/bundle-analyzer
```
Then, add the bundle analyzer's settings to your `next.config.js`.
```js filename="next.config.js"
const withBundleAnalyzer = require('@next/bundle-analyzer')({
enabled: process.env.ANALYZE === 'true',
})
/** @type {import('next').NextConfig} */
const nextConfig = {}
module.exports = withBundleAnalyzer(nextConfig)
```
## Analyzing your bundles
Run the following command to analyze your bundles:
```bash
ANALYZE=true npm run build
# or
ANALYZE=true yarn build
# or
ANALYZE=true pnpm build
```
The report will open two new tab in your browser, which you can inspect. Doing this regularly while you develop and before deploying your site can help you identify large bundles earlier, and architect your application to be more performant.
...@@ -17,7 +17,7 @@ description: Enable fast client-side navigation with the built-in `next/link` co ...@@ -17,7 +17,7 @@ description: Enable fast client-side navigation with the built-in `next/link` co
</PagesOnly> </PagesOnly>
`<Link>` is a React component that extends the HTML `<a>` element to provide [prefetching](/docs/app/building-your-application/routing/linking-and-navigating#1-prefetching) and client-side navigation between routes. It is the primary way to navigate between routes in Next.js. `<Link>` is a React component that extends the HTML `<a>` element to provide [prefetching](/docs/app/building-your-application/routing/linking-and-navigating#2-prefetching) and client-side navigation between routes. It is the primary way to navigate between routes in Next.js.
<AppOnly> <AppOnly>
......
...@@ -94,7 +94,7 @@ export default function ShopLayout({ children, params }) { ...@@ -94,7 +94,7 @@ export default function ShopLayout({ children, params }) {
### Layouts do not receive `searchParams` ### 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#3-partial-rendering) which could lead to stale `searchParams` between navigations. 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.
When using client-side navigation, Next.js automatically only renders the part of the page below the common layout between two routes. When using client-side navigation, Next.js automatically only renders the part of the page below the common layout between two routes.
......
...@@ -44,7 +44,7 @@ export default function Page() { ...@@ -44,7 +44,7 @@ export default function Page() {
- `router.push(href: string, { scroll: boolean })`: Perform a client-side navigation to the provided route. Adds a new entry into the [browser’s history](https://developer.mozilla.org/docs/Web/API/History_API) stack. - `router.push(href: string, { scroll: boolean })`: Perform a client-side navigation to the provided route. Adds a new entry into the [browser’s history](https://developer.mozilla.org/docs/Web/API/History_API) stack.
- `router.replace(href: string, { scroll: boolean })`: Perform a client-side navigation to the provided route without adding a new entry into the [browser’s history stack](https://developer.mozilla.org/docs/Web/API/History_API). - `router.replace(href: string, { scroll: boolean })`: Perform a client-side navigation to the provided route without adding a new entry into the [browser’s history stack](https://developer.mozilla.org/docs/Web/API/History_API).
- `router.refresh()`: Refresh the current route. Making a new request to the server, re-fetching data requests, and re-rendering Server Components. The client will merge the updated React Server Component payload without losing unaffected client-side React (e.g. `useState`) or browser state (e.g. scroll position). - `router.refresh()`: Refresh the current route. Making a new request to the server, re-fetching data requests, and re-rendering Server Components. The client will merge the updated React Server Component payload without losing unaffected client-side React (e.g. `useState`) or browser state (e.g. scroll position).
- `router.prefetch(href: string)`: [Prefetch](/docs/app/building-your-application/routing/linking-and-navigating#1-prefetching) the provided route for faster client-side transitions. - `router.prefetch(href: string)`: [Prefetch](/docs/app/building-your-application/routing/linking-and-navigating#2-prefetching) the provided route for faster client-side transitions.
- `router.back()`: Navigate back to the previous route in the browser’s history stack. - `router.back()`: Navigate back to the previous route in the browser’s history stack.
- `router.forward()`: Navigate forwards to the next page in the browser’s history stack. - `router.forward()`: Navigate forwards to the next page in the browser’s history stack.
......
...@@ -71,7 +71,7 @@ const searchParams = useSearchParams() ...@@ -71,7 +71,7 @@ const searchParams = useSearchParams()
> **Good to know**: > **Good to know**:
> >
> - `useSearchParams` is a [Client Component](/docs/app/building-your-application/rendering/client-components) hook and is **not supported** in [Server Components](/docs/app/building-your-application/rendering/server-components) to prevent stale values during [partial rendering](/docs/app/building-your-application/routing/linking-and-navigating#3-partial-rendering). > - `useSearchParams` is a [Client Component](/docs/app/building-your-application/rendering/client-components) hook and is **not supported** in [Server Components](/docs/app/building-your-application/rendering/server-components) to prevent stale values during [partial rendering](/docs/app/building-your-application/routing/linking-and-navigating#4-partial-rendering).
> - If an application includes the `/pages` directory, `useSearchParams` will return `ReadonlyURLSearchParams | null`. The `null` value is for compatibility during migration since search params cannot be known during pre-rendering of a page that doesn't use `getServerSideProps` > - If an application includes the `/pages` directory, `useSearchParams` will return `ReadonlyURLSearchParams | null`. The `null` value is for compatibility during migration since search params cannot be known during pre-rendering of a page that doesn't use `getServerSideProps`
## Behavior ## Behavior
...@@ -256,7 +256,7 @@ To access search params in [Pages](/docs/app/api-reference/file-conventions/page ...@@ -256,7 +256,7 @@ To access search params in [Pages](/docs/app/api-reference/file-conventions/page
#### Layouts #### Layouts
Unlike Pages, [Layouts](/docs/app/api-reference/file-conventions/layout) (Server 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#3-partial-rendering) which could lead to stale `searchParams` between navigations. View [detailed explanation](/docs/app/api-reference/file-conventions/layout#layouts-do-not-receive-searchparams). Unlike Pages, [Layouts](/docs/app/api-reference/file-conventions/layout) (Server 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. View [detailed explanation](/docs/app/api-reference/file-conventions/layout#layouts-do-not-receive-searchparams).
Instead, use the Page [`searchParams`](/docs/app/api-reference/file-conventions/page) 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) 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`.
......
---
title: Bundle Analyzer
description: Analyze the size of your JavaScript bundles using the @next/bundle-analyzer plugin.
source: app/building-your-application/optimizing/bundle-analyzer
related:
description: Learn more about optimizing your application for production.
links:
- pages/building-your-application/deploying/production-checklist
---
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment