Unverified Commit c68d62d5 authored by Joseph's avatar Joseph Committed by GitHub

Backport documentation fixes for 16.1.x (#90655)

## Summary

Backports documentation fixes and improvements from canary to the
`next-16-1` branch.

### Included commits:
- `757ab17e` In-Depth Explanation of React Version Handling Doc
(#89426)
- `fe0bb2fc` Next.js sticky scroll standards (#90197)
- `d13d1ba2` docs: improve form guide consistency and validation
examples (#90361)
- `c23f3434` docs: fixes typo in manifest.mdx regarding Route Handler
note (#90394)
- `dcf11d11` docs: clarify that next upgrade is for 16.1.x+ (#90435)
- `da0cbcce` Add not-found.js / notFound() links to Status Codes
section (#88332)
- `ae79ae55` docs: add Docker Standalone and Docker Export examples to
Deploying page (#90386)
- `bb813afd` docs(deploying): add Hostinger Web Apps Hosting to
Node.js deployment options (#90246)
- `15fcfb9c` docs: fix navigationType value and variable name in
useReportWebVitals (#90599)
- `080e1b3c` docs: Accept header content negotiation (#90607)

---------
Co-authored-by: 's avatarAbhishek Mardiya <97448460+abhishekmardiya@users.noreply.github.com>
Co-authored-by: 's avatarvercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
Co-authored-by: 's avatarJimmy Lai <laijimmy0@gmail.com>
Co-authored-by: 's avatarCursor Agent <cursoragent@cursor.com>
Co-authored-by: 's avatarMary Lavanitha <lavanitha.officialdesk@gmail.com>
Co-authored-by: 's avatarTyler Arthur <46767044+tdarthur@users.noreply.github.com>
Co-authored-by: 's avatarKarl Horky <karl.horky@gmail.com>
Co-authored-by: 's avatarKristiyan Velkov <40764277+kristiyan-velkov@users.noreply.github.com>
Co-authored-by: 's avatarWyatt Johnson <accounts+github@wyattjoh.ca>
Co-authored-by: 's avatarkristiyan.velkov <kristiyan.velkov@ffw.com>
Co-authored-by: 's avataragneliutkiene <agne.liutkiene@hostinger.com>
Co-authored-by: 's avatarMimori <mimorimori256@gmail.com>
Co-authored-by: 's avatarJoseph <icyJoseph@users.noreply.github.com>
parent 5214ac15
...@@ -126,7 +126,10 @@ yarn add next@latest react@latest react-dom@latest ...@@ -126,7 +126,10 @@ yarn add next@latest react@latest react-dom@latest
bun add next@latest react@latest react-dom@latest bun add next@latest react@latest react-dom@latest
``` ```
> **Good to know**: The App Router uses [React canary releases](https://react.dev/blog/2023/05/03/react-canaries) built-in, which include all the stable React 19 changes, as well as newer features being validated in frameworks. The Pages Router uses the React version you install in `package.json`. > **Good to know**:
>
> - The `App Router` uses [React canary releases](https://react.dev/blog/2023/05/03/react-canaries) built-in, which include all the stable React 19 changes, as well as newer features being validated in frameworks, but you should still declare react and react-dom in package.json for tooling and ecosystem compatibility.
> - The `Pages Router` uses the React version from your `package.json`.
Then, add the following scripts to your `package.json` file: Then, add the following scripts to your `package.json` file:
......
...@@ -158,6 +158,8 @@ Next.js avoids this with client-side transitions using the `<Link>` component. I ...@@ -158,6 +158,8 @@ Next.js avoids this with client-side transitions using the `<Link>` component. I
Client-side transitions are what makes a server-rendered apps _feel_ like client-rendered apps. And when paired with [prefetching](#prefetching) and [streaming](#streaming), it enables fast transitions, even for dynamic routes. Client-side transitions are what makes a server-rendered apps _feel_ like client-rendered apps. And when paired with [prefetching](#prefetching) and [streaming](#streaming), it enables fast transitions, even for dynamic routes.
Next.js also handles [scrolling to the top of the page](/docs/app/api-reference/components/link#scroll) during client-side transitions. If content scrolls behind a sticky or fixed header after navigation, you can fix this with CSS [`scroll-padding-top`](/docs/app/api-reference/components/link#scroll-offset-with-sticky-headers).
## What can make transitions slow? ## What can make transitions slow?
These Next.js optimizations make navigation fast and responsive. However, under certain conditions, transitions can still _feel_ slow. Here are some common causes and how to improve the user experience: These Next.js optimizations make navigation fast and responsive. However, under certain conditions, transitions can still _feel_ slow. Here are some common causes and how to improve the user experience:
......
...@@ -35,10 +35,11 @@ Node.js deployments support all Next.js features. Learn how to [configure them]( ...@@ -35,10 +35,11 @@ Node.js deployments support all Next.js features. Learn how to [configure them](
- [Flightcontrol](https://github.com/nextjs/deploy-flightcontrol) - [Flightcontrol](https://github.com/nextjs/deploy-flightcontrol)
- [Railway](https://github.com/nextjs/deploy-railway) - [Railway](https://github.com/nextjs/deploy-railway)
- [Replit](https://github.com/nextjs/deploy-replit) - [Replit](https://github.com/nextjs/deploy-replit)
- [Hostinger](https://github.com/hostinger/deploy-nextjs)
## Docker ## Docker
Next.js can be deployed to any provider that supports [Docker](https://www.docker.com/) containers. This includes container orchestrators like Kubernetes or a cloud provider that runs Docker. Next.js can be deployed to any provider that supports [Docker](https://www.docker.com/) containers. This includes container orchestrators like Kubernetes or a cloud provider that runs Docker. For containerization best practices, see the [Docker guide for React.js](https://docs.docker.com/guides/reactjs/).
Docker deployments support all Next.js features. Learn how to [configure them](/docs/app/guides/self-hosting) for your infrastructure. Docker deployments support all Next.js features. Learn how to [configure them](/docs/app/guides/self-hosting) for your infrastructure.
...@@ -46,8 +47,14 @@ Docker deployments support all Next.js features. Learn how to [configure them](/ ...@@ -46,8 +47,14 @@ Docker deployments support all Next.js features. Learn how to [configure them](/
### Templates ### Templates
- [Docker](https://github.com/vercel/next.js/tree/canary/examples/with-docker) The following examples demonstrate best practices for containerizing Next.js applications:
- [Docker Multi-Environment](https://github.com/vercel/next.js/tree/canary/examples/with-docker-multi-env)
- [Docker Standalone Output](https://github.com/vercel/next.js/tree/canary/examples/with-docker) - Deploy a Next.js application using `output: "standalone"` to generate a minimal, production-ready Docker image with only the required runtime files and dependencies.
- [Docker Export Output](https://github.com/vercel/next.js/tree/canary/examples/with-docker-export-output) - Deploy a fully static Next.js application using `output: "export"` to generate optimized HTML files that can be served from a lightweight container or any static hosting environment.
- [Docker Multi-Environment](https://github.com/vercel/next.js/tree/canary/examples/with-docker-multi-env) - Manage separate Docker configurations for development, staging, and production environments with different environment variables.
Additionally, hosting providers offer guidance on deploying Next.js:
- [DigitalOcean](https://github.com/nextjs/deploy-digitalocean) - [DigitalOcean](https://github.com/nextjs/deploy-digitalocean)
- [Fly.io](https://github.com/nextjs/deploy-fly) - [Fly.io](https://github.com/nextjs/deploy-fly)
- [Google Cloud Run](https://github.com/nextjs/deploy-google-cloud-run) - [Google Cloud Run](https://github.com/nextjs/deploy-google-cloud-run)
......
...@@ -30,7 +30,7 @@ yarn next upgrade ...@@ -30,7 +30,7 @@ yarn next upgrade
bunx next upgrade bunx next upgrade
``` ```
Next.js 15 and earlier do not support the `upgrade` command and need to use a separate package instead: Versions before Next.js 16.1.0 do not support the `upgrade` command and need to use a separate package instead:
```bash filename="Terminal" ```bash filename="Terminal"
npx @next/codemod@canary upgrade latest npx @next/codemod@canary upgrade latest
......
...@@ -4,10 +4,11 @@ nav_title: Backend for Frontend ...@@ -4,10 +4,11 @@ nav_title: Backend for Frontend
description: Learn how to use Next.js as a backend framework description: Learn how to use Next.js as a backend framework
related: related:
title: API Reference title: API Reference
description: Learn more about Route Handlers and Proxy description: Learn more about Route Handlers, Proxy, and Rewrites
links: links:
- app/api-reference/file-conventions/route - app/api-reference/file-conventions/route
- app/api-reference/file-conventions/proxy - app/api-reference/file-conventions/proxy
- app/api-reference/config/next-config-js/rewrites
--- ---
Next.js supports the "Backend for Frontend" pattern. This lets you create public endpoints to handle HTTP requests and return any content type—not just HTML. You can also access data sources and perform side effects like updating remote data. Next.js supports the "Backend for Frontend" pattern. This lets you create public endpoints to handle HTTP requests and return any content type—not just HTML. You can also access data sources and perform side effects like updating remote data.
...@@ -178,6 +179,105 @@ export async function GET(request) { ...@@ -178,6 +179,105 @@ export async function GET(request) {
Sanitize any input used to generate markup. Sanitize any input used to generate markup.
### Content negotiation
You can use [rewrites](/docs/app/api-reference/config/next-config-js/rewrites) with header matching to serve different content types from the same URL based on the request's `Accept` header. This is known as [content negotiation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation).
For example, a documentation site might serve HTML pages to browsers and raw Markdown to AI agents from the same `/docs/…` URLs.
**1. Configure a rewrite that matches the `Accept` header:**
```js filename="next.config.js"
module.exports = {
async rewrites() {
return [
{
source: '/docs/:slug*',
destination: '/docs/md/:slug*',
has: [
{
type: 'header',
key: 'accept',
value: '(.*)text/markdown(.*)',
},
],
},
]
},
}
```
When a request to `/docs/getting-started` includes `Accept: text/markdown`, the rewrite routes it to `/docs/md/getting-started`. A Route Handler at that path returns the Markdown response. Clients that do not send `text/markdown` in their `Accept` header continue to receive the normal HTML page.
**2. Create a Route Handler for the Markdown response:**
```ts filename="app/docs/md/[...slug]/route.ts" switcher
import { getDocsMd, generateDocsStaticParams } from '@/lib/docs'
export async function generateStaticParams() {
return generateDocsStaticParams()
}
export async function GET(_: Request, ctx: RouteContext<'/docs/md/[...slug]'>) {
const { slug } = await ctx.params
const mdDoc = await getDocsMd({ slug })
if (mdDoc == null) {
return new Response(null, { status: 404 })
}
return new Response(mdDoc, {
headers: {
'Content-Type': 'text/markdown; charset=utf-8',
Vary: 'Accept',
},
})
}
```
```js filename="app/docs/md/[...slug]/route.js" switcher
import { getDocsMd, generateDocsStaticParams } from '@/lib/docs'
export async function generateStaticParams() {
return generateDocsStaticParams()
}
export async function GET(_, { params }) {
const { slug } = await params
const mdDoc = await getDocsMd({ slug })
if (mdDoc == null) {
return new Response(null, { status: 404 })
}
return new Response(mdDoc, {
headers: {
'Content-Type': 'text/markdown; charset=utf-8',
Vary: 'Accept',
},
})
}
```
The [`Vary: Accept`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Vary) response header tells caches that the response body depends on the `Accept` request header. Without it, a shared cache could serve a cached Markdown response to a browser (or vice versa). Most hosting providers already include the `Accept` header in their cache key, but setting `Vary` explicitly ensures correct behavior across all CDNs and proxy caches.
`generateStaticParams` lets you pre-render the Markdown variants at build time so they can be served from the edge without hitting the origin server on every request.
**3. Test it with `curl`:**
```bash
# Returns Markdown
curl -H "Accept: text/markdown" https://example.com/docs/getting-started
# Returns the normal HTML page
curl https://example.com/docs/getting-started
```
> **Good to know:**
>
> - The `/docs/md/...` route is still directly accessible without the rewrite. If you want to restrict it to only serve via the rewrite, use [`proxy`](/docs/app/api-reference/file-conventions/proxy) to block direct requests that don't include the expected `Accept` header.
> - For more advanced negotiation logic, you can use [`proxy`](/docs/app/api-reference/file-conventions/proxy) instead of rewrites for more flexibility.
### Consuming request payloads ### Consuming request payloads
Use Request [instance methods](https://developer.mozilla.org/en-US/docs/Web/API/Request#instance_methods) like `.json()`, `.formData()`, or `.text()` to access the request body. Use Request [instance methods](https://developer.mozilla.org/en-US/docs/Web/API/Request#instance_methods) like `.json()`, `.formData()`, or `.text()` to access the request body.
......
...@@ -884,6 +884,58 @@ export default function Home() { ...@@ -884,6 +884,58 @@ export default function Home() {
</PagesOnly> </PagesOnly>
### Scroll offset with sticky headers
Because Next.js skips sticky and fixed positioned elements when finding the scroll target, content may end up behind a sticky header after navigation. For example, if your layout has a sticky header:
```tsx filename="app/layout.tsx" switcher
import './globals.css'
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<body>
<header className="sticky top-0 h-16 bg-white">
{/* Navigation */}
</header>
{children}
</body>
</html>
)
}
```
```jsx filename="app/layout.js" switcher
import './globals.css'
export default function RootLayout({ children }) {
return (
<html lang="en">
<body>
<header className="sticky top-0 h-16 bg-white">
{/* Navigation */}
</header>
{children}
</body>
</html>
)
}
```
You can account for its height using [`scroll-padding-top`](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-padding-top) on the scroll container:
```css filename="app/globals.css"
html {
scroll-padding-top: 64px; /* Match the height of your sticky header */
}
```
This is a browser CSS property that offsets scroll-based positioning. It applies whenever Next.js uses the native [`scrollIntoView()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView) API, including hash fragment (`#id`) navigation. Alternatively, you can use [`scroll-margin-top`](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-margin-top) on individual target elements instead of setting a global offset.
### Prefetching links in Proxy ### Prefetching links in Proxy
It's common to use [Proxy](/docs/app/api-reference/file-conventions/proxy) for authentication or other purposes that involve rewriting the user to a different page. In order for the `<Link />` component to properly prefetch links with rewrites via Proxy, you need to tell Next.js both the URL to display and the URL to prefetch. This is required to avoid un-necessary fetches to proxy to know the correct route to prefetch. It's common to use [Proxy](/docs/app/api-reference/file-conventions/proxy) for authentication or other purposes that involve rewriting the user to a different page. In order for the `<Link />` component to properly prefetch links with rewrites via Proxy, you need to tell Next.js both the URL to display and the URL to prefetch. This is required to avoid un-necessary fetches to proxy to know the correct route to prefetch.
......
...@@ -21,7 +21,7 @@ Add or generate a `manifest.(json|webmanifest)` file that matches the [Web Manif ...@@ -21,7 +21,7 @@ Add or generate a `manifest.(json|webmanifest)` file that matches the [Web Manif
Add a `manifest.js` or `manifest.ts` file that returns a [`Manifest` object](#manifest-object). Add a `manifest.js` or `manifest.ts` file that returns a [`Manifest` object](#manifest-object).
> Good to know: `manifest.js` is special Route Handlers that is cached by default unless it uses a [Dynamic API](/docs/app/guides/caching#dynamic-apis) or [dynamic config](/docs/app/guides/caching#segment-config-options) option. > Good to know: `manifest.js` is a special Route Handler that is cached by default unless it uses a [Dynamic API](/docs/app/guides/caching#dynamic-apis) or [dynamic config](/docs/app/guides/caching#segment-config-options) option.
```ts filename="app/manifest.ts" switcher ```ts filename="app/manifest.ts" switcher
import type { MetadataRoute } from 'next' import type { MetadataRoute } from 'next'
......
...@@ -10,7 +10,7 @@ Next.js provides two conventions to handle not found cases: ...@@ -10,7 +10,7 @@ Next.js provides two conventions to handle not found cases:
## `not-found.js` ## `not-found.js`
The **not-found** file is used to render UI when the [`notFound`](/docs/app/api-reference/functions/not-found) function is thrown within a route segment. Along with serving a custom UI, Next.js will return a `200` HTTP status code for streamed responses, and `404` for non-streamed responses. The **not-found** file is used to render UI when the [`notFound`](/docs/app/api-reference/functions/not-found) function is thrown within a route segment. Along with serving a custom UI, Next.js will return a `200` HTTP status code for streamed responses, and `404` for non-streamed responses (see [Status Codes](/docs/app/api-reference/file-conventions/loading#status-codes) for details about SEO).
```tsx filename="app/not-found.tsx" switcher ```tsx filename="app/not-found.tsx" switcher
import Link from 'next/link' import Link from 'next/link'
......
...@@ -3,7 +3,7 @@ title: notFound ...@@ -3,7 +3,7 @@ title: notFound
description: API Reference for the notFound function. description: API Reference for the notFound function.
--- ---
The `notFound` function allows you to render the [`not-found file`](/docs/app/api-reference/file-conventions/not-found) within a route segment as well as inject a `<meta name="robots" content="noindex" />` tag. The `notFound` function allows you to render the [`not-found file`](/docs/app/api-reference/file-conventions/not-found) within a route segment as well as inject a [`<meta name="robots" content="noindex" />`](/docs/app/api-reference/file-conventions/loading#status-codes) tag for search engines.
## `notFound()` ## `notFound()`
......
...@@ -72,7 +72,7 @@ The `metric` object passed as the hook's argument consists of a number of proper ...@@ -72,7 +72,7 @@ The `metric` object passed as the hook's argument consists of a number of proper
- `name`: The name of the performance metric. Possible values include names of [Web Vitals](#web-vitals) metrics (TTFB, FCP, LCP, FID, CLS) specific to a web application. - `name`: The name of the performance metric. Possible values include names of [Web Vitals](#web-vitals) metrics (TTFB, FCP, LCP, FID, CLS) specific to a web application.
- `delta`: The difference between the current value and the previous value of the metric. The value is typically in milliseconds and represents the change in the metric's value over time. - `delta`: The difference between the current value and the previous value of the metric. The value is typically in milliseconds and represents the change in the metric's value over time.
- `entries`: An array of [Performance Entries](https://developer.mozilla.org/docs/Web/API/PerformanceEntry) associated with the metric. These entries provide detailed information about the performance events related to the metric. - `entries`: An array of [Performance Entries](https://developer.mozilla.org/docs/Web/API/PerformanceEntry) associated with the metric. These entries provide detailed information about the performance events related to the metric.
- `navigationType`: Indicates the [type of navigation](https://developer.mozilla.org/docs/Web/API/PerformanceNavigationTiming/type) that triggered the metric collection. Possible values include `"navigate"`, `"reload"`, `"back_forward"`, and `"prerender"`. - `navigationType`: Indicates the navigation type that triggered metric collection. Values are derived from [PerformanceNavigationTiming.type](https://developer.mozilla.org/docs/Web/API/PerformanceNavigationTiming/type) and may include `"navigate"`, `"reload"`, `"prerender"`, `"back-forward"` (normalized from `"back_forward"`), `"back-forward-cache"` (BFCache restore), and `"restore"` (page restored after discard).
- `rating`: A qualitative rating of the metric value, providing an assessment of the performance. Possible values are `"good"`, `"needs-improvement"`, and `"poor"`. The rating is typically determined by comparing the metric value against predefined thresholds that indicate acceptable or suboptimal performance. - `rating`: A qualitative rating of the metric value, providing an assessment of the performance. Possible values are `"good"`, `"needs-improvement"`, and `"poor"`. The rating is typically determined by comparing the metric value against predefined thresholds that indicate acceptable or suboptimal performance.
- `value`: The actual value or duration of the performance entry, typically in milliseconds. The value provides a quantitative measure of the performance aspect being tracked by the metric. The source of the value depends on the specific metric being measured and can come from various [Performance API](https://developer.mozilla.org/docs/Web/API/Performance_API)s. - `value`: The actual value or duration of the performance entry, typically in milliseconds. The value provides a quantitative measure of the performance aspect being tracked by the metric. The source of the value depends on the specific metric being measured and can come from various [Performance API](https://developer.mozilla.org/docs/Web/API/Performance_API)s.
...@@ -183,7 +183,7 @@ You can handle all the results of these metrics separately: ...@@ -183,7 +183,7 @@ You can handle all the results of these metrics separately:
```jsx filename="pages/_app.js" ```jsx filename="pages/_app.js"
import { useReportWebVitals } from 'next/web-vitals' import { useReportWebVitals } from 'next/web-vitals'
function handleCustomMetrics(metrics) { function handleCustomMetrics(metric) {
switch (metric.name) { switch (metric.name) {
case 'Next.js-hydration': case 'Next.js-hydration':
// handle hydration results // handle hydration results
...@@ -216,7 +216,7 @@ You can send results to any endpoint to measure and track ...@@ -216,7 +216,7 @@ You can send results to any endpoint to measure and track
real user performance on your site. For example: real user performance on your site. For example:
```js ```js
function postWebVitals(metrics) { function postWebVitals(metric) {
const body = JSON.stringify(metric) const body = JSON.stringify(metric)
const url = 'https://example.com/analytics' const url = 'https://example.com/analytics'
......
...@@ -362,6 +362,7 @@ NODE_OPTIONS='--inspect' next ...@@ -362,6 +362,7 @@ NODE_OPTIONS='--inspect' next
| Version | Changes | | Version | Changes |
| --------- | ------------------------------------------------------------------------------- | | --------- | ------------------------------------------------------------------------------- |
| `v16.1.0` | Add the `next upgrade` command |
| `v16.1.0` | Add the `next experimental-analyze` command | | `v16.1.0` | Add the `next experimental-analyze` command |
| `v16.0.0` | The JS bundle size metrics have been removed from `next build` | | `v16.0.0` | The JS bundle size metrics have been removed from `next build` |
| `v15.5.0` | Add the `next typegen` command | | `v15.5.0` | Add the `next typegen` command |
......
...@@ -67,7 +67,7 @@ export default function Page() { ...@@ -67,7 +67,7 @@ export default function Page() {
async function onSubmit(event) { async function onSubmit(event) {
event.preventDefault() event.preventDefault()
const formData = new FormData(event.target) const formData = new FormData(event.currentTarget)
const response = await fetch('/api/submit', { const response = await fetch('/api/submit', {
method: 'POST', method: 'POST',
body: formData, body: formData,
...@@ -171,7 +171,7 @@ export default function Page() { ...@@ -171,7 +171,7 @@ export default function Page() {
<div> <div>
{error && <div style={{ color: 'red' }}>{error}</div>} {error && <div style={{ color: 'red' }}>{error}</div>}
<form onSubmit={onSubmit}> <form onSubmit={onSubmit}>
<input type="text" name="name" /> <input type="text" name="name" required />
<button type="submit" disabled={isLoading}> <button type="submit" disabled={isLoading}>
{isLoading ? 'Loading...' : 'Submit'} {isLoading ? 'Loading...' : 'Submit'}
</button> </button>
...@@ -220,7 +220,7 @@ export default function Page() { ...@@ -220,7 +220,7 @@ export default function Page() {
<div> <div>
{error && <div style={{ color: 'red' }}>{error}</div>} {error && <div style={{ color: 'red' }}>{error}</div>}
<form onSubmit={onSubmit}> <form onSubmit={onSubmit}>
<input type="text" name="name" /> <input type="text" name="name" required />
<button type="submit" disabled={isLoading}> <button type="submit" disabled={isLoading}>
{isLoading ? 'Loading...' : 'Submit'} {isLoading ? 'Loading...' : 'Submit'}
</button> </button>
......
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