Unverified Commit 121e1b56 authored by Joseph's avatar Joseph Committed by GitHub

[backport] docs: early October improvements and fixes (#84334)

Additional group of docs improvements.

---------
Co-authored-by: 's avatarFrançois Martin <f.martin@fastmail.com>
Co-authored-by: 's avatarliketiger <50165633+liketiger@users.noreply.github.com>
Co-authored-by: 's avatarMilancen123 <122306536+Milancen123@users.noreply.github.com>
Co-authored-by: 's avatargeraldochristiano <68152918+geraldochristiano@users.noreply.github.com>
Co-authored-by: 's avatarJJ Kasper <jj@jjsweb.site>
Co-authored-by: 's avatarAnshuman Bhardwaj <anshu5074@gmail.com>
Co-authored-by: 's avatarKarl Horky <karl.horky@gmail.com>
Co-authored-by: 's avatarJoão Henrique <117238473+joao4xz@users.noreply.github.com>
Co-authored-by: 's avatarvercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
parent 1b276c98
...@@ -5,6 +5,44 @@ description: Learn how to create a new Next.js application with the `create-next ...@@ -5,6 +5,44 @@ description: Learn how to create a new Next.js application with the `create-next
{/* The content of this doc is shared between the app and pages router. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */} {/* The content of this doc is shared between the app and pages router. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
<AppOnly>
Create a new Next.js app and run it locally.
## Quick start
1. Create a new Next.js app named `my-app`
2. `cd my-app` and start the dev server.
3. Visit `http://localhost:3000`.
```bash package="pnpm"
pnpm create next-app@latest my-app --yes
cd my-app
pnpm dev
```
```bash package="npm"
npx create-next-app@latest my-app --yes
cd my-app
npm run dev
```
```bash package="yarn"
yarn create next-app@latest my-app --yes
cd my-app
yarn dev
```
```bash package="bun"
bun create next-app@latest my-app --yes
cd my-app
bun dev
```
- `--yes` skips prompts using saved preferences or defaults. The default setup enables TypeScript, Tailwind, App Router, and Turbopack, with import alias `@/*`.
</AppOnly>
## System requirements ## System requirements
Before you begin, make sure your system meets the following requirements: Before you begin, make sure your system meets the following requirements:
...@@ -12,7 +50,7 @@ Before you begin, make sure your system meets the following requirements: ...@@ -12,7 +50,7 @@ Before you begin, make sure your system meets the following requirements:
- [Node.js 18.18](https://nodejs.org/) or later. - [Node.js 18.18](https://nodejs.org/) or later.
- macOS, Windows (including WSL), or Linux. - macOS, Windows (including WSL), or Linux.
## Automatic installation ## Create with the CLI
The quickest way to create a new Next.js app is using [`create-next-app`](/docs/app/api-reference/cli/create-next-app), which sets up everything automatically for you. To create a project, run: The quickest way to create a new Next.js app is using [`create-next-app`](/docs/app/api-reference/cli/create-next-app), which sets up everything automatically for you. To create a project, run:
......
...@@ -52,6 +52,8 @@ Top-level files are used to configure your application, manage dependencies, run ...@@ -52,6 +52,8 @@ Top-level files are used to configure your application, manage dependencies, run
### Routing Files ### Routing Files
Add `page` to expose a route, `layout` for shared UI such as header, nav, or footer, `loading` for skeletons, `error` for error boundaries and `route` for APIs.
| | | | | | | |
| ----------------------------------------------------------------------------- | ------------------- | ---------------------------- | | ----------------------------------------------------------------------------- | ------------------- | ---------------------------- |
| [`layout`](/docs/app/api-reference/file-conventions/layout) | `.js` `.jsx` `.tsx` | Layout | | [`layout`](/docs/app/api-reference/file-conventions/layout) | `.js` `.jsx` `.tsx` | Layout |
...@@ -66,35 +68,50 @@ Top-level files are used to configure your application, manage dependencies, run ...@@ -66,35 +68,50 @@ Top-level files are used to configure your application, manage dependencies, run
### Nested routes ### Nested routes
| | | Folders define URL segments. Nesting folders nests segments. Layouts at any level wrap their child segments. A route becomes public when a `page` or `route` file exists.
| --------------- | -------------------- |
| `folder` | Route segment | | Path | URL pattern | Notes |
| `folder/folder` | Nested route segment | | --------------------------- | --------------- | ----------------------------- |
| `app/layout.tsx` | — | Root layout wraps all routes |
| `app/blog/layout.tsx` | — | Wraps `/blog` and descendants |
| `app/page.tsx` | `/` | Public route |
| `app/blog/page.tsx` | `/blog` | Public route |
| `app/blog/authors/page.tsx` | `/blog/authors` | Public route |
### Dynamic routes ### Dynamic routes
| | | Parameterize segments with square brackets. Use `[segment]` for a single param, `[...segment]` for catch‑all, and `[[...segment]]` for optional catch‑all. Access values via the [`params`](/docs/app/api-reference/file-conventions/page#params-optional) prop.
| ------------------------------------------------------------------------------------------------------ | -------------------------------- |
| [`[folder]`](/docs/app/api-reference/file-conventions/dynamic-routes#convention) | Dynamic route segment | | Path | URL pattern |
| [`[...folder]`](/docs/app/api-reference/file-conventions/dynamic-routes#catch-all-segments) | Catch-all route segment | | ------------------------------- | -------------------------------------------------------------------- |
| [`[[...folder]]`](/docs/app/api-reference/file-conventions/dynamic-routes#optional-catch-all-segments) | Optional catch-all route segment | | `app/blog/[slug]/page.tsx` | `/blog/my-first-post` |
| `app/shop/[...slug]/page.tsx` | `/shop/clothing`, `/shop/clothing/shirts` |
| `app/docs/[[...slug]]/page.tsx` | `/docs`, `/docs/layouts-and-pages`, `/docs/api-reference/use-router` |
### Route Groups and private folders ### Route Groups and private folders
| | | Organize code without changing URLs with route groups [`(group)`](/docs/app/api-reference/file-conventions/route-groups#convention), and colocate non-routable files with private folders [`_folder`](#private-folders).
| ------------------------------------------------------------------------------ | ------------------------------------------------ |
| [`(folder)`](/docs/app/api-reference/file-conventions/route-groups#convention) | Group routes without affecting routing | | Path | URL pattern | Notes |
| [`_folder`](#private-folders) | Opt folder and all child segments out of routing | | ------------------------------- | ----------- | ----------------------------------------- |
| `app/(marketing)/page.tsx` | `/` | Group omitted from URL |
| `app/(shop)/cart/page.tsx` | `/cart` | Share layouts within `(shop)` |
| `app/blog/_components/Post.tsx` | — | Not routable; safe place for UI utilities |
| `app/blog/_lib/data.ts` | — | Not routable; safe place for utils |
### Parallel and Intercepted Routes ### Parallel and Intercepted Routes
| | | These features fit specific UI patterns, such as slot-based layouts or modal routing.
| ------------------------------------------------------------------------------------------- | -------------------------- |
| [`@folder`](/docs/app/api-reference/file-conventions/parallel-routes#slots) | Named slot | Use `@slot` for named slots rendered by a parent layout. Use intercept patterns to render another route inside the current layout without changing the URL, for example, to show a details view as a modal over a list.
| [`(.)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention) | Intercept same level |
| [`(..)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention) | Intercept one level above | | Pattern (docs) | Meaning | Typical use case |
| [`(..)(..)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention) | Intercept two levels above | | ------------------------------------------------------------------------------------------- | -------------------- | ------------------------------------ |
| [`(...)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention) | Intercept from root | | [`@folder`](/docs/app/api-reference/file-conventions/parallel-routes#slots) | Named slot | Sidebar + main content |
| [`(.)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention) | Intercept same level | Preview sibling route in a modal |
| [`(..)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention) | Intercept parent | Open parent child as overlay |
| [`(..)(..)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention) | Intercept two levels | Deeply nested overlay |
| [`(...)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention) | Intercept from root | Show arbitrary route in current view |
### Metadata file conventions ### Metadata file conventions
......
...@@ -13,6 +13,7 @@ related: ...@@ -13,6 +13,7 @@ related:
- app/api-reference/file-conventions/metadata/opengraph-image - app/api-reference/file-conventions/metadata/opengraph-image
- app/api-reference/file-conventions/metadata/robots - app/api-reference/file-conventions/metadata/robots
- app/api-reference/file-conventions/metadata/sitemap - app/api-reference/file-conventions/metadata/sitemap
- app/api-reference/config/next-config-js/htmlLimitedBots
--- ---
The Metadata APIs can be used to define your application metadata for improved SEO and web shareability and include: The Metadata APIs can be used to define your application metadata for improved SEO and web shareability and include:
...@@ -117,9 +118,15 @@ export default function Page({ params, searchParams }) {} ...@@ -117,9 +118,15 @@ export default function Page({ params, searchParams }) {}
### Streaming metadata ### Streaming metadata
For dynamically rendered pages, if resolving `generateMetadata` might block rendering, Next.js streams the resolved metadata separately and injects it into the HTML as soon as it's ready. For dynamically rendered pages, Next.js streams metadata separately, injecting it into the HTML once `generateMetadata` resolves, without blocking UI rendering.
Statically rendered pages don’t use this behavior since metadata is resolved at build time. Streaming metadata improves perceived performance by allowing visual content to stream first.
Streaming metadata is **disabled for bots and crawlers** that expect metadata to be in the `<head>` tag (e.g. `Twitterbot`, `Slackbot`, `Bingbot`). These are detected by using the User Agent header from the incoming request.
You can customize or **disable** streaming metadata completely, with the [`htmlLimitedBots`](/docs/app/api-reference/config/next-config-js/htmlLimitedBots#disabling) option in your Next.js config file.
Statically rendered pages don’t use streaming since metadata is resolved at build time.
Learn more about [streaming metadata](/docs/app/api-reference/functions/generate-metadata#streaming-metadata). Learn more about [streaming metadata](/docs/app/api-reference/functions/generate-metadata#streaming-metadata).
......
...@@ -28,7 +28,7 @@ To implement this pattern, use: ...@@ -28,7 +28,7 @@ To implement this pattern, use:
- [Route Handlers](/docs/app/api-reference/file-conventions/route) - [Route Handlers](/docs/app/api-reference/file-conventions/route)
- [`middleware`](/docs/app/api-reference/file-conventions/middleware) - [`middleware`](/docs/app/api-reference/file-conventions/middleware)
- In Pages Router, [API Routes](/pages/building-your-application/routing/api-routes) - In Pages Router, [API Routes](/docs/pages/building-your-application/routing/api-routes)
## Public Endpoints ## Public Endpoints
......
...@@ -50,7 +50,7 @@ export default function Page() { ...@@ -50,7 +50,7 @@ export default function Page() {
} }
``` ```
> **Good to know:** When working with forms that have multiple fields, you can use the [`entries()`](https://developer.mozilla.org/en-US/docs/Web/API/FormData/entries) method with JavaScript's [`Object.fromEntries()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/fromEntries). For example: `const rawFormData = Object.fromEntries(formData)`. > **Good to know:** When working with forms that have multiple fields, use JavaScript's [`Object.fromEntries()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/fromEntries). For example: `const rawFormData = Object.fromEntries(formData)`. Note that this object will contain extra properties prefixed with `$ACTION_`.
## Passing additional arguments ## Passing additional arguments
......
...@@ -4,7 +4,7 @@ nav_title: JSON-LD ...@@ -4,7 +4,7 @@ nav_title: JSON-LD
description: Learn how to add JSON-LD to your Next.js application to describe your content to search engines and AI. description: Learn how to add JSON-LD to your Next.js application to describe your content to search engines and AI.
--- ---
[JSON-LD](https://json-ld.org/) is a format for structured data that can be used by search engines and AI to to help them understand the structure of the page beyond pure content. For example, you can use it to describe a person, an event, an organization, a movie, a book, a recipe, and many other types of entities. [JSON-LD](https://json-ld.org/) is a format for structured data that can be used by search engines and AI to help them understand the structure of the page beyond pure content. For example, you can use it to describe a person, an event, an organization, a movie, a book, a recipe, and many other types of entities.
Our current recommendation for JSON-LD is to render structured data as a `<script>` tag in your `layout.js` or `page.js` components. Our current recommendation for JSON-LD is to render structured data as a `<script>` tag in your `layout.js` or `page.js` components.
......
...@@ -24,6 +24,7 @@ By default, Server Components are automatically [code split](https://developer.m ...@@ -24,6 +24,7 @@ By default, Server Components are automatically [code split](https://developer.m
## Examples ## Examples
<AppOnly> <AppOnly>
### Importing Client Components ### Importing Client Components
```jsx filename="app/page.js" ```jsx filename="app/page.js"
......
...@@ -219,7 +219,7 @@ export class GracefullyDegradingErrorBoundary extends Component< ...@@ -219,7 +219,7 @@ export class GracefullyDegradingErrorBoundary extends Component<
ErrorBoundaryProps, ErrorBoundaryProps,
ErrorBoundaryState ErrorBoundaryState
> { > {
private contentRef: React.RefObject<HTMLDivElement> private contentRef: React.RefObject<HTMLDivElement | null>
constructor(props: ErrorBoundaryProps) { constructor(props: ErrorBoundaryProps) {
super(props) super(props)
......
...@@ -88,7 +88,7 @@ export function onRequestError( ...@@ -88,7 +88,7 @@ export function onRequestError(
request: { request: {
path: string // resource path, e.g. /blog?name=foo path: string // resource path, e.g. /blog?name=foo
method: string // request method. e.g. GET, POST, etc method: string // request method. e.g. GET, POST, etc
headers: { [key: string]: string } headers: { [key: string]: string | string[] }
}, },
context: { context: {
routerKind: 'Pages Router' | 'App Router' // the router type routerKind: 'Pages Router' | 'App Router' // the router type
......
...@@ -105,6 +105,7 @@ export default function Layout(props: LayoutProps<'/dashboard'>) { ...@@ -105,6 +105,7 @@ export default function Layout(props: LayoutProps<'/dashboard'>) {
> **Good to know**: > **Good to know**:
> >
> - Types are generated during `next dev`, `next build` or `next typegen`. > - Types are generated during `next dev`, `next build` or `next typegen`.
> - After type generation, the `LayoutProps` helper is globally available. It doesn't need to be imported.
### Root Layout ### Root Layout
......
...@@ -20,6 +20,8 @@ Middleware executes before routes are rendered. It's particularly useful for imp ...@@ -20,6 +20,8 @@ Middleware executes before routes are rendered. It's particularly useful for imp
Create a `middleware.ts` (or `.js`) file in the project root, or inside `src` if applicable, so that it is located at the same level as `pages` or `app`. Create a `middleware.ts` (or `.js`) file in the project root, or inside `src` if applicable, so that it is located at the same level as `pages` or `app`.
If you’ve customized [`pageExtensions`](/docs/app/api-reference/config/next-config-js/pageExtensions), for example to `.page.ts` or `.page.js`, name your file `middleware.page.ts` or `middleware.page.js` accordingly.
```tsx filename="middleware.ts" switcher ```tsx filename="middleware.ts" switcher
import { NextResponse, NextRequest } from 'next/server' import { NextResponse, NextRequest } from 'next/server'
......
...@@ -135,6 +135,7 @@ export default async function Page(props: PageProps<'/blog/[slug]'>) { ...@@ -135,6 +135,7 @@ export default async function Page(props: PageProps<'/blog/[slug]'>) {
> - Using a literal route (e.g. `'/blog/[slug]'`) enables autocomplete and strict keys for `params`. > - Using a literal route (e.g. `'/blog/[slug]'`) enables autocomplete and strict keys for `params`.
> - Static routes resolve `params` to `{}`. > - Static routes resolve `params` to `{}`.
> - Types are generated during `next dev`, `next build`, or with `next typegen`. > - Types are generated during `next dev`, `next build`, or with `next typegen`.
> - After type generation, the `PageProps` helper is globally available. It doesn't need to be imported.
## Examples ## Examples
......
...@@ -118,6 +118,7 @@ export async function GET(_req: NextRequest, ctx: RouteContext<'/users/[id]'>) { ...@@ -118,6 +118,7 @@ export async function GET(_req: NextRequest, ctx: RouteContext<'/users/[id]'>) {
> **Good to know** > **Good to know**
> >
> - Types are generated during `next dev`, `next build` or `next typegen`. > - Types are generated during `next dev`, `next build` or `next typegen`.
> - After type generation, the `RouteContext` helper is globally available. It doesn't need to be imported.
## Examples ## Examples
...@@ -546,7 +547,6 @@ export async function GET(request) { ...@@ -546,7 +547,6 @@ export async function GET(request) {
> **Good to know**: > **Good to know**:
> >
> - To add CORS headers to multiple Route Handlers, you can use [Middleware](/docs/app/api-reference/file-conventions/middleware#cors) or the [`next.config.js` file](/docs/app/api-reference/config/next-config-js/headers#cors). > - To add CORS headers to multiple Route Handlers, you can use [Middleware](/docs/app/api-reference/file-conventions/middleware#cors) or the [`next.config.js` file](/docs/app/api-reference/config/next-config-js/headers#cors).
> - Alternatively, see our [CORS example](https://github.com/vercel/examples/blob/main/edge-functions/cors/lib/cors.ts) package.
### Webhooks ### Webhooks
......
...@@ -41,6 +41,10 @@ export default function Page() {} ...@@ -41,6 +41,10 @@ export default function Page() {}
Dynamic metadata depends on **dynamic information**, such as the current route parameters, external data, or `metadata` in parent segments, can be set by exporting a `generateMetadata` function that returns a [`Metadata` object](#metadata-fields). Dynamic metadata depends on **dynamic information**, such as the current route parameters, external data, or `metadata` in parent segments, can be set by exporting a `generateMetadata` function that returns a [`Metadata` object](#metadata-fields).
Resolving `generateMetadata` is part of rendering the page. If the page can be pre-rendered and `generateMetadata` doesn't introduce dynamic behavior, the resulting metadata is included in the page’s initial HTML.
Otherwise the metadata resolved from `generateMetadata` [can be streamed](/docs/app/api-reference/functions/generate-metadata#streaming-metadata) after sending the initial UI.
```tsx filename="app/products/[id]/page.tsx" switcher ```tsx filename="app/products/[id]/page.tsx" switcher
import type { Metadata, ResolvingMetadata } from 'next' import type { Metadata, ResolvingMetadata } from 'next'
...@@ -104,7 +108,6 @@ For type completion of `params` and `searchParams`, you can type the first argum ...@@ -104,7 +108,6 @@ For type completion of `params` and `searchParams`, you can type the first argum
> - The `metadata` object and `generateMetadata` function exports are **only supported in Server Components**. > - 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. > - You cannot export both the `metadata` object and `generateMetadata` function from the same route segment.
> - `fetch` requests inside `generateMetadata` are automatically [memoized](/docs/app/guides/caching#request-memoization) for the same data across `generateMetadata`, `generateStaticParams`, Layouts, Pages, and Server Components. > - `fetch` requests inside `generateMetadata` are automatically [memoized](/docs/app/guides/caching#request-memoization) for the same data across `generateMetadata`, `generateStaticParams`, Layouts, Pages, and Server Components.
> - Resolving `generateMetadata` is part of rendering the page. If the page can be pre-rendered and `generateMetadata` doesn't introduce dynamic behavior, its result is included in the page’s initial HTML.
> - React [`cache` can be used](/docs/app/guides/caching#react-cache-function) if `fetch` is unavailable. > - React [`cache` can be used](/docs/app/guides/caching#react-cache-function) if `fetch` is unavailable.
> - [File-based metadata](/docs/app/api-reference/file-conventions/metadata) has the higher priority and will override the `metadata` object and `generateMetadata` function. > - [File-based metadata](/docs/app/api-reference/file-conventions/metadata) has the higher priority and will override the `metadata` object and `generateMetadata` function.
...@@ -232,11 +235,9 @@ export const metadata = { ...@@ -232,11 +235,9 @@ export const metadata = {
> **Good to know**: > **Good to know**:
> >
> - `title.template` applies to **child** route segments and **not** the segment it's defined in. This means: > - `title.template` applies to **child** route segments and **not** the segment it's defined in. This means:
>
> - `title.default` is **required** when you add a `title.template`. > - `title.default` is **required** when you add a `title.template`.
> - `title.template` defined in `layout.js` will not apply to a `title` defined in a `page.js` of the same route segment. > - `title.template` defined in `layout.js` will not apply to a `title` defined in a `page.js` of the same route segment.
> - `title.template` defined in `page.js` has no effect because a page is always the terminating segment (it doesn't have any children route segments). > - `title.template` defined in `page.js` has no effect because a page is always the terminating segment (it doesn't have any children route segments).
>
> - `title.template` has **no effect** if a route has not defined a `title` or `title.default`. > - `title.template` has **no effect** if a route has not defined a `title` or `title.default`.
##### `absolute` ##### `absolute`
...@@ -1174,21 +1175,21 @@ There are two default `meta` tags that are always added even if a route doesn't ...@@ -1174,21 +1175,21 @@ There are two default `meta` tags that are always added even if a route doesn't
### Streaming metadata ### Streaming metadata
Metadata returned by `generateMetadata` is streamed to the client. This allows Next.js to inject metadata into the HTML as soon as it's resolved. Streaming metadata allows Next.js to render and send the initial UI to the browser, without waiting for `generateMetadata` to complete.
Streamed metadata is appended to the `<body>` tag. Since metadata mainly targets bots and crawlers, Next.js streams metadata for bots that can execute JavaScript and inspect the full DOM (e.g. `Googlebot`). We have verified that these bots interpret the metadata correctly. When `generateMetadata` resolves, the resulting metadata tags are appended to the `<body>` tag. We have verified that metadata is interpreted correctly by bots that execute JavaScript and inspect the full DOM (e.g. `Googlebot`).
For **HTML-limited** bots that can’t run JavaScript (e.g. `Twitterbot`), metadata continues to block page rendering and is placed in the `<head>` tag. For **HTML-limited bots** that can’t execute JavaScript (e.g. `facebookexternalhit`), metadata continues to block page rendering. The resulting metadata will be available in the `<head>` tag.
Next.js automatically detects the user agent of incoming requests to determine whether to serve streaming metadata or fallback to blocking metadata. Next.js automatically detects **HTML-limited bots** by looking at the User Agent header. You can use the [`htmlLimitedBots`](/docs/app/api-reference/config/next-config-js/htmlLimitedBots) option in your Next.js config file to override the default [User Agent list](https://github.com/vercel/next.js/blob/canary/packages/next/src/shared/lib/router/utils/html-bots.ts).
If you need to customize this list, you can define them manually using the `htmlLimitedBots` option in `next.config.js`. Next.js will ensure user agents matching this regex receive blocking metadata when requesting your web page. To fully disable streaming metadata:
```ts filename="next.config.ts" switcher ```ts filename="next.config.ts" switcher
import type { NextConfig } from 'next' import type { NextConfig } from 'next'
const config: NextConfig = { const config: NextConfig = {
htmlLimitedBots: /MySpecialBot|MyAnotherSpecialBot|SimpleCrawler/, htmlLimitedBots: /.*/,
} }
export default config export default config
...@@ -1196,11 +1197,11 @@ export default config ...@@ -1196,11 +1197,11 @@ export default config
```js filename="next.config.js" switcher ```js filename="next.config.js" switcher
module.exports = { module.exports = {
htmlLimitedBots: /MySpecialBot|MyAnotherSpecialBot|SimpleCrawler/, htmlLimitedBots: /.*/,
} }
``` ```
Specifying a `htmlLimitedBots` config will override the Next.js' default list, allowing you full control over what user agents should opt into this behavior. Streaming metadata improves perceived performance by reducing [TTFB](https://developer.mozilla.org/docs/Glossary/Time_to_first_byte) and can help lowering [LCP](https://developer.mozilla.org/docs/Glossary/Largest_contentful_paint) time.
Overriding `htmlLimitedBots` could lead to longer response times. Streaming metadata is an advanced feature, and the default should be sufficient for most cases. Overriding `htmlLimitedBots` could lead to longer response times. Streaming metadata is an advanced feature, and the default should be sufficient for most cases.
......
...@@ -23,9 +23,50 @@ module.exports = { ...@@ -23,9 +23,50 @@ module.exports = {
## Default list ## Default list
Next.js includes [a default list of HTML limited bots](https://github.com/vercel/next.js/blob/canary/packages/next/src/shared/lib/router/utils/html-bots.ts). Next.js includes a default list of HTML limited bots, including:
Specifying a `htmlLimitedBots` config will override the Next.js' default list, allowing you full control over what user agents should opt into this behavior. However, this is advanced behavior, and the default should be sufficient for most cases. - Google crawlers (e.g. Mediapartners-Google, AdsBot-Google, Google-PageRenderer)
- Bingbot
- Twitterbot
- Slackbot
See the full list [here](https://github.com/vercel/next.js/blob/canary/packages/next/src/shared/lib/router/utils/html-bots.ts).
Specifying a `htmlLimitedBots` config will override the Next.js' default list. However, this is advanced behavior, and the default should be sufficient for most cases.
```ts filename="next.config.ts" switcher
const config: NextConfig = {
htmlLimitedBots: /MySpecialBot|MyAnotherSpecialBot|SimpleCrawler/,
}
export default config
```
```js filename="next.config.js" switcher
module.exports = {
htmlLimitedBots: /MySpecialBot|MyAnotherSpecialBot|SimpleCrawler/,
}
```
## Disabling
To fully disable streaming metadata:
```ts filename="next.config.ts"
import type { NextConfig } from 'next'
const config: NextConfig = {
htmlLimitedBots: /.*/,
}
export default config
```
```js filename="next.config.js" switcher
module.exports = {
htmlLimitedBots: /.*/,
}
```
## Version History ## Version History
......
...@@ -90,10 +90,11 @@ The order Next.js routes are checked is: ...@@ -90,10 +90,11 @@ The order Next.js routes are checked is:
1. [headers](/docs/app/api-reference/config/next-config-js/headers) are checked/applied 1. [headers](/docs/app/api-reference/config/next-config-js/headers) are checked/applied
2. [redirects](/docs/app/api-reference/config/next-config-js/redirects) are checked/applied 2. [redirects](/docs/app/api-reference/config/next-config-js/redirects) are checked/applied
3. `beforeFiles` rewrites are checked/applied 3. [middleware](/docs/app/api-reference/file-conventions/middleware)
4. static files from the [public directory](/docs/app/api-reference/file-conventions/public-folder), `_next/static` files, and non-dynamic pages are checked/served 4. `beforeFiles` rewrites are checked/applied
5. `afterFiles` rewrites are checked/applied, if one of these rewrites is matched we check dynamic routes/static files after each match 5. static files from the [public directory](/docs/app/api-reference/file-conventions/public-folder), `_next/static` files, and non-dynamic pages are checked/served
6. `fallback` rewrites are checked/applied, these are applied before rendering the 404 page and after dynamic routes/all static assets have been checked. If you use [fallback: true/'blocking'](/docs/pages/api-reference/functions/get-static-paths#fallback-true) in `getStaticPaths`, the fallback `rewrites` defined in your `next.config.js` will _not_ be run. 6. `afterFiles` rewrites are checked/applied, if one of these rewrites is matched we check dynamic routes/static files after each match
7. `fallback` rewrites are checked/applied, these are applied before rendering the 404 page and after dynamic routes/all static assets have been checked. If you use [fallback: true/'blocking'](/docs/pages/api-reference/functions/get-static-paths#fallback-true) in `getStaticPaths`, the fallback `rewrites` defined in your `next.config.js` will _not_ be run.
</AppOnly> </AppOnly>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment