mirror of
https://github.com/hanzoai/next.js.git
synced 2026-09-24 17:00:51 +00:00
Fixes a typo related to how using `searchParams` opts into dynamic rendering. <!-- Thanks for opening a PR! Your contribution is much appreciated. To make sure your PR is handled as smoothly as possible we request that you follow the checklist sections below. Choose the right checklist for the change(s) that you're making: ## For Contributors ### Improving Documentation - Run `pnpm prettier-fix` to fix formatting issues before opening the PR. - Read the Docs Contribution Guide to ensure your contribution follows the docs guidelines: https://nextjs.org/docs/community/contribution-guide ### Adding or Updating Examples - The "examples guidelines" are followed from our contributing doc https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md - Make sure the linting passes by running `pnpm build && pnpm lint`. See https://github.com/vercel/next.js/blob/canary/contributing/repository/linting.md ### Fixing a bug - Related issues linked using `fixes #number` - Tests added. See: https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs - Errors have a helpful link attached, see https://github.com/vercel/next.js/blob/canary/contributing.md ### Adding a feature - Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR. (A discussion must be opened, see https://github.com/vercel/next.js/discussions/new?category=ideas) - Related issues/discussions are linked using `fixes #number` - e2e tests added (https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs) - Documentation added - Telemetry added. In case of a feature if it's used or not. - Errors have a helpful link attached, see https://github.com/vercel/next.js/blob/canary/contributing.md ## For Maintainers - Minimal description (aim for explaining to someone not on the team to understand the PR) - When linking to a Slack thread, you might want to share details of the conclusion - Link both the Linear (Fixes NEXT-xxx) and the GitHub issues - Add review comments if necessary to explain to the reviewer the logic behind a change ### What? ### Why? ### How? Closes NEXT- Fixes # --> Closes NEXT-2993
134 lines
9.8 KiB
Plaintext
134 lines
9.8 KiB
Plaintext
---
|
|
title: Server Components
|
|
description: Learn how you can use React Server Components to render parts of your application on the server.
|
|
related:
|
|
description: Learn how Next.js caches data and the result of static rendering.
|
|
links:
|
|
- app/building-your-application/caching
|
|
---
|
|
|
|
React Server Components allow you to write UI that can be rendered and optionally cached on the server. In Next.js, the rendering work is further split by route segments to enable streaming and partial rendering, and there are three different server rendering strategies:
|
|
|
|
- [Static Rendering](#static-rendering-default)
|
|
- [Dynamic Rendering](#dynamic-rendering)
|
|
- [Streaming](#streaming)
|
|
|
|
This page will go through how Server Components work, when you might use them, and the different server rendering strategies.
|
|
|
|
## Benefits of Server Rendering
|
|
|
|
There are a couple of benefits to doing the rendering work on the server, including:
|
|
|
|
- **Data Fetching**: Server Components allow you to move data fetching to the server, closer to your data source. This can improve performance by reducing time it takes to fetch data needed for rendering, and the number of requests the client needs to make.
|
|
- **Security**: Server Components allow you to keep sensitive data and logic on the server, such as tokens and API keys, without the risk of exposing them to the client.
|
|
- **Caching**: By rendering on the server, the result can be cached and reused on subsequent requests and across users. This can improve performance and reduce cost by reducing the amount of rendering and data fetching done on each request.
|
|
- **Performance**: Server Components give you additional tools to optimize performance from the baseline. For example, if you start with an app composed of entirely Client Components, moving non-interactive pieces of your UI to Server Components can reduce the amount of client-side JavaScript needed. This is beneficial for users with slower internet or less powerful devices, as the browser has less client-side JavaScript to download, parse, and execute.
|
|
- **Initial Page Load and [First Contentful Paint (FCP)](https://web.dev/fcp/)**: On the server, we can generate HTML to allow users to view the page immediately, without waiting for the client to download, parse and execute the JavaScript needed to render the page.
|
|
- **Search Engine Optimization and Social Network Shareability**: The rendered HTML can be used by search engine bots to index your pages and social network bots to generate social card previews for your pages.
|
|
- **Streaming**: Server Components allow you to split the rendering work into chunks and stream them to the client as they become ready. This allows the user to see parts of the page earlier without having to wait for the entire page to be rendered on the server.
|
|
|
|
## Using Server Components in Next.js
|
|
|
|
By default, Next.js uses Server Components. This allows you to automatically implement server rendering with no additional configuration, and you can opt into using Client Components when needed, see [Client Components](/docs/app/building-your-application/rendering/client-components).
|
|
|
|
## How are Server Components rendered?
|
|
|
|
On the server, Next.js uses React's APIs to orchestrate rendering. The rendering work is split into chunks: by individual route segments and [Suspense Boundaries](https://react.dev/reference/react/Suspense).
|
|
|
|
Each chunk is rendered in two steps:
|
|
|
|
1. React renders Server Components into a special data format called the **React Server Component Payload (RSC Payload)**.
|
|
2. Next.js uses the RSC Payload and Client Component JavaScript instructions to render **HTML** on the server.
|
|
|
|
{/* Rendering Diagram */}
|
|
|
|
Then, on the client:
|
|
|
|
1. The HTML is used to immediately show a fast non-interactive preview of the route - this is for the initial page load only.
|
|
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)?**
|
|
>
|
|
> 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:
|
|
>
|
|
> - The rendered result of Server Components
|
|
> - Placeholders for where Client Components should be rendered and references to their JavaScript files
|
|
> - Any props passed from a Server Component to a Client Component
|
|
|
|
## Server Rendering Strategies
|
|
|
|
There are three subsets of server rendering: Static, Dynamic, and Streaming.
|
|
|
|
### Static Rendering (Default)
|
|
|
|
{/* Static Rendering Diagram */}
|
|
|
|
With Static Rendering, routes are rendered at **build time**, or in the background after [data revalidation](/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#revalidating-data). The result is cached and can be pushed to a [Content Delivery Network (CDN)](https://developer.mozilla.org/docs/Glossary/CDN). This optimization allows you to share the result of the rendering work between users and server requests.
|
|
|
|
Static rendering is useful when a route has data that is not personalized to the user and can be known at build time, such as a static blog post or a product page.
|
|
|
|
### Dynamic Rendering
|
|
|
|
{/* Dynamic Rendering Diagram */}
|
|
|
|
With Dynamic Rendering, routes are rendered for each user at **request time**.
|
|
|
|
Dynamic rendering is useful when a route has data that is personalized to the user or has information that can only be known at request time, such as cookies or the URL's search params.
|
|
|
|
> **Dynamic Routes with Cached Data**
|
|
>
|
|
> In most websites, routes are not fully static or fully dynamic - it's a spectrum. For example, you can have an e-commerce page that uses cached product data that's revalidated at an interval, but also has uncached, personalized customer data.
|
|
>
|
|
> In Next.js, you can have dynamically rendered routes that have both cached and uncached data. This is because the RSC Payload and data are cached separately. This allows you to opt into dynamic rendering without worrying about the performance impact of fetching all the data at request time.
|
|
>
|
|
> Learn more about the [full-route cache](/docs/app/building-your-application/caching#full-route-cache) and [Data Cache](/docs/app/building-your-application/caching#data-cache).
|
|
|
|
#### Switching to Dynamic Rendering
|
|
|
|
During rendering, if a [dynamic function](#dynamic-functions) or [uncached data request](/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#opting-out-of-data-caching) is discovered, Next.js will switch to dynamically rendering the whole route. This table summarizes how dynamic functions and data caching affect whether a route is statically or dynamically rendered:
|
|
|
|
| Dynamic Functions | Data | Route |
|
|
| ----------------- | ---------- | -------------------- |
|
|
| No | Cached | Statically Rendered |
|
|
| Yes | Cached | Dynamically Rendered |
|
|
| No | Not Cached | Dynamically Rendered |
|
|
| Yes | Not Cached | Dynamically Rendered |
|
|
|
|
In the table above, for a route to be fully static, all data must be cached. However, you can have a dynamically rendered route that uses both cached and uncached data fetches.
|
|
|
|
As a developer, you do not need to choose between static and dynamic rendering as Next.js will automatically choose the best rendering strategy for each route based on the features and APIs used. Instead, you choose when to [cache or revalidate specific data](/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating), and you may choose to [stream](#streaming) parts of your UI.
|
|
|
|
#### Dynamic Functions
|
|
|
|
Dynamic functions rely on information that can only be known at request time such as a user's cookies, current requests headers, or the URL's search params. In Next.js, these dynamic functions are:
|
|
|
|
- **[`cookies()`](/docs/app/api-reference/functions/cookies) and [`headers()`](/docs/app/api-reference/functions/headers)**: Using these in a Server Component will opt the whole route into dynamic rendering at request time.
|
|
- **[`searchParams`](/docs/app/api-reference/file-conventions/page#searchparams-optional)**: Using the `searchParams` prop on a [Page](/docs/app/api-reference/file-conventions/page) will opt the page into dynamic rendering at request time.
|
|
|
|
Using any of these functions will opt the whole route into dynamic rendering at request time.
|
|
|
|
### Streaming
|
|
|
|
<Image
|
|
alt="Diagram showing parallelization of route segments during streaming, showing data fetching, rendering, and hydration of individual chunks."
|
|
srcLight="/docs/light/sequential-parallel-data-fetching.png"
|
|
srcDark="/docs/dark/sequential-parallel-data-fetching.png"
|
|
width="1600"
|
|
height="525"
|
|
/>
|
|
|
|
Streaming enables you to progressively render UI from the server. Work is split into chunks and streamed to the client as it becomes ready. This allows the user to see parts of the page immediately, before the entire content has finished rendering.
|
|
|
|
<Image
|
|
alt="Diagram showing partially rendered page on the client, with loading UI for chunks that are being streamed."
|
|
srcLight="/docs/light/server-rendering-with-streaming.png"
|
|
srcDark="/docs/dark/server-rendering-with-streaming.png"
|
|
width="1600"
|
|
height="785"
|
|
/>
|
|
|
|
Streaming is built into the Next.js App Router by default. This helps improve both the initial page loading performance, as well as UI that depends on slower data fetches that would block rendering the whole route. For example, reviews on a product page.
|
|
|
|
You can start streaming route segments using `loading.js` and UI components with [React Suspense](/docs/app/building-your-application/routing/loading-ui-and-streaming). See the [Loading UI and Streaming](/docs/app/building-your-application/routing/loading-ui-and-streaming) section for more information.
|