docs: Adds Note to Good to know consistency (#51080)
* Changes all `Note` → `Good to know` * Consistently puts the colon on the outside of bold text * Documents singe and multi-line styles in contribution guide --------- Co-authored-by: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
This commit is contained in:
Michael Novotny
GitHub
parent
6e9113fe59
commit
cefdb27662
92 changed files with 213 additions and 203 deletions
|
|
@ -39,7 +39,7 @@ Next.js now ships with TypeScript, ESLint, and Tailwind CSS configuration by def
|
|||
|
||||
After the prompts, `create-next-app` will create a folder with your project name and install the required dependencies.
|
||||
|
||||
> **Note:** While you can use the [Pages Router](/docs/pages) in your new project. We recommend starting new applications with the App Router to leverage React's latest features.
|
||||
> **Good to know**: While you can use the [Pages Router](/docs/pages) in your new project. We recommend starting new applications with the App Router to leverage React's latest features.
|
||||
|
||||
## Manual Installation
|
||||
|
||||
|
|
|
|||
|
|
@ -99,7 +99,7 @@ export default function Counter() {
|
|||
|
||||
Since Server Components are the default, all components are part of the Server Component module graph unless defined or imported in a module that starts with the `"use client"` directive.
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - Components in the Server Component module graph are guaranteed to be only rendered on the server.
|
||||
> - Components in the Client Component module graph are primarily rendered on the client, but with Next.js, they can also be pre-rendered on the server and hydrated on the client.
|
||||
|
|
@ -186,7 +186,7 @@ Behind the scenes, React handles rendering as follows:
|
|||
- On the client, React renders Client Components and _slots in_ the rendered result of Server Components, merging the work done on the server and client.
|
||||
- If any Server Components are nested inside a Client Component, their rendered content will be placed correctly within the Client Component.
|
||||
|
||||
> **Good to know:** In Next.js, during the initial page load, both the rendered result of Server Components from the above step and Client Components are [pre-rendered on the server as HTML](/docs/app/building-your-application/rendering#static-and-dynamic-rendering-on-the-server) to produce a faster initial page load.
|
||||
> **Good to know**: In Next.js, during the initial page load, both the rendered result of Server Components from the above step and Client Components are [pre-rendered on the server as HTML](/docs/app/building-your-application/rendering#static-and-dynamic-rendering-on-the-server) to produce a faster initial page load.
|
||||
|
||||
### Nesting Server Components inside Client Components
|
||||
|
||||
|
|
@ -731,7 +731,7 @@ export default function RootLayout({ children }) {
|
|||
|
||||
With the provider rendered at the root, all other Client Components throughout your app will be able to consume this context.
|
||||
|
||||
> Note: You should render providers as deep as possible in the tree – notice how `ThemeProvider` only wraps `{children}` instead of the entire `<html>` document. This makes it easier for Next.js to optimize the static parts of your Server Components.
|
||||
> **Good to know**: You should render providers as deep as possible in the tree – notice how `ThemeProvider` only wraps `{children}` instead of the entire `<html>` document. This makes it easier for Next.js to optimize the static parts of your Server Components.
|
||||
|
||||
### Rendering third-party context providers in Server Components
|
||||
|
||||
|
|
|
|||
|
|
@ -37,7 +37,7 @@ A special [`page.js` file](/docs/app/building-your-application/routing/pages-and
|
|||
|
||||
In this example, the `/dashboard/analytics` URL path is _not_ publicly accessible because it does not have a corresponding `page.js` file. This folder could be used to store components, stylesheets, images, or other colocated files.
|
||||
|
||||
> **Good to know:** `.js`, `.jsx`, or `.tsx` file extensions can be used for special files.
|
||||
> **Good to know**: `.js`, `.jsx`, or `.tsx` file extensions can be used for special files.
|
||||
|
||||
## Creating UI
|
||||
|
||||
|
|
|
|||
|
|
@ -49,7 +49,7 @@ export default function Page() {
|
|||
}
|
||||
```
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - A page is always the [leaf](/docs/app/building-your-application/routing#terminology) of the [route subtree](/docs/app/building-your-application/routing#terminology).
|
||||
> - `.js`, `.jsx`, or `.tsx` file extensions can be used for Pages.
|
||||
|
|
@ -103,7 +103,7 @@ export default function DashboardLayout({
|
|||
}
|
||||
```
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - The top-most layout is called the [Root Layout](#root-layout-required). This **required** layout is shared across all pages in an application. Root layouts must contain `html` and `body` tags.
|
||||
> - Any route segment can optionally define its own [Layout](#nesting-layouts). These layouts will be shared across all pages in that segment.
|
||||
|
|
@ -144,7 +144,7 @@ export default function RootLayout({ children }) {
|
|||
}
|
||||
```
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - The `app` directory **must** include a root layout.
|
||||
> - The root layout must define `<html>` and `<body>` tags since Next.js does not automatically create them.
|
||||
|
|
@ -267,6 +267,6 @@ 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, 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.
|
||||
|
||||
[Learn more about available metadata options in the API reference.](/docs/app/api-reference/functions/generate-metadata)
|
||||
|
|
|
|||
|
|
@ -140,7 +140,7 @@ The `useRouter` provides methods such as `push()`, `refresh()`, and more. See th
|
|||
|
||||
### Client-side Caching of Rendered Server Components
|
||||
|
||||
> **Good to know:** This client-side cache is different from the server-side [Next.js HTTP cache](/docs/app/building-your-application/data-fetching#caching-data).
|
||||
> **Good to know**: This client-side cache is different from the server-side [Next.js HTTP cache](/docs/app/building-your-application/data-fetching#caching-data).
|
||||
|
||||
The new router has an **in-memory client-side cache** that stores the **rendered result** of Server Components (payload). The cache is split by route segments which allows invalidation at any level and ensures consistency across concurrent renders.
|
||||
|
||||
|
|
@ -163,7 +163,7 @@ By default, routes are prefetched as they become visible in the viewport when us
|
|||
- If the route is static, all the Server Component payloads for the route segments will be prefetched.
|
||||
- If the route is dynamic, the payload from the first shared layout down until the first `loading.js` file is prefetched. This reduces the cost of prefetching the whole route dynamically and allows [instant loading states](/docs/app/building-your-application/routing/loading-ui-and-streaming#instant-loading-states) for dynamic routes.
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - Prefetching is only enabled in production.
|
||||
> - Prefetching can be disabled by passing `prefetch={false}` to `<Link>`.
|
||||
|
|
|
|||
|
|
@ -70,7 +70,7 @@ In the example above, both `(marketing)` and `(shop)` have their own root layout
|
|||
|
||||
---
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - The naming of route groups has no special significance other than for organization. They do not affect the URL path.
|
||||
> - Routes that include a route group **should not** resolve to the same URL path as other routes. For example, since route groups don't affect URL structure, `(marketing)/about/page.js` and `(shop)/about/page.js` would both resolve to `/about` and cause an error.
|
||||
|
|
|
|||
|
|
@ -41,7 +41,7 @@ export default function Page({ params }) {
|
|||
|
||||
See the [generateStaticParams()](#generating-static-params) page to learn how to generate the params for the segment.
|
||||
|
||||
> **Note:** Dynamic Segments are equivalent to [Dynamic Routes](/docs/app/building-your-application/routing/dynamic-routes) in the `pages` directory.
|
||||
> **Good to know**: Dynamic Segments are equivalent to [Dynamic Routes](/docs/app/building-your-application/routing/dynamic-routes) in the `pages` directory.
|
||||
|
||||
## Generating Static Params
|
||||
|
||||
|
|
@ -122,4 +122,4 @@ export default function Page({ params }) {
|
|||
| `app/shop/[...slug]/page.js` | `{ slug: string[] }` |
|
||||
| `app/[categoryId]/[itemId]/page.js` | `{ categoryId: string, itemId: string }` |
|
||||
|
||||
> **Note**: This may be done automatically by the [TypeScript plugin](/docs/app/building-your-application/configuring/typescript#typescript-plugin) in the future.
|
||||
> **Good to know**: This may be done automatically by the [TypeScript plugin](/docs/app/building-your-application/configuring/typescript#typescript-plugin) in the future.
|
||||
|
|
|
|||
|
|
@ -51,7 +51,7 @@ In the same folder, `loading.js` will be nested inside `layout.js`. It will auto
|
|||
height="768"
|
||||
/>
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - Navigation is immediate, even with [server-centric routing](/docs/app/building-your-application/routing#server-centric-routing-with-client-side-navigation).
|
||||
> - Navigation is interruptible, meaning changing routes does not need to wait for the content of the route to fully load before navigating to another route.
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ Route Handlers allow you to create custom request handlers for a given route usi
|
|||
height="444"
|
||||
/>
|
||||
|
||||
> **Good to know:** Route Handlers are only available inside the `app` directory. They are the equivalent of [API Routes](/docs/pages/building-your-application/routing/api-routes) inside the `pages` directory meaning you **do not** need to use API Routes and Route Handlers together.
|
||||
> **Good to know**: Route Handlers are only available inside the `app` directory. They are the equivalent of [API Routes](/docs/pages/building-your-application/routing/api-routes) inside the `pages` directory meaning you **do not** need to use API Routes and Route Handlers together.
|
||||
|
||||
## Convention
|
||||
|
||||
|
|
@ -170,7 +170,7 @@ export async function POST() {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note:** Previously, API Routes could have been used for use cases like handling form submissions. Route Handlers are likely not the solution for these uses cases. We will be recommending the use of [mutations](/docs/app/building-your-application/data-fetching/server-actions) for this when ready.
|
||||
> **Good to know**: Previously, API Routes could have been used for use cases like handling form submissions. Route Handlers are likely not the solution for these uses cases. We will be recommending the use of [mutations](/docs/app/building-your-application/data-fetching/server-actions) for this when ready.
|
||||
|
||||
### Route Resolution
|
||||
|
||||
|
|
|
|||
|
|
@ -81,7 +81,7 @@ export const config = {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note**: The `matcher` values need to be constants so they can be statically analyzed at build-time. Dynamic values such as variables will be ignored.
|
||||
> **Good to know**: The `matcher` values need to be constants so they can be statically analyzed at build-time. Dynamic values such as variables will be ignored.
|
||||
|
||||
Configured matchers:
|
||||
|
||||
|
|
@ -92,7 +92,7 @@ Configured matchers:
|
|||
|
||||
Read more details on [path-to-regexp](https://github.com/pillarjs/path-to-regexp#path-to-regexp-1) documentation.
|
||||
|
||||
> **Note**: For backward compatibility, Next.js always considers `/public` as `/public/index`. Therefore, a matcher of `/public/:path` will match.
|
||||
> **Good to know**: For backward compatibility, Next.js always considers `/public` as `/public/index`. Therefore, a matcher of `/public/:path` will match.
|
||||
|
||||
### Conditional Statements
|
||||
|
||||
|
|
@ -214,7 +214,7 @@ export function middleware(request) {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note**: Avoid setting large headers as it might cause [431 Request Header Fields Too Large](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/431) error depending on your backend web server configuration.
|
||||
> **Good to know**: Avoid setting large headers as it might cause [431 Request Header Fields Too Large](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/431) error depending on your backend web server configuration.
|
||||
|
||||
## Producing a Response
|
||||
|
||||
|
|
|
|||
|
|
@ -141,7 +141,7 @@ There is no "right" or "wrong" way when it comes to organizing your own files an
|
|||
|
||||
The following section lists a very high-level overview of common strategies. The simplest takeaway is to choose a strategy that works for you and your team and be consistent across the project.
|
||||
|
||||
> **Note:** In our examples below, we're using `components` and `lib` folders as generalized placeholders, their naming has no special framework significance and your projects might use other folders like `ui`, `utils`, `hooks`, `styles`, etc.
|
||||
> **Good to know**: In our examples below, we're using `components` and `lib` folders as generalized placeholders, their naming has no special framework significance and your projects might use other folders like `ui`, `utils`, `hooks`, `styles`, etc.
|
||||
|
||||
### Store project files outside of `app`
|
||||
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@ In version 13, Next.js introduced a new **App Router** built on [React Server Co
|
|||
|
||||
The App Router works in a new directory named `app`. The `app` directory works alongside the `pages` directory to allow for incremental adoption. This allows you to opt some routes of your application into the new behavior while keeping other routes in the `pages` directory for previous behavior. If your application uses the `pages` directory, please also see the [Pages Router](/docs/pages/building-your-application/routing) documentation.
|
||||
|
||||
> **Good to know:** The App Router takes priority over the Pages Router. Routes across directories should not resolve to the same URL path and will cause a build-time error to prevent a conflict.
|
||||
> **Good to know**: The App Router takes priority over the Pages Router. Routes across directories should not resolve to the same URL path and will cause a build-time error to prevent a conflict.
|
||||
|
||||
<Image
|
||||
alt="Next.js App Directory"
|
||||
|
|
@ -99,7 +99,7 @@ Next.js provides a set of special files to create UI with specific behavior in n
|
|||
| [`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) |
|
||||
|
||||
> **Good to know:** `.js`, `.jsx`, or `.tsx` file extensions can be used for special files.
|
||||
> **Good to know**: `.js`, `.jsx`, or `.tsx` file extensions can be used for special files.
|
||||
|
||||
## Component Hierarchy
|
||||
|
||||
|
|
|
|||
|
|
@ -36,7 +36,7 @@ This table summarizes how [dynamic functions](#dynamic-functions) and [caching](
|
|||
|
||||
Note how dynamic functions always opt the route into dynamic rendering, regardless of whether the data fetching is cached or not. In other words, static rendering is dependent not only on the data fetching behavior, but also on the dynamic functions used in the route.
|
||||
|
||||
> **Note:** In the future, Next.js will introduce hybrid server-side rendering where layouts and pages in a route can be independently statically or dynamically rendered, instead of the whole route.
|
||||
> **Good to know**: In the future, Next.js will introduce hybrid server-side rendering where layouts and pages in a route can be independently statically or dynamically rendered, instead of the whole route.
|
||||
|
||||
### Dynamic Functions
|
||||
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ There are two environments where your application code can be rendered: the clie
|
|||
- The **client** refers to the browser on a user's device that sends a request to a server for your application code. It then turns the response from the server into an interface the user can interact with.
|
||||
- The **server** refers to the computer in a data center that stores your application code, receives requests from a client, does some computation, and sends back an appropriate response.
|
||||
|
||||
> **Note:** Server can refer to computers in regions where your application is deployed to, the [Edge Network](https://vercel.com/docs/concepts/edge-network/overview) where your application code is distributed, or [Content Delivery Networks (CDNs)](https://developer.mozilla.org/en-US/docs/Glossary/CDN) where the result of the rendering work can be cached.
|
||||
> **Good to know**: Server can refer to computers in regions where your application is deployed to, the [Edge Network](https://vercel.com/docs/concepts/edge-network/overview) where your application code is distributed, or [Content Delivery Networks (CDNs)](https://developer.mozilla.org/en-US/docs/Glossary/CDN) where the result of the rendering work can be cached.
|
||||
|
||||
## Component-level Client and Server Rendering
|
||||
|
||||
|
|
@ -42,7 +42,7 @@ In addition to client-side and server-side rendering with React components, Next
|
|||
|
||||
With **Static Rendering**, both Server _and_ Client Components can be prerendered on the server at **build time**. The result of the work is [cached](/docs/app/building-your-application/data-fetching/caching) and reused on subsequent requests. The cached result can also be [revalidated](/docs/app/building-your-application/data-fetching#revalidating-data).
|
||||
|
||||
> **Note:** This is equivalent to [Static Site Generation (SSG)](/docs/pages/building-your-application/rendering/static-site-generation) and [Incremental Static Regeneration (ISR)](/docs/pages/building-your-application/rendering/incremental-static-regeneration) in the [Pages Router](/docs/pages/building-your-application/rendering).
|
||||
> **Good to know**: This is equivalent to [Static Site Generation (SSG)](/docs/pages/building-your-application/rendering/static-site-generation) and [Incremental Static Regeneration (ISR)](/docs/pages/building-your-application/rendering/incremental-static-regeneration) in the [Pages Router](/docs/pages/building-your-application/rendering).
|
||||
|
||||
Server and Client Components are rendered differently during Static Rendering:
|
||||
|
||||
|
|
@ -53,7 +53,7 @@ Server and Client Components are rendered differently during Static Rendering:
|
|||
|
||||
With Dynamic Rendering, both Server _and_ Client Components are rendered on the server at **request time**. The result of the work is not cached.
|
||||
|
||||
> **Note:** This is equivalent to [Server-Side Rendering (`getServerSideProps()`)](/docs/pages/building-your-application/rendering/server-side-rendering) in the [Pages Router](/docs/pages/building-your-application/rendering).
|
||||
> **Good to know**: This is equivalent to [Server-Side Rendering (`getServerSideProps()`)](/docs/pages/building-your-application/rendering/server-side-rendering) in the [Pages Router](/docs/pages/building-your-application/rendering).
|
||||
|
||||
To learn more about static and dynamic behavior, see the [Static and Dynamic Rendering](/docs/app/building-your-application/rendering/static-and-dynamic-rendering) page. To learn more about caching, see the [Caching](/docs/app/building-your-application/data-fetching/caching) sections.
|
||||
|
||||
|
|
|
|||
|
|
@ -58,7 +58,7 @@ export default async function Page() {
|
|||
}
|
||||
```
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> To use an `async` Server Component with TypeScript, ensure you are using TypeScript `5.1.3` or higher and `@types/react` `18.2.8` or higher.
|
||||
|
||||
|
|
@ -75,7 +75,7 @@ Next.js provides helpful server functions you may need when fetching data in Ser
|
|||
|
||||
Wrapping `fetch` in `use` is currently **not** recommended in Client Components and may trigger multiple re-renders. For now, if you need to fetch data in a Client Component, we recommend using a third-party library such as [SWR](https://swr.vercel.app/) or [React Query](https://tanstack.com/query/v4).
|
||||
|
||||
> **Note:** We'll be adding more examples once `fetch` and `use` work in Client Components.
|
||||
> **Good to know**: We'll be adding more examples once `fetch` and `use` work in Client Components.
|
||||
|
||||
## Static Data Fetching
|
||||
|
||||
|
|
@ -95,7 +95,7 @@ fetch('https://...', { next: { revalidate: 10 } })
|
|||
|
||||
See [Revalidating Data](/docs/app/building-your-application/data-fetching/revalidating) for more information.
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> Caching at the fetch level with `revalidate` or `cache: 'force-cache'` stores the data across requests in a shared cache. You should avoid using it for user-specific data (i.e. requests that derive data from `cookies()` or `headers()`)
|
||||
|
||||
|
|
@ -362,7 +362,7 @@ Any data fetching libraries that do not use `fetch` directly **will not** affect
|
|||
|
||||
If the segment is static (default), the output of the request will be cached and revalidated (if configured) alongside the rest of the segment. If the segment is dynamic, the output of the request will _not_ be cached and will be re-fetched on every request when the segment is rendered.
|
||||
|
||||
> **Good to know:** Dynamic functions like [`cookies()`](/docs/app/api-reference/functions/cookies) and [`headers()`](/docs/app/api-reference/functions/headers) will make the route segment dynamic.
|
||||
> **Good to know**: Dynamic functions like [`cookies()`](/docs/app/api-reference/functions/cookies) and [`headers()`](/docs/app/api-reference/functions/headers) will make the route segment dynamic.
|
||||
|
||||
### Segment Cache Configuration
|
||||
|
||||
|
|
|
|||
|
|
@ -136,7 +136,7 @@ export default async function Page({ params: { id } }) {
|
|||
|
||||
Although the `getUser()` function is called twice in the example above, only one query will be made to the database. This is because `getUser()` is wrapped in `cache()`, so the second request can reuse the result from the first request.
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - `fetch()` caches requests automatically, so you don't need to wrap functions that use `fetch()` with `cache()`. See [automatic request deduping](/docs/app/building-your-application/data-fetching#automatic-fetch-request-deduping) for more information.
|
||||
> - In this new model, we recommend **fetching data directly in the component that needs it**, even if you're requesting the same data in multiple components, rather than passing the data between components as props.
|
||||
|
|
@ -264,7 +264,7 @@ The `getUser.ts` exports can be used by layouts, pages, or components to give th
|
|||
|
||||
## Segment-level Caching
|
||||
|
||||
> **Note:** We recommend using per-request caching for improved granularity and control over caching.
|
||||
> **Good to know**: We recommend using per-request caching for improved granularity and control over caching.
|
||||
|
||||
Segment-level caching allows you to cache and revalidate data used in route segments.
|
||||
|
||||
|
|
@ -278,7 +278,7 @@ export const revalidate = 60 // revalidate this segment every 60 seconds
|
|||
export const revalidate = 60 // revalidate this segment every 60 seconds
|
||||
```
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - If a page, layout, and fetch request inside components all specify a [`revalidate`](/docs/app/api-reference/file-conventions/route-segment-config#revalidate) frequency, the lowest value of the three will be used.
|
||||
> - Advanced: You can set `fetchCache` to `'only-cache'` or `'force-cache'` to ensure that all `fetch` requests opt into caching but the revalidation frequency might still be lowered by individual `fetch` requests. See [`fetchCache`](/docs/app/api-reference/file-conventions/route-segment-config) for more information.
|
||||
|
|
|
|||
|
|
@ -41,7 +41,7 @@ In addition to `fetch`, you can also revalidate data using [`cache`](/docs/app/b
|
|||
|
||||
When a request is made to a route segment that hasn’t been generated, Next.js will dynamically render the route on the first request. Future requests will serve the static route segments from the cache.
|
||||
|
||||
> **Note**: Check if your upstream data provider has caching enabled by default. You might need to disable (e.g. `useCdn: false`), otherwise a revalidation won't be able to pull fresh data to update the ISR cache. Caching can occur at a CDN (for an endpoint being requested) when it returns the `Cache-Control` header. ISR on Vercel [persists the cache globally and handles rollbacks](https://vercel.com/docs/concepts/incremental-static-regeneration/overview).
|
||||
> **Good to know**: Check if your upstream data provider has caching enabled by default. You might need to disable (e.g. `useCdn: false`), otherwise a revalidation won't be able to pull fresh data to update the ISR cache. Caching can occur at a CDN (for an endpoint being requested) when it returns the `Cache-Control` header. ISR on Vercel [persists the cache globally and handles rollbacks](https://vercel.com/docs/concepts/incremental-static-regeneration/overview).
|
||||
|
||||
## On-demand Revalidation
|
||||
|
||||
|
|
|
|||
|
|
@ -123,7 +123,7 @@ export default function ClientComponent() {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note:** When using a top-level `"use server"` directive, all exports below will be considered Server Actions. You can have multiple Server Actions in a single file.
|
||||
> **Good to know**: When using a top-level `"use server"` directive, all exports below will be considered Server Actions. You can have multiple Server Actions in a single file.
|
||||
|
||||
### Invocation
|
||||
|
||||
|
|
@ -154,7 +154,7 @@ export default function AddToCart({ productId }) {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note:** An `action` is similar to the HTML primitive [`action`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form#action)
|
||||
> **Good to know**: An `action` is similar to the HTML primitive [`action`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form#action)
|
||||
|
||||
#### `formAction`
|
||||
|
||||
|
|
@ -182,13 +182,13 @@ export default function Form() {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note:** A `formAction` is the HTML primitive [`formaction`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#formaction). React now allows you to pass functions to this attribute.
|
||||
> **Good to know**: A `formAction` is the HTML primitive [`formaction`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#formaction). React now allows you to pass functions to this attribute.
|
||||
|
||||
#### Custom invocation using `startTransition`
|
||||
|
||||
You can also invoke Server Actions without using `action` or `formAction`. You can achieve this by using `startTransition` provided by the `useTransition` hook, which can be useful if you want to use Server Actions outside of forms, buttons, or inputs.
|
||||
|
||||
> **Note:** Using `startTransition` disables the out-of-the-box Progressive Enhancement.
|
||||
> **Good to know**: Using `startTransition` disables the out-of-the-box Progressive Enhancement.
|
||||
|
||||
```jsx filename="app/components/example-client-component.js" highlight={3, 7, 10}
|
||||
'use client'
|
||||
|
|
|
|||
|
|
@ -32,13 +32,13 @@ Whenever possible, we recommend fetching data in [Server Components](/docs/getti
|
|||
- Reduce client-server [waterfalls](#parallel-and-sequential-data-fetching).
|
||||
- Depending on your region, data fetching can also happen closer to your data source, reducing latency and improving performance.
|
||||
|
||||
> **Good to know:** It's still possible to fetch data client-side. We recommend using a third-party library such as [SWR](https://swr.vercel.app/) or [React Query](https://tanstack.com/query/v4/) with Client Components. In the future, it'll also be possible to fetch data in Client Components using React's [`use()` hook](/docs/app/building-your-application/data-fetching/fetching#use-in-client-components).
|
||||
> **Good to know**: It's still possible to fetch data client-side. We recommend using a third-party library such as [SWR](https://swr.vercel.app/) or [React Query](https://tanstack.com/query/v4/) with Client Components. In the future, it'll also be possible to fetch data in Client Components using React's [`use()` hook](/docs/app/building-your-application/data-fetching/fetching#use-in-client-components).
|
||||
|
||||
## Fetching Data at the Component Level
|
||||
|
||||
In the App Router, you can fetch data inside [layouts](/docs/app/building-your-application/routing/pages-and-layouts#layouts), [pages](/docs/app/building-your-application/routing/pages-and-layouts#pages), and components. Data fetching is also compatible with [Streaming and Suspense](#streaming-and-suspense).
|
||||
|
||||
> **Good to know:** For layouts, it's not possible to pass data between a parent layout and its `children` components. We recommend **fetching data directly inside the layout that needs it**, even if you're requesting the same data multiple times in a route. Behind the scenes, React and Next.js will [cache and dedupe](#automatic-fetch-request-deduping) requests to avoid the same data being fetched more than once.
|
||||
> **Good to know**: For layouts, it's not possible to pass data between a parent layout and its `children` components. We recommend **fetching data directly inside the layout that needs it**, even if you're requesting the same data multiple times in a route. Behind the scenes, React and Next.js will [cache and dedupe](#automatic-fetch-request-deduping) requests to avoid the same data being fetched more than once.
|
||||
|
||||
## Parallel and Sequential Data Fetching
|
||||
|
||||
|
|
@ -74,7 +74,7 @@ If you need to fetch the same data (e.g. current user) in multiple components in
|
|||
- This optimization also applies during [static generation](/docs/app/building-your-application/rendering#static-rendering).
|
||||
- On the client, the cache lasts the duration of a session (which could include multiple client-side re-renders) before a full page reload.
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - `POST` requests are not automatically deduplicated. [Learn more about caching](/docs/app/building-your-application/data-fetching/caching).
|
||||
> - If you're unable to use `fetch`, React provides a [`cache` function](/docs/app/building-your-application/data-fetching/caching#react-cache) to allow you to manually cache data for the duration of the request.
|
||||
|
|
@ -123,7 +123,7 @@ Next.js extends the [options object](https://developer.mozilla.org/en-US/docs/We
|
|||
|
||||
During server rendering, when Next.js comes across a fetch, it will check the cache to see if the data is already available. If it is, it will return the cached data. If not, it will fetch and store data for future requests.
|
||||
|
||||
> **Good to know:** If you're unable to use `fetch`, React provides a [`cache` function](/docs/app/building-your-application/data-fetching/caching#react-cache) to allow you to manually cache data for the duration of the request.
|
||||
> **Good to know**: If you're unable to use `fetch`, React provides a [`cache` function](/docs/app/building-your-application/data-fetching/caching#react-cache) to allow you to manually cache data for the duration of the request.
|
||||
|
||||
[Learn more about caching in Next.js](/docs/app/building-your-application/data-fetching/caching).
|
||||
|
||||
|
|
|
|||
|
|
@ -106,7 +106,7 @@ These `.css` files represent hot execution paths in your application, ensuring t
|
|||
<AppOnly>
|
||||
Global styles can be imported into any layout, page, or component inside the `app` directory.
|
||||
|
||||
> **Good to know:** This is different from the `pages` directory, where you can only import global styles inside the `_app.js` file.
|
||||
> **Good to know**: This is different from the `pages` directory, where you can only import global styles inside the `_app.js` file.
|
||||
|
||||
For example, consider a stylesheet named `app/global.css`:
|
||||
|
||||
|
|
@ -223,7 +223,7 @@ export default function RootLayout({ children }) {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note:** External stylesheets must be directly imported from an npm package or downloaded and colocated with your codebase. You cannot use `<link rel="stylesheet" />`.
|
||||
> **Good to know**: External stylesheets must be directly imported from an npm package or downloaded and colocated with your codebase. You cannot use `<link rel="stylesheet" />`.
|
||||
|
||||
</AppOnly>
|
||||
|
||||
|
|
|
|||
|
|
@ -23,7 +23,7 @@ The following are currently working on support:
|
|||
- [Material UI](https://github.com/mui/material-ui/issues/34905#issuecomment-1401306594)
|
||||
- [Chakra UI](https://github.com/chakra-ui/chakra-ui/issues/7180)
|
||||
|
||||
> **Note:** We're testing out different CSS-in-JS libraries and we'll be adding more examples for libraries that support React 18 features and/or the `app` directory.
|
||||
> **Good to know**: We're testing out different CSS-in-JS libraries and we'll be adding more examples for libraries that support React 18 features and/or the `app` directory.
|
||||
|
||||
If you want to style Server Components, we recommend using [CSS Modules](/docs/app/building-your-application/styling/css-modules) or other solutions that output CSS files, like PostCSS or [Tailwind CSS](/docs/app/building-your-application/styling/tailwind-css).
|
||||
|
||||
|
|
@ -225,7 +225,7 @@ export default function RootLayout({ children }) {
|
|||
|
||||
[View an example here](https://github.com/vercel/app-playground/tree/main/app/styling/styled-components).
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - During server rendering, styles will be extracted to a global registry and flushed to the `<head>` of your HTML. This ensures the style rules are placed before any content that might use them. In the future, we may use an upcoming React feature to determine where to inject the styles.
|
||||
> - During streaming, styles from each chunk will be collected and appended to existing styles. After client-side hydration is complete, `styled-components` will take over as usual and inject any further dynamic styles.
|
||||
|
|
|
|||
|
|
@ -103,7 +103,7 @@ export default function Page({ params, searchParams }) {}
|
|||
|
||||
For all the available params, see the [API Reference](/docs/app/api-reference/functions/generate-metadata).
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - Both static and dynamic metadata through `generateMetadata` are **only supported in Server Components**.
|
||||
> - When rendering a route, Next.js will [automatically deduplicate `fetch` requests](/docs/app/building-your-application/data-fetching#automatic-fetch-request-deduping) for the same data across `generateMetadata`, `generateStaticParams`, Layouts, Pages, and Server Components. React [`cache` can be used](/docs/app/building-your-application/data-fetching/caching#react-cache) if `fetch` is unavailable.
|
||||
|
|
@ -138,7 +138,7 @@ There are two default `meta` tags that are always added even if a route doesn't
|
|||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
```
|
||||
|
||||
> **Note**: You can overwrite the default [`viewport`](/docs/app/api-reference/functions/generate-metadata#viewport) meta tag.
|
||||
> **Good to know**: You can overwrite the default [`viewport`](/docs/app/api-reference/functions/generate-metadata#viewport) meta tag.
|
||||
|
||||
### Ordering
|
||||
|
||||
|
|
@ -285,7 +285,7 @@ export async function GET() {
|
|||
|
||||
`ImageResponse` supports common CSS properties including flexbox and absolute positioning, custom fonts, text wrapping, centering, and nested images. [See the full list of supported CSS properties](/docs/app/api-reference/functions/image-response).
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - Examples are available in the [Vercel OG Playground](https://og-playground.vercel.app/).
|
||||
> - `ImageResponse` uses [@vercel/og](https://vercel.com/docs/concepts/functions/edge-functions/og-image-generation), [Satori](https://github.com/vercel/satori), and Resvg to convert HTML and CSS into PNG.
|
||||
|
|
|
|||
|
|
@ -176,7 +176,7 @@ export default function Home() {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note**: In `import('path/to/component')`, the path must be explicitly written. It can't be a template string nor a variable. Furthermore the `import()` has to be inside the `dynamic()` call for Next.js to be able to match webpack bundles / module ids to the specific `dynamic()` call and preload them before rendering. `dynamic()` can't be used inside of React rendering as it needs to be marked in the top level of the module for preloading to work, similar to `React.lazy`.
|
||||
> **Good to know**: In `import('path/to/component')`, the path must be explicitly written. It can't be a template string nor a variable. Furthermore the `import()` has to be inside the `dynamic()` call for Next.js to be able to match webpack bundles / module ids to the specific `dynamic()` call and preload them before rendering. `dynamic()` can't be used inside of React rendering as it needs to be marked in the top level of the module for preloading to work, similar to `React.lazy`.
|
||||
|
||||
## With named exports
|
||||
|
||||
|
|
|
|||
|
|
@ -165,7 +165,7 @@ export function reportWebVitals(metric) {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note**: If you use [Google Analytics](https://analytics.google.com/analytics/web/), using the
|
||||
> **Good to know**: If you use [Google Analytics](https://analytics.google.com/analytics/web/), using the
|
||||
> `id` value can allow you to construct metric distributions manually (to calculate percentiles,
|
||||
> etc.)
|
||||
>
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ title: OpenTelemetry
|
|||
description: Learn how to instrument your Next.js app with OpenTelemetry.
|
||||
---
|
||||
|
||||
> **Note**: This feature is **experimental**, you need to explicitly opt-in by providing `experimental.instrumentationHook = true;` in your `next.config.js`.
|
||||
> **Good to know**: This feature is **experimental**, you need to explicitly opt-in by providing `experimental.instrumentationHook = true;` in your `next.config.js`.
|
||||
|
||||
Observability is crucial for understanding and optimizing the behavior and performance of your Next.js app.
|
||||
|
||||
|
|
@ -18,7 +18,7 @@ This documentation uses terms like _Span_, _Trace_ or _Exporter_ throughout this
|
|||
Next.js supports OpenTelemetry instrumentation out of the box, which means that we already instrumented Next.js itself.
|
||||
When you enable OpenTelemetry we will automatically wrap all your code like `getStaticProps` in _spans_ with helpful attributes.
|
||||
|
||||
> **Note**: We currently support OpenTelemetry bindings only in serverless functions.
|
||||
> **Good to know**: We currently support OpenTelemetry bindings only in serverless functions.
|
||||
> We don't provide any for `edge` or client side code.
|
||||
|
||||
## Getting Started
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ title: Instrumentation
|
|||
description: Learn how to use instrumentation to run code at server startup in your Next.js app
|
||||
---
|
||||
|
||||
> **Note**: This feature is **experimental**. To use it, you must explicitly opt in by defining `experimental.instrumentationHook = true;` in your `next.config.js`.
|
||||
> **Good to know**: This feature is **experimental**. To use it, you must explicitly opt in by defining `experimental.instrumentationHook = true;` in your `next.config.js`.
|
||||
|
||||
If you export a function named `register` from a `instrumentation.ts` (or `.js`) file in the **root directory** of your project, we will call that function whenever a new Next.js server instance is bootstrapped.
|
||||
|
||||
|
|
|
|||
|
|
@ -67,7 +67,7 @@ The TypeScript plugin can help with:
|
|||
- Ensuring the `use client` directive is used correctly.
|
||||
- Ensuring client hooks (like `useState`) are only used in Client Components.
|
||||
|
||||
> **Note:** More features will be added in the future.
|
||||
> **Good to know**: More features will be added in the future.
|
||||
|
||||
</AppOnly>
|
||||
|
||||
|
|
|
|||
|
|
@ -63,7 +63,7 @@ TWITTER_URL=https://twitter.com/$TWITTER_USER
|
|||
|
||||
In the above example, `process.env.TWITTER_URL` would be set to `http://twitter.com/vercel`.
|
||||
|
||||
> **Note**: If you need to use variable with a `$` in the actual value, it needs to be escaped e.g. `\$`.
|
||||
> **Good to know**: If you need to use variable with a `$` in the actual value, it needs to be escaped e.g. `\$`.
|
||||
|
||||
## Exposing Environment Variables to the Browser
|
||||
|
||||
|
|
@ -111,7 +111,7 @@ Next.js allows you to set defaults in `.env` (all environments), `.env.developme
|
|||
|
||||
`.env.local` always overrides the defaults set.
|
||||
|
||||
> **Note**: `.env`, `.env.development`, and `.env.production` files should be included in your repository as they define defaults. **`.env*.local` should be added to `.gitignore`**, as those files are intended to be ignored. `.env.local` is where secrets can be stored.
|
||||
> **Good to know**: `.env`, `.env.development`, and `.env.production` files should be included in your repository as they define defaults. **`.env*.local` should be added to `.gitignore`**, as those files are intended to be ignored. `.env.local` is where secrets can be stored.
|
||||
|
||||
## Environment Variables on Vercel
|
||||
|
||||
|
|
@ -133,7 +133,7 @@ This one is useful when running tests with tools like `jest` or `cypress` where
|
|||
|
||||
There is a small difference between `test` environment, and both `development` and `production` that you need to bear in mind: `.env.local` won't be loaded, as you expect tests to produce the same results for everyone. This way every test execution will use the same env defaults across different executions by ignoring your `.env.local` (which is intended to override the default set).
|
||||
|
||||
> **Note**: similar to Default Environment Variables, `.env.test` file should be included in your repository, but `.env.test.local` shouldn't, as `.env*.local` are intended to be ignored through `.gitignore`.
|
||||
> **Good to know**: similar to Default Environment Variables, `.env.test` file should be included in your repository, but `.env.test.local` shouldn't, as `.env*.local` are intended to be ignored through `.gitignore`.
|
||||
|
||||
While running unit tests you can make sure to load your environment variables the same way Next.js does by leveraging the `loadEnvConfig` function from the `@next/env` package.
|
||||
|
||||
|
|
@ -159,7 +159,7 @@ Environment variables are looked up in the following places, in order, stopping
|
|||
|
||||
For example, if `NODE_ENV` is `development` and you define a variable in both `.env.development.local` and `.env`, the value in `.env.development.local` will be used.
|
||||
|
||||
> **Note**: The allowed values for `NODE_ENV` are `production`, `development` and `test`.
|
||||
> **Good to know**: The allowed values for `NODE_ENV` are `production`, `development` and `test`.
|
||||
|
||||
## Good to know
|
||||
|
||||
|
|
|
|||
|
|
@ -186,7 +186,7 @@ If your Markdown or MDX files do _not_ live inside your application, you can fet
|
|||
|
||||
There are two popular community packages for fetching MDX content: [`next-mdx-remote`](https://github.com/hashicorp/next-mdx-remote#react-server-components-rsc--nextjs-app-directory-support) and [`contentlayer`](https://www.contentlayer.dev/). For example, the following example uses `next-mdx-remote`:
|
||||
|
||||
> **Note:** Please proceed with caution. MDX compiles to JavaScript and is executed on the server. You should only fetch MDX content from a trusted source, otherwise this can lead to remote code execution (RCE).
|
||||
> **Good to know**: Please proceed with caution. MDX compiles to JavaScript and is executed on the server. You should only fetch MDX content from a trusted source, otherwise this can lead to remote code execution (RCE).
|
||||
|
||||
```tsx filename="app/page.tsx" switcher
|
||||
import { MDXRemote } from 'next-mdx-remote/rsc'
|
||||
|
|
|
|||
|
|
@ -241,4 +241,4 @@ A new bypass cookie value will be generated each time you run `next build`.
|
|||
|
||||
This ensures that the bypass cookie can’t be guessed.
|
||||
|
||||
> **Note**: To test Draft Mode locally over HTTP, your browser will need to allow third-party cookies and local storage access.
|
||||
> **Good to know**: To test Draft Mode locally over HTTP, your browser will need to allow third-party cookies and local storage access.
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ Since Next.js supports this static export, it can be deployed and hosted on any
|
|||
|
||||
<PagesOnly>
|
||||
|
||||
> **Note:** We recommend using the App Router for enhanced static export support.
|
||||
> **Good to know**: We recommend using the App Router for enhanced static export support.
|
||||
|
||||
</PagesOnly>
|
||||
|
||||
|
|
|
|||
|
|
@ -102,7 +102,7 @@ The following services support Next.js `v12+`. Below, you’ll find examples or
|
|||
- [Railway](https://docs.railway.app/getting-started)
|
||||
- [Render](https://render.com/docs/deploy-nextjs-app)
|
||||
|
||||
> **Note**: There are also managed platforms that allow you to use a Dockerfile as shown in the [example above](#docker-image).
|
||||
> **Good to know**: There are also managed platforms that allow you to use a Dockerfile as shown in the [example above](#docker-image).
|
||||
|
||||
### Static Only
|
||||
|
||||
|
|
@ -122,7 +122,7 @@ You can also manually deploy the output from [`output: 'export'`](/docs/app/buil
|
|||
- [Terraform](https://github.com/milliHQ/terraform-aws-next-js)
|
||||
- [SST](https://docs.sst.dev/start/nextjs)
|
||||
|
||||
> **Note**: Not all serverless providers implement the [Next.js Build API](#nextjs-build-api) from `next start`. Please check with the provider to see what features are supported.
|
||||
> **Good to know**: Not all serverless providers implement the [Next.js Build API](#nextjs-build-api) from `next start`. Please check with the provider to see what features are supported.
|
||||
|
||||
## Automatic Updates
|
||||
|
||||
|
|
@ -130,7 +130,7 @@ When you deploy your Next.js application, you want to see the latest version wit
|
|||
|
||||
Next.js will automatically load the latest version of your application in the background when routing. For client-side navigations, `next/link` will temporarily function as a normal `<a>` tag.
|
||||
|
||||
**Note**: If a new page (with an old version) has already been prefetched by `next/link`, Next.js will use the old version. Navigating to a page that has _not_ been prefetched (and is not cached at the CDN level) will load the latest version.
|
||||
> **Good to know**: If a new page (with an old version) has already been prefetched by `next/link`, Next.js will use the old version. Navigating to a page that has _not_ been prefetched (and is not cached at the CDN level) will load the latest version.
|
||||
|
||||
## Manual Graceful shutdowns
|
||||
|
||||
|
|
@ -138,7 +138,7 @@ When self-hosting, you might want to run code when the server shuts down on `SIG
|
|||
|
||||
You can set the env variable `NEXT_MANUAL_SIG_HANDLE` to `true` and then register a handler for that signal inside your `_document.js` file. You will need to register the env variable directly in the `package.json` script, not in the `.env` file.
|
||||
|
||||
> **Note**: Manual signal handling is not available in `next dev`.
|
||||
> **Good to know**: Manual signal handling is not available in `next dev`.
|
||||
|
||||
```json filename="package.json"
|
||||
{
|
||||
|
|
|
|||
|
|
@ -32,7 +32,7 @@ If you're using ESLint, you need to upgrade your ESLint version:
|
|||
npm install -D eslint-config-next@latest
|
||||
```
|
||||
|
||||
> **Note:** You may need to restart the ESLint server in VS Code for the ESLint changes to take effect. Open the Command Palette (`cmd+shift+p` on Mac; `ctrl+shift+p` on Windows) and search for `ESLint: Restart ESLint Server`.
|
||||
> **Good to know**: You may need to restart the ESLint server in VS Code for the ESLint changes to take effect. Open the Command Palette (`cmd+shift+p` on Mac; `ctrl+shift+p` on Windows) and search for `ESLint: Restart ESLint Server`.
|
||||
|
||||
## Next Steps
|
||||
|
||||
|
|
@ -340,7 +340,7 @@ We recommend breaking down the migration of a page into two main steps:
|
|||
- Step 1: Move the default exported Page Component into a new Client Component.
|
||||
- Step 2: Import the new Client Component into a new `page.js` file inside the `app` directory.
|
||||
|
||||
> **Note:** This is the easiest migration path because it has the most comparable behavior to the `pages` directory.
|
||||
> **Good to know**: This is the easiest migration path because it has the most comparable behavior to the `pages` directory.
|
||||
|
||||
**Step 1: Create a new Client Component**
|
||||
|
||||
|
|
@ -870,7 +870,7 @@ export async function GET(request: Request) {}
|
|||
export async function GET(request) {}
|
||||
```
|
||||
|
||||
> **Note:** If you previously used API routes to call an external API from the client, you can now use [Server Components](/docs/getting-started/react-essentials#server-components) instead to securely fetch data. Learn more about [data fetching](/docs/app/building-your-application/data-fetching/fetching).
|
||||
> **Good to know**: If you previously used API routes to call an external API from the client, you can now use [Server Components](/docs/getting-started/react-essentials#server-components) instead to securely fetch data. Learn more about [data fetching](/docs/app/building-your-application/data-fetching/fetching).
|
||||
|
||||
### Step 7: Styling
|
||||
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ description: Optimize Images in your Next.js Application using the built-in `nex
|
|||
|
||||
<PagesOnly>
|
||||
|
||||
> **Note**: If you are using a version of Next.js prior to 13, you'll want to use the [next/legacy/image](/docs/pages/api-reference/components/image-legacy) documentation since the component was renamed.
|
||||
> **Good to know**: If you are using a version of Next.js prior to 13, you'll want to use the [next/legacy/image](/docs/pages/api-reference/components/image-legacy) documentation since the component was renamed.
|
||||
|
||||
</PagesOnly>
|
||||
|
||||
|
|
@ -152,7 +152,7 @@ export default function Page() {
|
|||
|
||||
<AppOnly>
|
||||
|
||||
> **Good to know:** Using props like `loader`, which accept a function, require using [Client Components](/docs/getting-started/react-essentials#client-components) to serialize the provided function.
|
||||
> **Good to know**: Using props like `loader`, which accept a function, require using [Client Components](/docs/getting-started/react-essentials#client-components) to serialize the provided function.
|
||||
|
||||
</AppOnly>
|
||||
|
||||
|
|
@ -290,7 +290,7 @@ The callback function will be called with one argument, a reference to the under
|
|||
|
||||
<AppOnly>
|
||||
|
||||
> **Good to know:** Using props like `onLoadingComplete`, which accept a function, require using [Client Components](/docs/getting-started/react-essentials#client-components) to serialize the provided function.
|
||||
> **Good to know**: Using props like `onLoadingComplete`, which accept a function, require using [Client Components](/docs/getting-started/react-essentials#client-components) to serialize the provided function.
|
||||
|
||||
</AppOnly>
|
||||
|
||||
|
|
@ -306,7 +306,7 @@ The load event might occur before the image placeholder is removed and the image
|
|||
|
||||
<AppOnly>
|
||||
|
||||
> **Good to know:** Using props like `onLoad`, which accept a function, require using [Client Components](/docs/getting-started/react-essentials#client-components) to serialize the provided function.
|
||||
> **Good to know**: Using props like `onLoad`, which accept a function, require using [Client Components](/docs/getting-started/react-essentials#client-components) to serialize the provided function.
|
||||
|
||||
</AppOnly>
|
||||
|
||||
|
|
@ -320,7 +320,7 @@ A callback function that is invoked if the image fails to load.
|
|||
|
||||
<AppOnly>
|
||||
|
||||
> **Good to know:** Using props like `onError`, which accept a function, require using [Client Components](/docs/getting-started/react-essentials#client-components) to serialize the provided function.
|
||||
> **Good to know**: Using props like `onError`, which accept a function, require using [Client Components](/docs/getting-started/react-essentials#client-components) to serialize the provided function.
|
||||
|
||||
</AppOnly>
|
||||
|
||||
|
|
@ -416,7 +416,7 @@ module.exports = {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note**: The example above will ensure the `src` property of `next/image` must start with `https://example.com/account123/`. Any other protocol, hostname, port, or unmatched path will respond with 400 Bad Request.
|
||||
> **Good to know**: The example above will ensure the `src` property of `next/image` must start with `https://example.com/account123/`. Any other protocol, hostname, port, or unmatched path will respond with 400 Bad Request.
|
||||
|
||||
Below is another example of the `remotePatterns` property in the `next.config.js` file:
|
||||
|
||||
|
|
@ -433,7 +433,7 @@ module.exports = {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note**: The example above will ensure the `src` property of `next/image` must start with `https://img1.example.com` or `https://me.avatar.example.com` or any number of subdomains. Any other protocol or unmatched hostname will respond with 400 Bad Request.
|
||||
> **Good to know**: The example above will ensure the `src` property of `next/image` must start with `https://img1.example.com` or `https://me.avatar.example.com` or any number of subdomains. Any other protocol or unmatched hostname will respond with 400 Bad Request.
|
||||
|
||||
Wildcard patterns can be used for both `pathname` and `hostname` and have the following syntax:
|
||||
|
||||
|
|
@ -489,7 +489,7 @@ Examples:
|
|||
|
||||
<AppOnly>
|
||||
|
||||
> **Good to know:** Customizing the image loader file, which accepts a function, require using [Client Components](/docs/getting-started/react-essentials#client-components) to serialize the provided function.
|
||||
> **Good to know**: Customizing the image loader file, which accepts a function, require using [Client Components](/docs/getting-started/react-essentials#client-components) to serialize the provided function.
|
||||
|
||||
</AppOnly>
|
||||
|
||||
|
|
@ -553,9 +553,10 @@ module.exports = {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note**: AVIF generally takes 20% longer to encode but it compresses 20% smaller compared to WebP. This means that the first time an image is requested, it will typically be slower and then subsequent requests that are cached will be faster.
|
||||
|
||||
> **Note**: If you self-host with a Proxy/CDN in front of Next.js, you must configure the Proxy to forward the `Accept` header.
|
||||
> **Good to know**:
|
||||
>
|
||||
> - AVIF generally takes 20% longer to encode but it compresses 20% smaller compared to WebP. This means that the first time an image is requested, it will typically be slower and then subsequent requests that are cached will be faster.
|
||||
> - If you self-host with a Proxy/CDN in front of Next.js, you must configure the Proxy to forward the `Accept` header.
|
||||
|
||||
## Caching Behavior
|
||||
|
||||
|
|
|
|||
|
|
@ -171,7 +171,7 @@ export default function Page() {
|
|||
|
||||
An `<a>` element is no longer required as a child of `<Link>`. Add the `legacyBehavior` prop to use the legacy behavior or remove the `<a>` to upgrade. A [codemod is available](/docs/app/building-your-application/upgrading/codemods#new-link) to automatically upgrade your code.
|
||||
|
||||
> **Note**: when `legacyBehavior` is not set to `true`, all [`anchor`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) tag properties can be passed to `next/link` as well such as, `className`, `onClick`, etc.
|
||||
> **Good to know**: when `legacyBehavior` is not set to `true`, all [`anchor`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) tag properties can be passed to `next/link` as well such as, `className`, `onClick`, etc.
|
||||
|
||||
### `passHref`
|
||||
|
||||
|
|
@ -404,6 +404,6 @@ export default function Page() {
|
|||
|
||||
<PagesOnly>
|
||||
|
||||
> **Note**: If you're using [Dynamic Routes](/docs/app/building-your-application/routing/dynamic-routes), you'll need to adapt your `as` and `href` props. For example, if you have a Dynamic Route like `/dashboard/[user]` that you want to present differently via middleware, you would write: `<Link href={{ pathname: '/dashboard/authed/[user]', query: { user: username } }} as="/dashboard/[user]">Profile</Link>`.
|
||||
> **Good to know**: If you're using [Dynamic Routes](/docs/app/building-your-application/routing/dynamic-routes), you'll need to adapt your `as` and `href` props. For example, if you have a Dynamic Route like `/dashboard/[user]` that you want to present differently via middleware, you would write: `<Link href={{ pathname: '/dashboard/authed/[user]', query: { user: username } }} as="/dashboard/[user]">Profile</Link>`.
|
||||
|
||||
</PagesOnly>
|
||||
|
|
|
|||
|
|
@ -207,7 +207,7 @@ export default function Icon({ params }) {
|
|||
|
||||
The default export function should return a `Blob` | `ArrayBuffer` | `TypedArray` | `DataView` | `ReadableStream` | `Response`.
|
||||
|
||||
> **Note:** `ImageResponse` satisfies this return type.
|
||||
> **Good to know**: `ImageResponse` satisfies this return type.
|
||||
|
||||
### Config exports
|
||||
|
||||
|
|
|
|||
|
|
@ -242,7 +242,7 @@ export default function Image({ params }) {
|
|||
|
||||
The default export function should return a `Blob` | `ArrayBuffer` | `TypedArray` | `DataView` | `ReadableStream` | `Response`.
|
||||
|
||||
> **Note:** `ImageResponse` satisfies this return type.
|
||||
> **Good to know**: `ImageResponse` satisfies this return type.
|
||||
|
||||
### Config exports
|
||||
|
||||
|
|
@ -338,7 +338,7 @@ export default function Image() {}
|
|||
|
||||
This example uses the `params` object and external data to generate the image.
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
> By default, this generated image will be [statically optimized](/docs/app/building-your-application/rendering/static-and-dynamic-rendering#static-rendering-default). You can configure the individual `fetch` [`options`](/docs/app/api-reference/functions/fetch) or route segments [options](docs/app/api-reference/file-conventions/route-segment-config#revalidate) to change this behavior.
|
||||
|
||||
```tsx filename="app/posts/[slug]/opengraph-image.tsx" switcher
|
||||
|
|
|
|||
|
|
@ -75,7 +75,7 @@ An instance of an [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScr
|
|||
|
||||
A function to reset the error boundary, which does not return a response.
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - `error.js` boundaries must be **[Client Components](/docs/getting-started/react-essentials)**.
|
||||
> - An `error.js` boundary will **not** handle errors thrown in a `layout.js` component in the **same** segment because the error boundary is nested **inside** that layouts component.
|
||||
|
|
@ -122,7 +122,7 @@ export default function GlobalError({ error, reset }) {
|
|||
}
|
||||
```
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - `global-error.js` replaces the root `layout.js` when active and so **must** define its own `<html>` and `<body>` tags.
|
||||
> - While designing error UI, you may find it helpful to use the [React Developer Tools](https://react.dev/learn/react-developer-tools) to manually toggle Error boundaries.
|
||||
|
|
|
|||
|
|
@ -37,7 +37,7 @@ export default function NotFound() {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note:** In addition to catching expected `notFound()` errors, the root `app/not-found.js` file also handles any unmatched URLs for your whole application. This means users that visit a URL that is not handled by your app will be shown the UI exported by the `app/not-found.js` file.
|
||||
> **Good to know**: In addition to catching expected `notFound()` errors, the root `app/not-found.js` file also handles any unmatched URLs for your whole application. This means users that visit a URL that is not handled by your app will be shown the UI exported by the `app/not-found.js` file.
|
||||
|
||||
## Props
|
||||
|
||||
|
|
|
|||
|
|
@ -45,7 +45,7 @@ An object containing the [search parameters](https://developer.mozilla.org/en-US
|
|||
| `/shop?a=1&b=2` | `{ a: '1', b: '2' }` |
|
||||
| `/shop?a=1&a=2` | `{ a: ['1', '2'] }` |
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - `searchParams` is a **[Dynamic API](/docs/app/building-your-application/rendering/static-and-dynamic-rendering#dynamic-functions)** whose values cannot be known ahead of time. Using it will opt the page into **[dynamic rendering](/docs/app/building-your-application/rendering/static-and-dynamic-rendering#dynamic-rendering)** at request time.
|
||||
> - `searchParams` returns a plain JavaScript object and not a `URLSearchParams` instance.
|
||||
|
|
|
|||
|
|
@ -36,7 +36,7 @@ export const preferredRegion = 'auto'
|
|||
export default function MyComponent() {}
|
||||
```
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - The values of the config options currently need be statically analyzable. For example `revalidate = 600` is valid, but `revalidate = 60 * 10` is not.
|
||||
|
||||
|
|
@ -56,7 +56,7 @@ export const dynamic = 'auto'
|
|||
// 'auto' | 'force-dynamic' | 'error' | 'force-static'
|
||||
```
|
||||
|
||||
> **Migration Note:** The new model in the `app` directory favors granular caching control at the `fetch` request level over the binary all-or-nothing model of `getServerSideProps` and `getStaticProps` at the page-level in the `pages` directory. The `dynamic` option is a way to opt back in to the previous model as a convenience and provides a simpler migration path.
|
||||
> **Good to know**: The new model in the `app` directory favors granular caching control at the `fetch` request level over the binary all-or-nothing model of `getServerSideProps` and `getStaticProps` at the page-level in the `pages` directory. The `dynamic` option is a way to opt back in to the previous model as a convenience and provides a simpler migration path.
|
||||
|
||||
- **`'auto'`** (default): The default option to cache as much as possible without preventing any components from opting into dynamic behavior.
|
||||
- **`'force-dynamic'`**: Force dynamic rendering and dynamic data fetching of a layout or page by disabling all caching of `fetch` requests and always revalidating. This option is equivalent to:
|
||||
|
|
@ -69,10 +69,10 @@ export const dynamic = 'auto'
|
|||
- `getStaticProps()` in the `pages` directory.
|
||||
- Setting the option of every `fetch()` request in a layout or page to `{ cache: 'force-cache' }`.
|
||||
- Setting the segment config to `fetchCache = 'only-cache', dynamicParams = false`.
|
||||
- Note: `dynamic = 'error'` changes the default of `dynamicParams` from `true` to `false`. You can opt back into dynamically rendering pages for dynamic params not generated by `generateStaticParams` by manually setting `dynamicParams = true`.
|
||||
- `dynamic = 'error'` changes the default of `dynamicParams` from `true` to `false`. You can opt back into dynamically rendering pages for dynamic params not generated by `generateStaticParams` by manually setting `dynamicParams = true`.
|
||||
- **`'force-static'`**: Force static rendering and static data fetching of a layout or page by forcing [`cookies()`](/docs/app/api-reference/functions/cookies), [`headers()`](/docs/app/api-reference/functions/headers) and [`useSearchParams()`](/docs/app/api-reference/functions/use-search-params) to return empty values.
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - Instructions on [how to migrate](/docs/app/building-your-application/upgrading/app-router-migration#step-6-migrating-data-fetching-methods) from `getServerSideProps` and `getStaticProps` to `dynamic: 'force-dynamic'` and `dynamic: 'error'` can be found in the [upgrade guide](/docs/app/building-your-application/upgrading/app-router-migration#step-6-migrating-data-fetching-methods).
|
||||
|
||||
|
|
@ -91,7 +91,7 @@ export const dynamicParams = true // true | false,
|
|||
- **`true`** (default): Dynamic segments not included in `generateStaticParams` are generated on demand.
|
||||
- **`false`**: Dynamic segments not included in `generateStaticParams` will return a 404.
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - This option replaces the `fallback: true | false | blocking` option of `getStaticPaths` in the `pages` directory.
|
||||
> - When `dynamicParams = true`, the segment uses [Streaming Server Rendering](/docs/app/building-your-application/routing/loading-ui-and-streaming#streaming-with-suspense).
|
||||
|
|
@ -192,7 +192,7 @@ export const preferredRegion = 'auto'
|
|||
|
||||
Support for `preferredRegion`, and regions supported, is dependent on your deployment platform.
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - If a `preferredRegion` is not specified, it will inherit the option of the nearest parent layout.
|
||||
> - The root layout defaults to `all` regions.
|
||||
|
|
|
|||
|
|
@ -43,7 +43,7 @@ export async function PATCH(request) {}
|
|||
export async function OPTIONS(request) {}
|
||||
```
|
||||
|
||||
> **Good to know:** Route Handlers are only available inside the `app` directory. You **do not** need to use API Routes (`pages`) and Route Handlers (`app`) together, as Route Handlers should be able to handle all use cases.
|
||||
> **Good to know**: Route Handlers are only available inside the `app` directory. You **do not** need to use API Routes (`pages`) and Route Handlers (`app`) together, as Route Handlers should be able to handle all use cases.
|
||||
|
||||
## Parameters
|
||||
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ related:
|
|||
|
||||
The `cookies` function allows you to read the HTTP incoming request cookies from a [Server Component](/docs/getting-started/react-essentials) or write outgoing request cookies in a [Server Action](/docs/app/building-your-application/data-fetching/server-actions) or [Route Handler](/docs/app/building-your-application/routing/router-handlers).
|
||||
|
||||
> **Good to know:** `cookies()` is a **[Dynamic Function](/docs/app/building-your-application/rendering/static-and-dynamic-rendering#dynamic-functions)** whose returned values cannot be known ahead of time. Using it in a layout or page will opt a route into **[dynamic rendering](/docs/app/building-your-application/rendering/static-and-dynamic-rendering#dynamic-rendering)** at request time.
|
||||
> **Good to know**: `cookies()` is a **[Dynamic Function](/docs/app/building-your-application/rendering/static-and-dynamic-rendering#dynamic-functions)** whose returned values cannot be known ahead of time. Using it in a layout or page will opt a route into **[dynamic rendering](/docs/app/building-your-application/rendering/static-and-dynamic-rendering#dynamic-rendering)** at request time.
|
||||
|
||||
## `cookies().get(name)`
|
||||
|
||||
|
|
@ -62,7 +62,7 @@ export default function Page() {
|
|||
|
||||
A method that takes a cookie name, value, and options and sets the outgoing request cookie.
|
||||
|
||||
> **Good to know:** `.set()` is only available in a [Server Action](/docs/app/building-your-application/data-fetching/server-actions) or [Route Handler](/docs/app/building-your-application/routing/router-handlers).
|
||||
> **Good to know**: `.set()` is only available in a [Server Action](/docs/app/building-your-application/data-fetching/server-actions) or [Route Handler](/docs/app/building-your-application/routing/router-handlers).
|
||||
|
||||
```js filename="app/actions.js"
|
||||
'use server'
|
||||
|
|
@ -87,7 +87,7 @@ async function create(data) {
|
|||
|
||||
To "delete" a cookie, you must set a new cookie with the same name and an empty value. You can also set the `maxAge` to `0` to expire the cookie immediately.
|
||||
|
||||
> **Good to know:** `.set()` is only available in a [Server Action](/docs/app/building-your-application/data-fetching/server-actions) or [Route Handler](/docs/app/building-your-application/routing/router-handlers).
|
||||
> **Good to know**: `.set()` is only available in a [Server Action](/docs/app/building-your-application/data-fetching/server-actions) or [Route Handler](/docs/app/building-your-application/routing/router-handlers).
|
||||
|
||||
```js filename="app/actions.js"
|
||||
'use server';
|
||||
|
|
|
|||
|
|
@ -70,7 +70,7 @@ fetch(`https://...`, { cache: 'force-cache' | 'no-store' })
|
|||
- If there is no match or a stale match, Next.js will fetch the resource from the remote server and update the cache with the downloaded resource.
|
||||
- **`no-store`** - Next.js fetches the resource from the remote server on every request without looking in the cache, and it will not update the cache with the downloaded resource.
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - If you don't provide a `cache` option, Next.js will default to `force-cache`, unless a [dynamic function](/docs/app/building-your-application/rendering/static-and-dynamic-rendering#dynamic-functions) such as `cookies()` is used, in which case it will default to `no-store`.
|
||||
> - The `no-cache` option behaves the same way as `no-store` in Next.js.
|
||||
|
|
@ -87,7 +87,7 @@ Set the cache lifetime of a resource (in seconds).
|
|||
- **`0`** - Prevent the resource from being cached.
|
||||
- **`number`** - (in seconds) Specify the resource should have a cache lifetime of at most `n` seconds.
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - If an individual `fetch()` request sets a `revalidate` number lower than the [default `revalidate`](/docs/app/api-reference/file-conventions/route-segment-config#revalidate) of a route, the whole route revalidation interval will be decreased.
|
||||
> - If two fetch requests with the same URL in the same route have different `revalidate` values, the lower value will be used.
|
||||
|
|
|
|||
|
|
@ -42,7 +42,7 @@ export async function generateMetadata({ params }) {
|
|||
}
|
||||
```
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - The `metadata` object and `generateMetadata` function exports are **only supported in Server Components**.
|
||||
> - You cannot export both the `metadata` object and `generateMetadata` function from the same route segment.
|
||||
|
|
@ -137,7 +137,7 @@ export default function Page({ params, searchParams }: Props) {}
|
|||
|
||||
`generateMetadata` should return a [`Metadata` object](#metadata-fields) containing one or more metadata fields.
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - If metadata doesn't depend on runtime information, it should be defined using the static [`metadata` object](#the-metadata-object) rather than `generateMetadata`.
|
||||
> - When rendering a route, Next.js will [automatically deduplicate `fetch` requests](/docs/app/building-your-application/data-fetching#automatic-fetch-request-deduping) for the same data across `generateMetadata`, `generateStaticParams`, Layouts, Pages, and Server Components. React [`cache` can be used](/docs/app/building-your-application/data-fetching/caching#react-cache) if `fetch` is unavailable.
|
||||
|
|
@ -252,7 +252,7 @@ export const metadata: Metadata = {
|
|||
// Output: <title>About | Acme</title>
|
||||
```
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - `title.template` applies to **child** route segments and **not** the segment it's defined in. This means:
|
||||
>
|
||||
|
|
@ -306,7 +306,7 @@ export const metadata = {
|
|||
// Output: <title>About</title>
|
||||
```
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - `layout.js`
|
||||
>
|
||||
|
|
@ -397,7 +397,7 @@ export const metadata = {
|
|||
<meta property="og:image" content="https://acme.com/og-image.png" />
|
||||
```
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - `metadataBase` is typically set in root `app/layout.js` to apply to URL-based `metadata` fields across all routes.
|
||||
> - All URL-based `metadata` fields that require absolute URLs can be configured with a `metadataBase` option.
|
||||
|
|
@ -513,7 +513,7 @@ export const metadata = {
|
|||
<meta property="article:author" content="Josh" />
|
||||
```
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - It may be more convenient to use the [file-based Metadata API](/docs/app/api-reference/file-conventions/metadata/opengraph-image#image-files-jpg-png-gif) for Open Graph images. Rather than having to sync the config export with actual files, the file-based API will automatically generate the correct metadata for you.
|
||||
|
||||
|
|
@ -547,7 +547,7 @@ export const metadata = {
|
|||
|
||||
### `icons`
|
||||
|
||||
Note: We recommend using the [file-based Metadata API](/docs/app/api-reference/file-conventions/metadata/app-icons#image-files-ico-jpg-png) for icons where possible. Rather than having to sync the config export with actual files, the file-based API will automatically generate the correct metadata for you.
|
||||
> **Good to know**: We recommend using the [file-based Metadata API](/docs/app/api-reference/file-conventions/metadata/app-icons#image-files-ico-jpg-png) for icons where possible. Rather than having to sync the config export with actual files, the file-based API will automatically generate the correct metadata for you.
|
||||
|
||||
```jsx filename="layout.js / page.js"
|
||||
export const metadata = {
|
||||
|
|
@ -609,7 +609,7 @@ export const metadata = {
|
|||
/>
|
||||
```
|
||||
|
||||
> **Note:** The `msapplication-*` meta tags are no longer supported in Chromium builds of Microsoft Edge, and thus no longer needed.
|
||||
> **Good to know**: The `msapplication-*` meta tags are no longer supported in Chromium builds of Microsoft Edge, and thus no longer needed.
|
||||
|
||||
### `themeColor`
|
||||
|
||||
|
|
@ -735,7 +735,7 @@ export const metadata = {
|
|||
|
||||
### `viewport`
|
||||
|
||||
> **Note**: The `viewport` meta tag is automatically set with the following default values. Usually, manual configuration is unnecessary as the default is sufficient. However, the information is provided for completeness.
|
||||
> **Good to know**: The `viewport` meta tag is automatically set with the following default values. Usually, manual configuration is unnecessary as the default is sufficient. However, the information is provided for completeness.
|
||||
|
||||
```jsx filename="layout.js / page.js"
|
||||
export const metadata = {
|
||||
|
|
@ -1039,10 +1039,9 @@ ReactDOM.prefetchDNS(href: string)
|
|||
<link rel="dns-prefetch" href="..." />
|
||||
```
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - These methods are currently only supported in Client Components.
|
||||
> - Note: Client Components are still Server Side Rendered on initial page load.
|
||||
> - These methods are currently only supported in Client Components, which are still Server Side Rendered on initial page load.
|
||||
> - Next.js in-built features such as `next/font`, `next/image` and `next/script` automatically handle relevant resource hints.
|
||||
> - React 18.3 does not yet include type definitions for `ReactDOM.preload`, `ReactDOM.preconnect`, and `ReactDOM.preconnectDNS`. You can use `// @ts-ignore` as a temporary solution to avoid type errors.
|
||||
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ export default function Page() {
|
|||
}
|
||||
```
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - `headers()` is a **[Dynamic Function](/docs/app/building-your-application/rendering/static-and-dynamic-rendering#dynamic-functions)** whose returned values cannot be known ahead of time. Using it in a layout or page will opt a route into **[dynamic rendering](/docs/app/building-your-application/rendering/static-and-dynamic-rendering#dynamic-rendering)** at request time.
|
||||
|
||||
|
|
|
|||
|
|
@ -29,4 +29,4 @@ export default async function Profile({ params }) {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note:** `notFound()` does not require you to use `return notFound()` due to using the TypeScript [`never`](https://www.typescriptlang.org/docs/handbook/2/functions.html#never) type.
|
||||
> **Good to know**: `notFound()` does not require you to use `return notFound()` due to using the TypeScript [`never`](https://www.typescriptlang.org/docs/handbook/2/functions.html#never) type.
|
||||
|
|
|
|||
|
|
@ -28,4 +28,4 @@ export default async function Profile({ params }) {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note:** `redirect()` does not require you to use `return redirect()` due to using the TypeScript [`never`](https://www.typescriptlang.org/docs/handbook/2/functions.html#never) type.
|
||||
> **Good to know**: `redirect()` does not require you to use `return redirect()` due to using the TypeScript [`never`](https://www.typescriptlang.org/docs/handbook/2/functions.html#never) type.
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ export async function GET(request) {
|
|||
}
|
||||
```
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - `revalidatePath` is available in both [Node.js and Edge runtimes](/docs/pages/building-your-application/rendering/edge-and-nodejs-runtimes).
|
||||
> - `revalidatePath` will revalidate _all segments_ under a dynamic route segment. For example, if you have a dynamic segment `/product/[id]` and you call `revalidatePath('/product/[id]')`, then all segments under `/product/[id]` will be revalidated as requested.
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ export async function GET(request) {
|
|||
}
|
||||
```
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - `revalidateTag` is available in both [Node.js and Edge runtimes](/docs/pages/building-your-application/rendering/edge-and-nodejs-runtimes).
|
||||
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ description: API Reference for the useParams hook.
|
|||
|
||||
`useParams` is a **Client Component** hook that lets you read a route's [dynamic params](/docs/app/building-your-application/routing/dynamic-routes) filled in by the current URL.
|
||||
|
||||
> **Note:** Support for `useParams` is added in Next.js 13.3.
|
||||
> **Good to know**: Support for `useParams` is added in Next.js 13.3.
|
||||
|
||||
```tsx filename="app/example-client-component.tsx" switcher
|
||||
'use client'
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ export default function ExampleClientComponent() {
|
|||
|
||||
For example, a Client Component with `usePathname` will be rendered into HTML on the initial page load. When navigating to a new route, this component does not need to be re-fetched. Instead, the component is downloaded once (in the client JavaScript bundle), and re-renders based on the current state.
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - Reading the current URL from a [Server Component](/docs/getting-started/react-essentials) is not supported. This design is intentional to support layout state being preserved across page navigations.
|
||||
> - Compatibility mode:
|
||||
|
|
|
|||
|
|
@ -207,7 +207,7 @@ useReportWebVitals((metric) => {
|
|||
})
|
||||
```
|
||||
|
||||
> **Note**: If you use [Google Analytics](https://analytics.google.com/analytics/web/), using the
|
||||
> **Good to know**: If you use [Google Analytics](https://analytics.google.com/analytics/web/), using the
|
||||
> `id` value can allow you to construct metric distributions manually (to calculate percentiles,
|
||||
> etc.)
|
||||
|
||||
|
|
|
|||
|
|
@ -48,7 +48,7 @@ export default function Page() {
|
|||
- `router.back()`: Navigate back to the previous route in the browser’s history stack using [soft navigation](/docs/app/building-your-application/routing/linking-and-navigating#soft-navigation).
|
||||
- `router.forward()`: Navigate forwards to the next page in the browser’s history stack using [soft navigation](/docs/app/building-your-application/routing/linking-and-navigating#soft-navigation).
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - The `push()` and `replace()` methods will perform a [soft navigation](/docs/app/building-your-application/routing/linking-and-navigating#soft-navigation) if the new route has been prefetched, and either, doesn't include [dynamic segments](/docs/app/building-your-application/routing/dynamic-routes) or has the same dynamic parameters as the current route.
|
||||
> - `next/link` automatically prefetch routes as they become visible in the viewport.
|
||||
|
|
@ -111,4 +111,4 @@ export default function Layout({ children }) {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note:** `<NavigationEvents>` is wrapped in a [`Suspense` boundary](/docs/app/building-your-application/routing/loading-ui-and-streaming#example) because[`useSearchParams()`](/docs/app/api-reference/functions/use-search-params) causes client-side rendering up to the closest `Suspense` boundary during [static rendering](/docs/app/building-your-application/rendering/static-and-dynamic-rendering#static-rendering-default). [Learn more](/docs/app/api-reference/functions/use-search-params#behavior).
|
||||
> **Good to know**: `<NavigationEvents>` is wrapped in a [`Suspense` boundary](/docs/app/building-your-application/routing/loading-ui-and-streaming#example) because[`useSearchParams()`](/docs/app/api-reference/functions/use-search-params) causes client-side rendering up to the closest `Suspense` boundary during [static rendering](/docs/app/building-your-application/rendering/static-and-dynamic-rendering#static-rendering-default). [Learn more](/docs/app/api-reference/functions/use-search-params#behavior).
|
||||
|
|
|
|||
|
|
@ -69,7 +69,7 @@ const searchParams = useSearchParams()
|
|||
|
||||
- Learn more about other **read-only** methods of [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams), including the [`getAll()`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams/getAll), [`keys()`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams/keys), [`values()`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams/values), [`entries()`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams/entries), [`forEach()`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams/forEach), and [`toString()`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams/toString).
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - `useSearchParams` is a [Client Component](/docs/getting-started/react-essentials) hook and is **not supported** in [Server Components](/docs/getting-started/react-essentials) to prevent stale values during [partial rendering](/docs/app/building-your-application/routing#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`
|
||||
|
|
@ -174,7 +174,7 @@ export default function Page() {
|
|||
|
||||
If a route is [dynamically rendered](/docs/app/building-your-application/rendering/static-and-dynamic-rendering#dynamic-rendering), `useSearchParams` will be available on the server during the initial server render of the Client Component.
|
||||
|
||||
> **Note:** Setting the [`dynamic` route segment config option](/docs/app/api-reference/file-conventions/route-segment-config#dynamic) to `force-dynamic` can be used to force dynamic rendering.
|
||||
> **Good to know**: Setting the [`dynamic` route segment config option](/docs/app/api-reference/file-conventions/route-segment-config#dynamic) to `force-dynamic` can be used to force dynamic rendering.
|
||||
|
||||
For example:
|
||||
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ export default function ExampleClientComponent() {
|
|||
}
|
||||
```
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - Since `useSelectedLayoutSegment` is a [Client Component](/docs/getting-started/react-essentials#client-components) hook, and Layouts are [Server Components](/docs/getting-started/react-essentials#server-components) by default, `useSelectedLayoutSegment` is usually called via a Client Component that is imported into a Layout.
|
||||
> - `useSelectedLayoutSegment` only returns the segment one level down. To return all active segments, see [`useSelectedLayoutSegments`](/docs/app/api-reference/functions/use-selected-layout-segments)
|
||||
|
|
|
|||
|
|
@ -43,7 +43,7 @@ export default function ExampleClientComponent() {
|
|||
}
|
||||
```
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - Since `useSelectedLayoutSegments` is a [Client Component](/docs/getting-started/react-essentials#client-components) hook, and Layouts are [Server Components](/docs/getting-started/react-essentials#server-components) by default, `useSelectedLayoutSegments` is usually called via a Client Component that is imported into a Layout.
|
||||
> - The returned segments include [Route Groups](/docs/app/building-your-application/routing/route-groups), which you might not want to be included in your UI. You can use the `filter()` array method to remove items that start with a bracket.
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ title: appDir
|
|||
description: Enable the App Router to use layouts, streaming, and more.
|
||||
---
|
||||
|
||||
> **Note:** This option is **no longer** needed as of Next.js 13.4. The App Router is now stable.
|
||||
> **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/getting-started/react-essentials#server-components), [streaming](/docs/app/building-your-application/routing/loading-ui-and-streaming), and [colocated data fetching](/docs/app/building-your-application/data-fetching).
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ description: Learn how to use the assetPrefix config option to configure your CD
|
|||
> **Attention**: [Deploying to Vercel](/docs/pages/building-your-application/deploying) automatically configures a global CDN for your Next.js project.
|
||||
> You do not need to manually setup an Asset Prefix.
|
||||
|
||||
> **Note**: Next.js 9.5+ added support for a customizable [Base Path](/docs/app/api-reference/next-config-js/basePath), which is better
|
||||
> **Good to know**: Next.js 9.5+ added support for a customizable [Base Path](/docs/app/api-reference/next-config-js/basePath), which is better
|
||||
> suited for hosting your application on a sub-path like `/docs`.
|
||||
> We do not suggest you use a custom Asset Prefix for this use case.
|
||||
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ module.exports = {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note**: This value must be set at build time and cannot be changed without re-building as the value is inlined in the client-side bundles.
|
||||
> **Good to know**: This value must be set at build time and cannot be changed without re-building as the value is inlined in the client-side bundles.
|
||||
|
||||
### Links
|
||||
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ description: Optimized pages include an indicator to let you know if it's being
|
|||
|
||||
When you edit your code, and Next.js is compiling the application, a compilation indicator appears in the bottom right corner of the page.
|
||||
|
||||
> **Note**: This indicator is only present in development mode and will not appear when building and running the app in production mode.
|
||||
> **Good to know**: This indicator is only present in development mode and will not appear when building and running the app in production mode.
|
||||
|
||||
In some cases this indicator can be misplaced on your page, for example, when conflicting with a chat launcher. To change its position, open `next.config.js` and set the `buildActivityPosition` in the `devIndicators` object to `bottom-right` (default), `bottom-left`, `top-right` or `top-left`:
|
||||
|
||||
|
|
@ -33,7 +33,7 @@ module.exports = {
|
|||
|
||||
<PagesOnly>
|
||||
|
||||
> **Note**: This indicator was removed in Next.js version 10.0.1. We recommend upgrading to the latest version of Next.js.
|
||||
> **Good to know**: This indicator was removed in Next.js version 10.0.1. We recommend upgrading to the latest version of Next.js.
|
||||
|
||||
When a page qualifies for [Automatic Static Optimization](/docs/pages/building-your-application/rendering/automatic-static-optimization) we show an indicator to let you know.
|
||||
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ description: Learn to add and access environment variables in your Next.js appli
|
|||
|
||||
</details>
|
||||
|
||||
> **Note**: environment variables specified in this way will **always** be included in the JavaScript bundle, prefixing the environment variable name with `NEXT_PUBLIC_` only has an effect when specifying them [through the environment or .env files](/docs/pages/building-your-application/configuring/environment-variables).
|
||||
> **Good to know**: environment variables specified in this way will **always** be included in the JavaScript bundle, prefixing the environment variable name with `NEXT_PUBLIC_` only has an effect when specifying them [through the environment or .env files](/docs/pages/building-your-application/configuring/environment-variables).
|
||||
|
||||
To add environment variables to the JavaScript bundle, open `next.config.js` and add the `env` config:
|
||||
|
||||
|
|
|
|||
|
|
@ -41,7 +41,7 @@ module.exports = {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note**: the `query` field in `exportPathMap` cannot be used with [automatically statically optimized pages](/docs/pages/building-your-application/rendering/automatic-static-optimization) or [`getStaticProps` pages](/docs/pages/building-your-application/data-fetching/get-static-props) as they are rendered to HTML files at build-time and additional query information cannot be provided during `next export`.
|
||||
> **Good to know**: the `query` field in `exportPathMap` cannot be used with [automatically statically optimized pages](/docs/pages/building-your-application/rendering/automatic-static-optimization) or [`getStaticProps` pages](/docs/pages/building-your-application/data-fetching/get-static-props) as they are rendered to HTML files at build-time and additional query information cannot be provided during `next export`.
|
||||
|
||||
The pages will then be exported as HTML files, for example, `/about` will become `/about.html`.
|
||||
|
||||
|
|
|
|||
|
|
@ -33,9 +33,10 @@ This will create a folder at `.next/standalone` which can then be deployed on it
|
|||
|
||||
Additionally, a minimal `server.js` file is also output which can be used instead of `next start`. This minimal server does not copy the `public` or `.next/static` folders by default as these should ideally be handled by a CDN instead, although these folders can be copied to the `standalone/public` and `standalone/.next/static` folders manually, after which `server.js` file will serve these automatically.
|
||||
|
||||
> **Note**: `next.config.js` is read during `next build` and serialized into the `server.js` output file. If the legacy [`serverRuntimeConfig` or `publicRuntimeConfig` options](/docs/pages/api-reference/next-config-js/runtime-configuration) are being used, the values will be specific to values at build time.
|
||||
|
||||
> **Note**: If your project uses [Image Optimization](/docs/pages/building-your-application/optimizing/images) with the default `loader`, you must install `sharp` as a dependency:
|
||||
> **Good to know**:
|
||||
>
|
||||
> - `next.config.js` is read during `next build` and serialized into the `server.js` output file. If the legacy [`serverRuntimeConfig` or `publicRuntimeConfig` options](/docs/pages/api-reference/next-config-js/runtime-configuration) are being used, the values will be specific to values at build time.
|
||||
> - If your project uses [Image Optimization](/docs/pages/building-your-application/optimizing/images) with the default `loader`, you must install `sharp` as a dependency:
|
||||
|
||||
```bash filename="Terminal"
|
||||
npm i sharp
|
||||
|
|
|
|||
|
|
@ -70,7 +70,7 @@ module.exports = {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note**: rewrites in `beforeFiles` do not check the filesystem/dynamic routes immediately after matching a source, they continue until all `beforeFiles` have been checked.
|
||||
> **Good to know**: rewrites in `beforeFiles` do not check the filesystem/dynamic routes immediately after matching a source, they continue until all `beforeFiles` have been checked.
|
||||
|
||||
The order Next.js routes are checked is:
|
||||
|
||||
|
|
@ -131,7 +131,7 @@ module.exports = {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note**: Static pages from [Automatic Static Optimization](/docs/pages/building-your-application/rendering/automatic-static-optimization) or [prerendering](/docs/pages/building-your-application/data-fetching/get-static-props) params from rewrites will be parsed on the client after hydration and provided in the query.
|
||||
> **Good to know**: Static pages from [Automatic Static Optimization](/docs/pages/building-your-application/rendering/automatic-static-optimization) or [prerendering](/docs/pages/building-your-application/data-fetching/get-static-props) params from rewrites will be parsed on the client after hydration and provided in the query.
|
||||
|
||||
## Path Matching
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ title: Runtime Config
|
|||
description: Add client and server runtime configuration to your Next.js app.
|
||||
---
|
||||
|
||||
> **Note**: This feature is considered legacy and does not work with [Automatic Static Optimization](/docs/pages/building-your-application/rendering/automatic-static-optimization), [Output File Tracing](/docs/pages/api-reference/next-config-js/output#automatically-copying-traced-files), or [React Server Components](/docs/getting-started/react-essentials#server-components). Please use [environment variables](/docs/pages/building-your-application/configuring/environment-variables) instead to avoid initialization overhead.
|
||||
> **Good to know**: This feature is considered legacy and does not work with [Automatic Static Optimization](/docs/pages/building-your-application/rendering/automatic-static-optimization), [Output File Tracing](/docs/pages/api-reference/next-config-js/output#automatically-copying-traced-files), or [React Server Components](/docs/getting-started/react-essentials#server-components). Please use [environment variables](/docs/pages/building-your-application/configuring/environment-variables) instead to avoid initialization overhead.
|
||||
|
||||
To add runtime configuration to your app, open `next.config.js` and add the `publicRuntimeConfig` and `serverRuntimeConfig` configs:
|
||||
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ nav_title: webpack
|
|||
description: Learn how to customize the webpack config used by Next.js
|
||||
---
|
||||
|
||||
> **Note**: changes to webpack config are not covered by semver so proceed at your own risk
|
||||
> **Good to know**: changes to webpack config are not covered by semver so proceed at your own risk
|
||||
|
||||
Before continuing to add custom webpack configuration to your application make sure Next.js doesn't already support your use-case:
|
||||
|
||||
|
|
|
|||
|
|
@ -38,7 +38,7 @@ NODE_OPTIONS='-r esm' next
|
|||
NODE_OPTIONS='--inspect' next
|
||||
```
|
||||
|
||||
> **Note**: Running `next` without a command is the same as running `next dev`
|
||||
> **Good to know**: Running `next` without a command is the same as running `next dev`
|
||||
|
||||
## Build
|
||||
|
||||
|
|
@ -81,7 +81,7 @@ Or using the `PORT` environment variable:
|
|||
PORT=4000 npx next dev
|
||||
```
|
||||
|
||||
> **Note**: `PORT` cannot be set in `.env` as booting up the HTTP server happens before any other code is initialized.
|
||||
> **Good to know**: `PORT` cannot be set in `.env` as booting up the HTTP server happens before any other code is initialized.
|
||||
|
||||
You can also set the hostname to be different from the default of `0.0.0.0`, this can be useful for making the application available for other devices on the network. The default hostname can be changed with `-H`, like so:
|
||||
|
||||
|
|
@ -105,9 +105,11 @@ Or using the `PORT` environment variable:
|
|||
PORT=4000 npx next start
|
||||
```
|
||||
|
||||
> **Note**: `PORT` cannot be set in `.env` as booting up the HTTP server happens before any other code is initialized.
|
||||
|
||||
> **Note**: `next start` cannot be used with `output: 'standalone'` or `output: 'export'`.
|
||||
> **Good to know**:
|
||||
>
|
||||
> -`PORT` cannot be set in `.env` as booting up the HTTP server happens before any other code is initialized.
|
||||
>
|
||||
> - `next start` cannot be used with `output: 'standalone'` or `output: 'export'`.
|
||||
|
||||
### Keep Alive Timeout
|
||||
|
||||
|
|
|
|||
|
|
@ -111,7 +111,7 @@ When navigating between pages, we want to _persist_ page state (input values, sc
|
|||
|
||||
This layout pattern enables state persistence because the React component tree is maintained between page transitions. With the component tree, React can understand which elements have changed to preserve state.
|
||||
|
||||
> **Note**: This process is called [reconciliation](https://react.dev/learn/preserving-and-resetting-state), which is how React understands which elements have changed.
|
||||
> **Good to know**: This process is called [reconciliation](https://react.dev/learn/preserving-and-resetting-state), which is how React understands which elements have changed.
|
||||
|
||||
### With TypeScript
|
||||
|
||||
|
|
|
|||
|
|
@ -45,7 +45,7 @@ Or add a `className` to the `body` tag:
|
|||
|
||||
## Customizing `renderPage`
|
||||
|
||||
> **Note**: This 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.
|
||||
> **Good to know**: This 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.
|
||||
|
||||
For [React 18](/docs/getting-started/react-essentials) support, we recommend avoiding customizing `getInitialProps` and `renderPage`, if possible.
|
||||
|
||||
|
|
@ -89,7 +89,7 @@ class MyDocument extends Document {
|
|||
export default MyDocument
|
||||
```
|
||||
|
||||
> **Note**: `getInitialProps` in `_document` is not called during client-side transitions.
|
||||
> **Good to know**: `getInitialProps` in `_document` is not called during client-side transitions.
|
||||
|
||||
## TypeScript
|
||||
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ export default function Custom404() {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note**: You can use [`getStaticProps`](/docs/pages/building-your-application/data-fetching/get-static-props) inside this page if you need to fetch data at build time.
|
||||
> **Good to know**: You can use [`getStaticProps`](/docs/pages/building-your-application/data-fetching/get-static-props) inside this page if you need to fetch data at build time.
|
||||
|
||||
## 500 Page
|
||||
|
||||
|
|
@ -35,7 +35,7 @@ export default function Custom500() {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note**: You can use [`getStaticProps`](/docs/pages/building-your-application/data-fetching/get-static-props) inside this page if you need to fetch data at build time.
|
||||
> **Good to know**: You can use [`getStaticProps`](/docs/pages/building-your-application/data-fetching/get-static-props) inside this page if you need to fetch data at build time.
|
||||
|
||||
### More Advanced Error Page Customizing
|
||||
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ description: Next.js supports API Routes, which allow you to build your API with
|
|||
|
||||
<PagesOnly>
|
||||
|
||||
> **Note**: If you are using the App Router, you can use [Server Components](/docs/app/building-your-application/data-fetching/fetching) or [Route Handlers](/docs/app/building-your-application/routing/router-handlers) instead of API Routes.
|
||||
> **Good to know**: If you are using the App Router, you can use [Server Components](/docs/app/building-your-application/data-fetching/fetching) or [Route Handlers](/docs/app/building-your-application/routing/router-handlers) instead of API Routes.
|
||||
|
||||
</PagesOnly>
|
||||
|
||||
|
|
@ -34,7 +34,7 @@ export default function handler(req, res) {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note**: API Routes will be affected by [`pageExtensions` configuration](/docs/pages/api-reference/next-config-js/pageExtensions) in `next.config.js`.
|
||||
> **Good to know**: API Routes will be affected by [`pageExtensions` configuration](/docs/pages/api-reference/next-config-js/pageExtensions) in `next.config.js`.
|
||||
|
||||
For an API route to work, you need to export a function as default (a.k.a **request handler**), which then receives the following parameters:
|
||||
|
||||
|
|
@ -350,7 +350,7 @@ export default function handler(
|
|||
}
|
||||
```
|
||||
|
||||
> **Note**: The body of `NextApiRequest` is `any` because the client may include any payload. You should validate the type/shape of the body at runtime before using it.
|
||||
> **Good to know**: The body of `NextApiRequest` is `any` because the client may include any payload. You should validate the type/shape of the body at runtime before using it.
|
||||
|
||||
## Dynamic API Routes
|
||||
|
||||
|
|
@ -391,7 +391,7 @@ API Routes can be extended to catch all paths by adding three dots (`...`) insid
|
|||
|
||||
- `pages/api/post/[...slug].js` matches `/api/post/a`, but also `/api/post/a/b`, `/api/post/a/b/c` and so on.
|
||||
|
||||
> **Note**: You can use names other than `slug`, such as: `[...param]`
|
||||
> **Good to know**: You can use names other than `slug`, such as: `[...param]`
|
||||
|
||||
Matched parameters will be sent as a query parameter (`slug` in the example) to the page, and it will always be an array, so, the path `/api/post/a` will have the following `query` object:
|
||||
|
||||
|
|
@ -547,7 +547,7 @@ export default async function handler(req: NextRequest) {
|
|||
|
||||
You may want to restrict your edge function to specific regions when deploying so that you can colocate near your data sources ensuring lower response times which can be achieved as shown.
|
||||
|
||||
> **Note**: This configuration is available in `v12.3.2` of Next.js and up.
|
||||
> **Good to know**: This configuration is available in `v12.3.2` of Next.js and up.
|
||||
|
||||
```js
|
||||
import { NextResponse } from 'next/server'
|
||||
|
|
@ -568,6 +568,6 @@ Edge API Routes use the [Edge Runtime](/docs/pages/api-reference/edge), whereas
|
|||
|
||||
Edge API Routes can [stream responses](/docs/pages/api-reference/edge#stream-apis) from the server and run _after_ cached files (e.g. HTML, CSS, JavaScript) have been accessed. Server-side streaming can help improve performance with faster [Time To First Byte (TTFB)](https://web.dev/ttfb/).
|
||||
|
||||
> **Note**: Using [Edge Runtime](/docs/pages/api-reference/edge) with `getServerSideProps` does not give you access to the response object. If you need access to `res`, you should use the [Node.js runtime](/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes) by setting `runtime: 'nodejs'`.
|
||||
> **Good to know**: Using [Edge Runtime](/docs/pages/api-reference/edge) with `getServerSideProps` does not give you access to the response object. If you need access to `res`, you should use the [Node.js runtime](/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes) by setting `runtime: 'nodejs'`.
|
||||
|
||||
View the [supported APIs](/docs/pages/api-reference/edge) and [unsupported APIs](/docs/pages/api-reference/edge#unsupported-apis) for the Edge Runtime.
|
||||
|
|
|
|||
|
|
@ -354,4 +354,4 @@ export async function getStaticProps({ locale }) {
|
|||
- `locales`: 100 total locales
|
||||
- `domains`: 100 total locale domain items
|
||||
|
||||
> **Note**: These limits have been added initially to prevent potential [performance issues at build time](#dynamic-routes-and-getstaticprops-pages). You can workaround these limits with custom routing using [Middleware](/docs/pages/building-your-application/routing/middleware) in Next.js 12.
|
||||
> **Good to know**: These limits have been added initially to prevent potential [performance issues at build time](#dynamic-routes-and-getstaticprops-pages). You can workaround these limits with custom routing using [Middleware](/docs/pages/building-your-application/routing/middleware) in Next.js 12.
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ description: Learn how to create or update static pages at runtime with Incremen
|
|||
|
||||
Next.js allows you to create or update static pages _after_ you’ve built your site. Incremental Static Regeneration (ISR) enables you to use static-generation on a per-page basis, **without needing to rebuild the entire site**. With ISR, you can retain the benefits of static while scaling to millions of pages.
|
||||
|
||||
> **Note**: The [`edge` runtime](/docs/app/api-reference/edge) is currently not compatible with ISR, although you can leverage `stale-while-revalidate` by setting the `cache-control` header manually.
|
||||
> **Good to know**: The [`edge` runtime](/docs/app/api-reference/edge) is currently not compatible with ISR, although you can leverage `stale-while-revalidate` by setting the `cache-control` header manually.
|
||||
|
||||
To use ISR, add the `revalidate` prop to `getStaticProps`:
|
||||
|
||||
|
|
@ -77,7 +77,7 @@ When a request is made to a page that was pre-rendered at build time, it will in
|
|||
|
||||
When a request is made to a path that hasn’t been generated, Next.js will server-render the page on the first request. Future requests will serve the static file from the cache. ISR on Vercel [persists the cache globally and handles rollbacks](https://vercel.com/docs/concepts/next.js/incremental-static-regeneration?utm_source=next-site&utm_medium=docs&utm_campaign=next-website).
|
||||
|
||||
> **Note**: Check if your upstream data provider has caching enabled by default. You might need to disable (e.g. `useCdn: false`), otherwise a revalidation won't be able to pull fresh data to update the ISR cache. Caching can occur at a CDN (for an endpoint being requested) when it returns the `Cache-Control` header.
|
||||
> **Good to know**: Check if your upstream data provider has caching enabled by default. You might need to disable (e.g. `useCdn: false`), otherwise a revalidation won't be able to pull fresh data to update the ISR cache. Caching can occur at a CDN (for an endpoint being requested) when it returns the `Cache-Control` header.
|
||||
|
||||
## On-Demand Revalidation
|
||||
|
||||
|
|
@ -90,7 +90,7 @@ Starting with `v12.2.0`, Next.js supports On-Demand Incremental Static Regenerat
|
|||
|
||||
Inside `getStaticProps`, you do not need to specify `revalidate` to use on-demand revalidation. If `revalidate` is omitted, Next.js will use the default value of `false` (no revalidation) and only revalidate the page on-demand when `revalidate()` is called.
|
||||
|
||||
> **Note**: [Middleware](/docs/app/building-your-application/routing/middleware) won't be executed for On-Demand ISR requests. Instead, call `revalidate()` on the _exact_ path that you want revalidated. For example, if you have `pages/blog/[slug].js` and a rewrite from `/post-1` -> `/blog/post-1`, you would need to call `res.revalidate('/blog/post-1')`.
|
||||
> **Good to know**: [Middleware](/docs/app/building-your-application/routing/middleware) won't be executed for On-Demand ISR requests. Instead, call `revalidate()` on the _exact_ path that you want revalidated. For example, if you have `pages/blog/[slug].js` and a rewrite from `/post-1` -> `/blog/post-1`, you would need to call `res.revalidate('/blog/post-1')`.
|
||||
|
||||
### Using On-Demand Revalidation
|
||||
|
||||
|
|
@ -186,7 +186,7 @@ module.exports = {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note**: You might need to consider a race condition between multiple pods trying to update the cache at the same time, depending on how your shared mount is configured.
|
||||
> **Good to know**: You might need to consider a race condition between multiple pods trying to update the cache at the same time, depending on how your shared mount is configured.
|
||||
|
||||
## Version History
|
||||
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ The cases where the query will be updated after hydration triggering another ren
|
|||
|
||||
To be able to distinguish if the query is fully updated and ready for use, you can leverage the `isReady` field on [`next/router`](/docs/pages/api-reference/functions/use-router#router-object).
|
||||
|
||||
> **Note**: Parameters added with [dynamic routes](/docs/pages/building-your-application/routing/dynamic-routes) to a page that's using [`getStaticProps`](/docs/pages/building-your-application/data-fetching/get-static-props) will always be available inside the `query` object.
|
||||
> **Good to know**: Parameters added with [dynamic routes](/docs/pages/building-your-application/routing/dynamic-routes) to a page that's using [`getStaticProps`](/docs/pages/building-your-application/data-fetching/get-static-props) will always be available inside the `query` object.
|
||||
|
||||
`next build` will emit `.html` files for statically optimized pages. For example, the result for the page `pages/about.js` would be:
|
||||
|
||||
|
|
|
|||
|
|
@ -189,7 +189,7 @@ One of the reasons for this restriction is that React needs to have all the requ
|
|||
|
||||
Also, you must use export `getStaticProps` as a standalone function — it will **not** work if you add `getStaticProps` as a property of the page component.
|
||||
|
||||
> **Note**: if you have created a [custom app](/docs/pages/building-your-application/routing/custom-app), ensure you are passing the `pageProps` to the page component as shown in the linked document, otherwise the props will be empty.
|
||||
> **Good to know**: if you have created a [custom app](/docs/pages/building-your-application/routing/custom-app), ensure you are passing the `pageProps` to the page component as shown in the linked document, otherwise the props will be empty.
|
||||
|
||||
## Runs on every request in development
|
||||
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@ description: 'Learn how to create or update static pages at runtime with Increme
|
|||
|
||||
Next.js allows you to create or update static pages _after_ you’ve built your site. Incremental Static Regeneration (ISR) enables you to use static-generation on a per-page basis, **without needing to rebuild the entire site**. With ISR, you can retain the benefits of static while scaling to millions of pages.
|
||||
|
||||
> **Note**: The [`edge` runtime](/docs/pages/api-reference/edge) is currently not compatible with ISR, although you can leverage `stale-while-revalidate` by setting the `cache-control` header manually.
|
||||
> **Good to know**: The [`edge` runtime](/docs/pages/api-reference/edge) is currently not compatible with ISR, although you can leverage `stale-while-revalidate` by setting the `cache-control` header manually.
|
||||
|
||||
To use ISR, add the `revalidate` prop to `getStaticProps`:
|
||||
|
||||
|
|
@ -91,7 +91,7 @@ When a request is made to a page that was pre-rendered at build time, it will in
|
|||
|
||||
When a request is made to a path that hasn’t been generated, Next.js will server-render the page on the first request. Future requests will serve the static file from the cache. ISR on Vercel [persists the cache globally and handles rollbacks](https://vercel.com/docs/concepts/next.js/incremental-static-regeneration?utm_source=next-site&utm_medium=docs&utm_campaign=next-website).
|
||||
|
||||
> **Note**: Check if your upstream data provider has caching enabled by default. You might need to disable (e.g. `useCdn: false`), otherwise a revalidation won't be able to pull fresh data to update the ISR cache. Caching can occur at a CDN (for an endpoint being requested) when it returns the `Cache-Control` header.
|
||||
> **Good to know**: Check if your upstream data provider has caching enabled by default. You might need to disable (e.g. `useCdn: false`), otherwise a revalidation won't be able to pull fresh data to update the ISR cache. Caching can occur at a CDN (for an endpoint being requested) when it returns the `Cache-Control` header.
|
||||
|
||||
## On-Demand Revalidation
|
||||
|
||||
|
|
@ -104,7 +104,7 @@ Starting with `v12.2.0`, Next.js supports On-Demand Incremental Static Regenerat
|
|||
|
||||
Inside `getStaticProps`, you do not need to specify `revalidate` to use on-demand revalidation. If `revalidate` is omitted, Next.js will use the default value of `false` (no revalidation) and only revalidate the page on-demand when `revalidate()` is called.
|
||||
|
||||
> **Note**: [Middleware](/docs/pages/building-your-application/routing/middleware) won't be executed for On-Demand ISR requests. Instead, call `revalidate()` on the _exact_ path that you want revalidated. For example, if you have `pages/blog/[slug].js` and a rewrite from `/post-1` -> `/blog/post-1`, you would need to call `res.revalidate('/blog/post-1')`.
|
||||
> **Good to know**: [Middleware](/docs/pages/building-your-application/routing/middleware) won't be executed for On-Demand ISR requests. Instead, call `revalidate()` on the _exact_ path that you want revalidated. For example, if you have `pages/blog/[slug].js` and a rewrite from `/post-1` -> `/blog/post-1`, you would need to call `res.revalidate('/blog/post-1')`.
|
||||
|
||||
### Using On-Demand Revalidation
|
||||
|
||||
|
|
@ -200,4 +200,4 @@ module.exports = {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note**: You might need to consider a race condition between multiple pods trying to update the cache at the same time, depending on how your shared mount is configured.
|
||||
> **Good to know**: You might need to consider a race condition between multiple pods trying to update the cache at the same time, depending on how your shared mount is configured.
|
||||
|
|
|
|||
|
|
@ -116,7 +116,7 @@ You can use `cy.visit("/")` instead of `cy.visit("http://localhost:3000/")` if y
|
|||
|
||||
Component tests build and mount a specific component without having to bundle your whole application or launch a server. This allows for more performant tests that still provide visual feedback and the same API used for Cypress E2E tests.
|
||||
|
||||
> **Note**: Since component tests do not launch a Next.js server, capabilities like `<Image />` and `getServerSideProps` which rely on a server being available will not function out-of-the-box. See the [Cypress Next.js docs](https://docs.cypress.io/guides/component-testing/react/overview#Nextjs) for examples of getting these features working within component tests.
|
||||
> **Good to know**: Since component tests do not launch a Next.js server, capabilities like `<Image />` and `getServerSideProps` which rely on a server being available will not function out-of-the-box. See the [Cypress Next.js docs](https://docs.cypress.io/guides/component-testing/react/overview#Nextjs) for examples of getting these features working within component tests.
|
||||
|
||||
Assuming the same components from the previous section, add a test to validate a component is rendering the expected output:
|
||||
|
||||
|
|
@ -146,7 +146,7 @@ Since Cypress E2E tests are testing a real Next.js application they require the
|
|||
|
||||
Run `npm run build` and `npm run start`, then run `npm run cypress -- --e2e` in another terminal window to start Cypress and run your E2E testing suite.
|
||||
|
||||
> **Note**: Alternatively, you can install the `start-server-and-test` package and add it to the `package.json` scripts field: `"test": "start-server-and-test start http://localhost:3000 cypress"` to start the Next.js production server in conjunction with Cypress. Remember to rebuild your application after new changes.
|
||||
> **Good to know**: Alternatively, you can install the `start-server-and-test` package and add it to the `package.json` scripts field: `"test": "start-server-and-test start http://localhost:3000 cypress"` to start the Next.js production server in conjunction with Cypress. Remember to rebuild your application after new changes.
|
||||
|
||||
#### Component Tests
|
||||
|
||||
|
|
@ -275,7 +275,7 @@ Since Playwright is testing a real Next.js application, it requires the Next.js
|
|||
|
||||
Run `npm run build` and `npm run start`, then run `npm run test:e2e` in another terminal window to run the Playwright tests.
|
||||
|
||||
> **Note**: Alternatively, you can use the [`webServer`](https://playwright.dev/docs/test-webserver/) feature to let Playwright start the development server and wait until it's fully available.
|
||||
> **Good to know**: Alternatively, you can use the [`webServer`](https://playwright.dev/docs/test-webserver/) feature to let Playwright start the development server and wait until it's fully available.
|
||||
|
||||
### Running Playwright on Continuous Integration (CI)
|
||||
|
||||
|
|
@ -347,7 +347,7 @@ Under the hood, `next/jest` is automatically configuring Jest for you, including
|
|||
- Ignoring `.next` from test resolving
|
||||
- Loading `next.config.js` for flags that enable SWC transforms
|
||||
|
||||
> **Note**: To test environment variables directly, load them manually in a separate setup script or in your `jest.config.js` file. For more information, please see [Test Environment Variables](/docs/pages/building-your-application/configuring/environment-variables#test-environment-variables).
|
||||
> **Good to know**: To test environment variables directly, load them manually in a separate setup script or in your `jest.config.js` file. For more information, please see [Test Environment Variables](/docs/pages/building-your-application/configuring/environment-variables#test-environment-variables).
|
||||
|
||||
### Setting up Jest (with Babel)
|
||||
|
||||
|
|
@ -513,7 +513,7 @@ it('renders homepage unchanged', () => {
|
|||
})
|
||||
```
|
||||
|
||||
> **Note**: Test files should not be included inside the Pages Router because any files inside the Pages Router are considered routes.
|
||||
> **Good to know**: Test files should not be included inside the Pages Router because any files inside the Pages Router are considered routes.
|
||||
|
||||
**Running your test suite**
|
||||
|
||||
|
|
|
|||
|
|
@ -61,7 +61,7 @@ To add presets/plugins **with custom configuration**, do it on the `next/babel`
|
|||
|
||||
To learn more about the available options for each config, visit babel's [documentation](https://babeljs.io/docs/) site.
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - Next.js uses the **current** Node.js version for server-side compilations.
|
||||
> - The `modules` option on `"preset-env"` should be kept to `false`, otherwise webpack code splitting is turned off.
|
||||
|
|
|
|||
|
|
@ -118,7 +118,7 @@ This is the default configuration used by Next.js:
|
|||
}
|
||||
```
|
||||
|
||||
> **Note**: Next.js also allows the file to be named `.postcssrc.json`, or, to be read from the `postcss` key in `package.json`.
|
||||
> **Good to know**: Next.js also allows the file to be named `.postcssrc.json`, or, to be read from the `postcss` key in `package.json`.
|
||||
|
||||
It is also possible to configure PostCSS with a `postcss.config.js` file, which is useful when you want to conditionally include plugins based on environment:
|
||||
|
||||
|
|
@ -147,11 +147,11 @@ module.exports = {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note**: Next.js also allows the file to be named `.postcssrc.js`.
|
||||
> **Good to know**: Next.js also allows the file to be named `.postcssrc.js`.
|
||||
|
||||
Do **not use `require()`** to import the PostCSS Plugins. Plugins must be provided as strings.
|
||||
|
||||
> **Note**: If your `postcss.config.js` needs to support other non-Next.js tools in the same project, you must use the interoperable object-based format instead:
|
||||
> **Good to know**: If your `postcss.config.js` needs to support other non-Next.js tools in the same project, you must use the interoperable object-based format instead:
|
||||
>
|
||||
> ```js
|
||||
> module.exports = {
|
||||
|
|
|
|||
|
|
@ -15,9 +15,10 @@ description: Start a Next.js app programmatically using a custom server.
|
|||
|
||||
By default, Next.js includes its own server with `next start`. If you have an existing backend, you can still use it with Next.js (this is not a custom server). A custom Next.js server allows you to start a server 100% programmatically in order to use custom server patterns. Most of the time, you will not need this - but it's available for complete customization.
|
||||
|
||||
> **Note**: A custom server **cannot** be deployed on [Vercel](https://vercel.com/solutions/nextjs).
|
||||
|
||||
> Before deciding to use a custom server, please keep in mind that it should only be used when the integrated router of Next.js can't meet your app requirements. A custom server will remove important performance optimizations, like **serverless functions** and **[Automatic Static Optimization](/docs/pages/building-your-application/rendering/automatic-static-optimization).**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - Before deciding to use a custom server, please keep in mind that it should only be used when the integrated router of Next.js can't meet your app requirements. A custom server will remove important performance optimizations, like **serverless functions** and **[Automatic Static Optimization](/docs/pages/building-your-application/rendering/automatic-static-optimization).**
|
||||
> - A custom server **cannot** be deployed on [Vercel](https://vercel.com/solutions/nextjs).
|
||||
|
||||
Take a look at the following example of a custom server:
|
||||
|
||||
|
|
|
|||
|
|
@ -176,4 +176,4 @@ A new bypass cookie value will be generated each time you run `next build`.
|
|||
|
||||
This ensures that the bypass cookie can’t be guessed.
|
||||
|
||||
> **Note**: To test Draft Mode locally over HTTP, your browser will need to allow third-party cookies and local storage access.
|
||||
> **Good to know**: To test Draft Mode locally over HTTP, your browser will need to allow third-party cookies and local storage access.
|
||||
|
|
|
|||
|
|
@ -104,7 +104,7 @@ Windows users may run into an issue when using `NODE_OPTIONS='--inspect'` as tha
|
|||
|
||||
`cross-env` will set the `NODE_OPTIONS` environment variable regardless of which platform you are on (including Mac, Linux, and Windows) and allow you to debug consistently across devices and operating systems.
|
||||
|
||||
> **Note**: Ensure Windows Defender is disabled on your machine. This external service will check _every file read_, which has been reported to greatly increase Fast Refresh time with `next dev`. This is a known issue, not related to Next.js, but it does affect Next.js development.
|
||||
> **Good to know**: Ensure Windows Defender is disabled on your machine. This external service will check _every file read_, which has been reported to greatly increase Fast Refresh time with `next dev`. This is a known issue, not related to Next.js, but it does affect Next.js development.
|
||||
|
||||
## More information
|
||||
|
||||
|
|
|
|||
|
|
@ -173,7 +173,7 @@ https://<your-site>/api/preview?secret=<token>&slug=<path>
|
|||
|
||||
## More Details
|
||||
|
||||
> **Note**: during rendering `next/router` exposes an `isPreview` flag, see the [router object docs](/docs/pages/api-reference/functions/use-router#router-object) for more info.
|
||||
> **Good to know**: during rendering `next/router` exposes an `isPreview` flag, see the [router object docs](/docs/pages/api-reference/functions/use-router#router-object) for more info.
|
||||
|
||||
### Specify the Preview Mode duration
|
||||
|
||||
|
|
@ -238,4 +238,4 @@ export default function myApiRoute(req, res) {
|
|||
Both the bypass cookie value and the private key for encrypting the `previewData` change when `next build` is completed.
|
||||
This ensures that the bypass cookie can’t be guessed.
|
||||
|
||||
> **Note**: To test Preview Mode locally over HTTP your browser will need to allow third-party cookies and local storage access.
|
||||
> **Good to know**: To test Preview Mode locally over HTTP your browser will need to allow third-party cookies and local storage access.
|
||||
|
|
|
|||
|
|
@ -42,7 +42,7 @@ Cache-Control: public, max-age=31536000, immutable
|
|||
|
||||
`Cache-Control` headers set in `next.config.js` will be overwritten in production to ensure that static assets can be cached effectively. If you need to revalidate the cache of a page that has been [statically generated](/docs/pages/building-your-application/rendering/static-site-generation), you can do so by setting `revalidate` in the page's [`getStaticProps`](/docs/pages/building-your-application/data-fetching/get-static-props) function. If you're using `next/image`, you can configure the [`minimumCacheTTL`](/docs/pages/api-reference/components/image#minimumcachettl) for the default Image Optimization loader.
|
||||
|
||||
> **Note**: When running your application locally with `next dev`, your headers are overwritten to prevent caching locally.
|
||||
> **Good to know**: When running your application locally with `next dev`, your headers are overwritten to prevent caching locally.
|
||||
|
||||
```terminal
|
||||
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
|
||||
|
|
@ -75,7 +75,7 @@ By default, `Cache-Control` headers will be set differently depending on how you
|
|||
- If the page uses `getServerSideProps` or `getInitialProps`, it will use the default `Cache-Control` header set by `next start` in order to prevent accidental caching of responses that cannot be cached. If you want a different cache behavior while using `getServerSideProps`, use `res.setHeader('Cache-Control', 'value_you_prefer')` inside of the function as shown above.
|
||||
- If the page is using `getStaticProps`, it will have a `Cache-Control` header of `s-maxage=REVALIDATE_SECONDS, stale-while-revalidate`, or if `revalidate` is _not_ used, `s-maxage=31536000, stale-while-revalidate` to cache for the maximum age possible.
|
||||
|
||||
> **Note**: Your deployment provider must support caching for dynamic responses. If you are self-hosting, you will need to add this logic yourself using a key/value store like Redis. If you are using Vercel, [Edge Caching works without configuration](https://vercel.com/docs/edge-network/caching?utm_source=next-site&utm_medium=docs&utm_campaign=next-website).
|
||||
> **Good to know**: Your deployment provider must support caching for dynamic responses. If you are self-hosting, you will need to add this logic yourself using a key/value store like Redis. If you are using Vercel, [Edge Caching works without configuration](https://vercel.com/docs/edge-network/caching?utm_source=next-site&utm_medium=docs&utm_campaign=next-website).
|
||||
|
||||
## Reducing JavaScript Size
|
||||
|
||||
|
|
|
|||
|
|
@ -370,7 +370,7 @@ module.exports = {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note**: The example above will ensure the `src` property of `next/legacy/image` must start with `https://example.com/account123/`. Any other protocol, hostname, port, or unmatched path will respond with 400 Bad Request.
|
||||
> **Good to know**: The example above will ensure the `src` property of `next/legacy/image` must start with `https://example.com/account123/`. Any other protocol, hostname, port, or unmatched path will respond with 400 Bad Request.
|
||||
|
||||
Below is another example of the `remotePatterns` property in the `next.config.js` file:
|
||||
|
||||
|
|
@ -387,7 +387,7 @@ module.exports = {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note**: The example above will ensure the `src` property of `next/legacy/image` must start with `https://img1.example.com` or `https://me.avatar.example.com` or any number of subdomains. Any other protocol or unmatched hostname will respond with 400 Bad Request.
|
||||
> **Good to know**: The example above will ensure the `src` property of `next/legacy/image` must start with `https://img1.example.com` or `https://me.avatar.example.com` or any number of subdomains. Any other protocol or unmatched hostname will respond with 400 Bad Request.
|
||||
|
||||
Wildcard patterns can be used for both `pathname` and `hostname` and have the following syntax:
|
||||
|
||||
|
|
@ -504,7 +504,7 @@ module.exports = {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note**: AVIF generally takes 20% longer to encode but it compresses 20% smaller compared to WebP. This means that the first time an image is requested, it will typically be slower and then subsequent requests that are cached will be faster.
|
||||
> **Good to know**: AVIF generally takes 20% longer to encode but it compresses 20% smaller compared to WebP. This means that the first time an image is requested, it will typically be slower and then subsequent requests that are cached will be faster.
|
||||
|
||||
## Caching Behavior
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ title: getInitialProps
|
|||
description: Fetch dynamic data on the server for your React component with getInitialProps.
|
||||
---
|
||||
|
||||
> **Note:** `getInitialProps` is a legacy API. We recommend using [`getStaticProps`](/docs/pages/building-your-application/data-fetching/get-static-props) or [`getServerSideProps`](/docs/pages/building-your-application/data-fetching/get-server-side-props) instead.
|
||||
> **Good to know**: `getInitialProps` is a legacy API. We recommend using [`getStaticProps`](/docs/pages/building-your-application/data-fetching/get-static-props) or [`getServerSideProps`](/docs/pages/building-your-application/data-fetching/get-server-side-props) instead.
|
||||
|
||||
`getInitialProps` is an `async` function that can be added to the default exported React component for the page. It will run on both the server-side and again on the client-side during page transitions. The result of the function will be forwarded to the React component as `props`.
|
||||
|
||||
|
|
@ -33,7 +33,7 @@ export default function Page({ stars }) {
|
|||
}
|
||||
```
|
||||
|
||||
> **Good to know:**
|
||||
> **Good to know**:
|
||||
>
|
||||
> - Data returned from `getInitialProps` is serialized when server rendering. Ensure the returned object from `getInitialProps` is a plain `Object`, and not using `Date`, `Map` or `Set`.
|
||||
> - For the initial page load, `getInitialProps` will run on the server only. `getInitialProps` will then also run on the client when navigating to a different route with the [`next/link`](/docs/pages/api-reference/components/link) component or by using [`next/router`](/docs/pages/api-reference/functions/use-router).
|
||||
|
|
|
|||
|
|
@ -167,7 +167,7 @@ If `fallback` is `true`, then the behavior of `getStaticProps` changes in the fo
|
|||
- When complete, the browser receives the `JSON` for the generated path. This will be used to automatically render the page with the required props. From the user’s perspective, the page will be swapped from the fallback page to the full page.
|
||||
- At the same time, Next.js adds this path to the list of pre-rendered pages. Subsequent requests to the same path will serve the generated page, like other pages pre-rendered at build time.
|
||||
|
||||
> **Note**: `fallback: true` is not supported when using [`output: 'export'`](/docs/pages/building-your-application/deploying/static-exports).
|
||||
> **Good to know**: `fallback: true` is not supported when using [`output: 'export'`](/docs/pages/building-your-application/deploying/static-exports).
|
||||
|
||||
#### When is `fallback: true` useful?
|
||||
|
||||
|
|
@ -194,7 +194,7 @@ If `fallback` is `'blocking'`, new paths not returned by `getStaticPaths` will w
|
|||
|
||||
`fallback: 'blocking'` will not _update_ generated pages by default. To update generated pages, use [Incremental Static Regeneration](/docs/pages/building-your-application/data-fetching/incremental-static-regeneration) in conjunction with `fallback: 'blocking'`.
|
||||
|
||||
> **Note**: `fallback: 'blocking'` is not supported when using [`output: 'export'`](/docs/pages/building-your-application/deploying/static-exports).
|
||||
> **Good to know**: `fallback: 'blocking'` is not supported when using [`output: 'export'`](/docs/pages/building-your-application/deploying/static-exports).
|
||||
|
||||
### Fallback pages
|
||||
|
||||
|
|
|
|||
|
|
@ -125,7 +125,7 @@ export async function getStaticProps(context) {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note**: `notFound` is not needed for [`fallback: false`](/docs/pages/api-reference/functions/get-static-paths#fallback-false) mode as only paths returned from `getStaticPaths` will be pre-rendered.
|
||||
> **Good to know**: `notFound` is not needed for [`fallback: false`](/docs/pages/api-reference/functions/get-static-paths#fallback-false) mode as only paths returned from `getStaticPaths` will be pre-rendered.
|
||||
|
||||
### `redirect`
|
||||
|
||||
|
|
|
|||
|
|
@ -381,7 +381,7 @@ You can listen to different events happening inside the Next.js Router. Here's a
|
|||
- `hashChangeStart(url, { shallow })` - Fires when the hash will change but not the page
|
||||
- `hashChangeComplete(url, { shallow })` - Fires when the hash has changed but not the page
|
||||
|
||||
> **Note**: Here `url` is the URL shown in the browser, including the [`basePath`](/docs/app/api-reference/next-config-js/basePath).
|
||||
> **Good to know**: Here `url` is the URL shown in the browser, including the [`basePath`](/docs/app/api-reference/next-config-js/basePath).
|
||||
|
||||
For example, to listen to the router event `routeChangeStart`, open or create `pages/_app.js` and subscribe to the event, like so:
|
||||
|
||||
|
|
|
|||
|
|
@ -107,7 +107,7 @@ module.exports = {
|
|||
}
|
||||
```
|
||||
|
||||
> **Note:** In Next.js, all JavaScript files in `pages` directory are considered routes. So, for `relay-compiler` you'll need to specify `artifactDirectory` configuration settings outside of the `pages`, otherwise `relay-compiler` will generate files next to the source file in the `__generated__` directory, and this file will be considered a route, which will break production builds.
|
||||
> **Good to know**: In Next.js, all JavaScript files in `pages` directory are considered routes. So, for `relay-compiler` you'll need to specify `artifactDirectory` configuration settings outside of the `pages`, otherwise `relay-compiler` will generate files next to the source file in the `__generated__` directory, and this file will be considered a route, which will break production builds.
|
||||
|
||||
### Remove React Properties
|
||||
|
||||
|
|
|
|||
|
|
@ -34,7 +34,7 @@ The docs are written in [MDX](https://mdxjs.com/), a markdown format that suppor
|
|||
|
||||
VSCode has a built-in markdown previewer that you can use to see your edits locally. To enable the previewer for MDX files, you'll need to add a configuration option to your user settings.
|
||||
|
||||
Open the command pallete (`⌘ + ⇧ + P` on Mac or `Ctrl + Shift + P` on Windows) and search from `Preferences: Open User Settings (JSON)`.
|
||||
Open the command palette (`⌘ + ⇧ + P` on Mac or `Ctrl + Shift + P` on Windows) and search from `Preferences: Open User Settings (JSON)`.
|
||||
|
||||
Then, add the following line to your `settings.json` file:
|
||||
|
||||
|
|
@ -243,7 +243,7 @@ Currently, we write TS and JS examples one after the other, and link them with `
|
|||
```
|
||||
````
|
||||
|
||||
> **Note:** We plan to automatically compile TypeScript snippets to JavaScript in the future. In the meantime, you can use [transform.tools](https://transform.tools/typescript-to-javascript).
|
||||
> **Good to know**: We plan to automatically compile TypeScript snippets to JavaScript in the future. In the meantime, you can use [transform.tools](https://transform.tools/typescript-to-javascript).
|
||||
|
||||
### Line Highlighting
|
||||
|
||||
|
|
@ -297,19 +297,25 @@ We do not use emojis in the docs.
|
|||
|
||||
## Notes
|
||||
|
||||
For information that is important but not critical, use a note. Notes are a good way to add information without distracting the user from the main content.
|
||||
For information that is important but not critical, use notes. Notes are a good way to add information without distracting the user from the main content.
|
||||
|
||||
```mdx filename="notes.mdx"
|
||||
> **Good to know**: This is a single line note.
|
||||
|
||||
> **Good to know**:
|
||||
>
|
||||
> This is a note :)
|
||||
> - We also use this format for multi-line notes.
|
||||
> - There are sometimes multiple item worths knowing or keeping in mind.
|
||||
```
|
||||
|
||||
**Output:**
|
||||
|
||||
> **Good to know**: This is a single line note.
|
||||
|
||||
> **Good to know**:
|
||||
>
|
||||
> This is a note :)
|
||||
> - We also use this format for multi-line notes.
|
||||
> - There are sometimes multiple item worths knowing or keeping in mind.
|
||||
|
||||
## Related Links
|
||||
|
||||
|
|
@ -374,7 +380,7 @@ Docs pages are also split into two categories: Conceptual and Reference.
|
|||
- **Conceptual** pages are used to explain a concept or feature. They are usually longer and contain more information than reference pages. In the Next.js docs, conceptual pages are found in the **Building Your Application** section.
|
||||
- **Reference** pages are used to explain a specific API. They are usually shorter and more focused. In the Next.js docs, reference pages are found in the **API Reference** section.
|
||||
|
||||
> **Note:** Depending on the page you're contributing to, you may need to follow a different voice and style. For example, conceptual pages are more instructional and use the word _you_ to address the user. Reference pages are more technical, they use more imperative words like "create, update, accept" and tend to omit the word _you_.
|
||||
> **Good to know**: Depending on the page you're contributing to, you may need to follow a different voice and style. For example, conceptual pages are more instructional and use the word _you_ to address the user. Reference pages are more technical, they use more imperative words like "create, update, accept" and tend to omit the word _you_.
|
||||
|
||||
### Voice
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue