diff --git a/docs/01-getting-started/01-installation.mdx b/docs/01-getting-started/01-installation.mdx index 6ffc66d57aac0..598939c01c454 100644 --- a/docs/01-getting-started/01-installation.mdx +++ b/docs/01-getting-started/01-installation.mdx @@ -10,7 +10,7 @@ related: System Requirements: -- [Node.js 16.14](https://nodejs.org/) or later. +- [Node.js 18.17](https://nodejs.org/) or later. - macOS, Windows (including WSL), and Linux are supported. ## Automatic Installation diff --git a/docs/02-app/01-building-your-application/02-data-fetching/01-fetching-caching-and-revalidating.mdx b/docs/02-app/01-building-your-application/02-data-fetching/01-fetching-caching-and-revalidating.mdx index 3c28cd1ac0ad9..0afee64dfe2de 100644 --- a/docs/02-app/01-building-your-application/02-data-fetching/01-fetching-caching-and-revalidating.mdx +++ b/docs/02-app/01-building-your-application/02-data-fetching/01-fetching-caching-and-revalidating.mdx @@ -17,7 +17,7 @@ There are four ways you can fetch data: Next.js extends the native [`fetch` Web API](https://developer.mozilla.org/docs/Web/API/Fetch_API) to allow you to configure the [caching](#caching-data) and [revalidating](#revalidating-data) behavior for each fetch request on the server. React extends `fetch` to automatically [memoize](/docs/app/building-your-application/data-fetching/patterns#fetching-data-where-its-needed) fetch requests while rendering a React component tree. -You can use `fetch` with [`async`/`await` in Server Components](https://github.com/acdlite/rfcs/blob/first-class-promises/text/0000-first-class-support-for-promises.md), in [Route Handlers](/docs/app/building-your-application/routing/route-handlers), and in [Server Actions](/docs/app/building-your-application/data-fetching/forms-and-mutations). +You can use `fetch` with `async`/`await` in Server Components, in [Route Handlers](/docs/app/building-your-application/routing/route-handlers), and in [Server Actions](/docs/app/building-your-application/data-fetching/forms-and-mutations). For example: @@ -117,7 +117,7 @@ Learn more about [time-based revalidation](/docs/app/building-your-application/c #### On-demand Revalidation -Data can be revalidated on-demand by path ([`revalidatePath`](/docs/app/api-reference/functions/revalidatePath)) or by cache tag ([`revalidateTag`](/docs/app/api-reference/functions/revalidateTag)) inside a Route Handler or a Server Action. +Data can be revalidated on-demand by path ([`revalidatePath`](/docs/app/api-reference/functions/revalidatePath)) or by cache tag ([`revalidateTag`](/docs/app/api-reference/functions/revalidateTag)) inside a [Server Action](/docs/app/building-your-application/data-fetching/forms-and-mutations) or [Route Handler](/docs/app/building-your-application/routing/route-handlers). Next.js has a cache tagging system for invalidating `fetch` requests across routes. @@ -142,89 +142,25 @@ export default async function Page() { } ``` -If using a Route Handler, you should create a secret token only known by your Next.js app. This secret will be used to prevent unauthorized revalidation attempts. For example, you can access the route (either manually or with a webhook) with the following URL structure: +You can then revalidate this `fetch` call tagged with `collection` by calling `revalidateTag` in a Server Action: -```bash filename="URL" -https:///api/revalidate?tag=collection&secret= -``` - -```ts filename="app/api/revalidate/route.ts" switcher -import { NextRequest } from 'next/server' -import { revalidateTag } from 'next/cache' - -// e.g a webhook to `your-website.com/api/revalidate?tag=collection&secret=` -export async function POST(request: NextRequest) { - const secret = request.nextUrl.searchParams.get('secret') - const tag = request.nextUrl.searchParams.get('tag') - - if (secret !== process.env.MY_SECRET_TOKEN) { - return Response.json({ message: 'Invalid secret' }, { status: 401 }) - } - - if (!tag) { - return Response.json({ message: 'Missing tag param' }, { status: 400 }) - } - - revalidateTag(tag) +```ts filename="app/actions.ts" switcher +'use server' - return Response.json({ revalidated: true, now: Date.now() }) -} -``` - -```js filename="app/api/revalidate/route.js" switcher import { revalidateTag } from 'next/cache' -// e.g a webhook to `your-website.com/api/revalidate?tag=collection&secret=` -export async function POST(request) { - const secret = request.nextUrl.searchParams.get('secret') - const tag = request.nextUrl.searchParams.get('tag') - - if (secret !== process.env.MY_SECRET_TOKEN) { - return Response.json({ message: 'Invalid secret' }, { status: 401 }) - } - - if (!tag) { - return Response.json({ message: 'Missing tag param' }, { status: 400 }) - } - - revalidateTag(tag) - - return Response.json({ revalidated: true, now: Date.now() }) +export default async function action() { + revalidateTag('collection') } ``` -Alternatively, you can use [`revalidatePath`](/docs/app/api-reference/functions/revalidatePath) to revalidate all data associated with a path. +```js filename="app/actions.js" switcher +'use server' -```ts filename="app/api/revalidate/route.ts" switcher -import { NextRequest } from 'next/server' -import { revalidatePath } from 'next/cache' - -export async function POST(request: NextRequest) { - const path = request.nextUrl.searchParams.get('path') - - if (!path) { - return Response.json({ message: 'Missing path param' }, { status: 400 }) - } - - revalidatePath(path) - - return Response.json({ revalidated: true, now: Date.now() }) -} -``` - -```js filename="app/api/revalidate/route.js" switcher -import { revalidatePath } from 'next/cache' - -export async function POST(request) { - const path = request.nextUrl.searchParams.get('path') - - if (!path) { - return Response.json({ message: 'Missing path param' }, { status: 400 }) - } - - revalidatePath(path) +import { revalidateTag } from 'next/cache' - return Response.json({ revalidated: true, now: Date.now() }) +export default async function action() { + revalidateTag('collection') } ``` @@ -260,14 +196,7 @@ View all the available `cache` options in the [`fetch` API reference](/docs/app/ If you have multiple `fetch` requests in a route segment (e.g. a Layout or Page), you can configure the caching behavior of all data requests in the segment using the [Segment Config Options](/docs/app/api-reference/file-conventions/route-segment-config). -For example, using `const dynamic = 'force-dynamic'` will cause all data to be fetched at request time, and the segment to be rendered dynamically. - -```js filename="layout.js | page.js" -// Add -export const dynamic = 'force-dynamic' -``` - -There's an extensive list of Segment Config options, giving you fine-grained control of static and dynamic behavior of a route segment. See the [API reference](/docs/app/api-reference/file-conventions/route-segment-config) for more. +However, we recommend configuring the caching behavior of each `fetch` request individually. This gives you more granular control over the caching behavior. ## Fetching data on the Server with third-party libraries @@ -275,9 +204,7 @@ In cases where you're using a third-party library that doesn't support or expose Whether the data is cached or not will depend on whether the route segment is [statically or dynamically rendered](/docs/app/building-your-application/rendering/server-components#server-rendering-strategies). If the segment is static (default), the output of the request will be cached and revalidated as part of the route 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:** -> -> Next.js is working on an API, `unstable_cache`, for configuring the caching and revalidating behavior of individual third-party requests. +You can also use the experimental [`unstable_cache` API](/docs/app/api-reference/functions/unstable_cache). ### Example @@ -370,4 +297,4 @@ You can also fetch data on the client using a third-party library such as [SWR]( > **Future APIs**: > -> `use` is a React function that **accepts and handles a promise** returned by a function. Wrapping `fetch` in `use` is currently **not** recommended in Client Components and may trigger multiple re-renders. Learn more about `use` in the [React RFC](https://github.com/acdlite/rfcs/blob/first-class-promises/text/0000-first-class-support-for-promises.md#usepromise). +> `use` is a React function that **accepts and handles a promise** returned by a function. Wrapping `fetch` in `use` is currently **not** recommended in Client Components and may trigger multiple re-renders. Learn more about `use` in the [React docs](https://react.dev/reference/react/use). diff --git a/docs/02-app/01-building-your-application/02-data-fetching/03-forms-and-mutations.mdx b/docs/02-app/01-building-your-application/02-data-fetching/03-forms-and-mutations.mdx index 70342516b8e46..0eb66f1ed808e 100644 --- a/docs/02-app/01-building-your-application/02-data-fetching/03-forms-and-mutations.mdx +++ b/docs/02-app/01-building-your-application/02-data-fetching/03-forms-and-mutations.mdx @@ -360,7 +360,7 @@ export default async function submit(formData) { -Use the `useFormStatus` hook to show a loading state when a form is submitting on the server. The `useFormStatus` hook can only be used as a child of a `form` element using a Server Action. +Use the [`useFormStatus`](https://react.dev/reference/react-dom/hooks/useFormStatus) hook to show a loading state when a form is submitting on the server. The `useFormStatus` hook can only be used as a child of a `form` element using a Server Action. For example, the following submit button: @@ -731,7 +731,7 @@ Use `useOptimistic` to optimistically update the UI before the Server Action fin ```tsx filename="app/page.tsx" switcher 'use client' -import { experimental_useOptimistic as useOptimistic } from 'react' +import { useOptimistic } from 'react' import { send } from './actions' type Message = { @@ -770,7 +770,7 @@ export function Thread({ messages }: { messages: Message[] }) { ```jsx filename="app/page.jsx" switcher 'use client' -import { experimental_useOptimistic as useOptimistic } from 'react' +import { useOptimistic } from 'react' import { send } from './actions' export function Thread({ messages }) { diff --git a/docs/02-app/01-building-your-application/03-rendering/02-client-components.mdx b/docs/02-app/01-building-your-application/03-rendering/02-client-components.mdx index e8bda53d3710a..01b8bd1a8b643 100644 --- a/docs/02-app/01-building-your-application/03-rendering/02-client-components.mdx +++ b/docs/02-app/01-building-your-application/03-rendering/02-client-components.mdx @@ -103,4 +103,4 @@ This means the Client Component JavaScript bundle is downloaded and parsed. Once Sometimes, after you've declared the `"use client"` boundary, you may want to go back to the server environment. For example, you may want to reduce the client bundle size, fetch data on the server, or use an API that is only available on the server. -You can keep code on the server even though it's theoretically nested inside Client Components by interleaving Client and Server Components and Server Actions. See the [Composition Patterns](/docs/app/building-your-application/rendering/composition-patterns) page for more information. +You can keep code on the server even though it's theoretically nested inside Client Components by interleaving Client and Server Components and [Server Actions](/docs/app/building-your-application/data-fetching/forms-and-mutations). See the [Composition Patterns](/docs/app/building-your-application/rendering/composition-patterns) page for more information. diff --git a/docs/02-app/01-building-your-application/04-caching/index.mdx b/docs/02-app/01-building-your-application/04-caching/index.mdx index d412102ede002..15d50683b4171 100644 --- a/docs/02-app/01-building-your-application/04-caching/index.mdx +++ b/docs/02-app/01-building-your-application/04-caching/index.mdx @@ -417,7 +417,7 @@ The following table provides an overview of how different Next.js APIs affect ca | [`headers`, `useSearchParams`, `searchParams`](#dynamic-functions) | | Opt out | | | | [`generateStaticParams`](#generatestaticparams) | | Cache | | | | [`React.cache`](#react-cache-function) | | | | Cache | -| [`unstable_cache`](#unstable_cache) (Coming Soon) | | | | | +| [`unstable_cache`](/docs/app/api-reference/functions/unstable_cache) | | | | | ### `` @@ -480,7 +480,7 @@ See the [`fetch` API reference](/docs/app/api-reference/functions/fetch) for mor Next.js has a cache tagging system for fine-grained data caching and revalidation. -1. When using `fetch` or `unstable_cache`, you have the option to tag cache entries with one or more tags. +1. When using `fetch` or [`unstable_cache`](/docs/app/api-reference/functions/unstable_cache), you have the option to tag cache entries with one or more tags. 2. Then, you can call `revalidateTag` to purge the cache entries associated with that tag. For example, you can set a tag when fetching data: @@ -577,27 +577,3 @@ export const getItem = cache(async (id) => { return item }) ``` - -### `unstable_cache` - -`unstable_cache` is an experimental API for adding values to the Data Cache when the `fetch` API is not suitable. For example, when using database clients, CMS clients, or GraphQL. - -```jsx -import { unstable_cache } from 'next/cache' - -export default async function Page() { - const cachedData = await unstable_cache( - async () => { - const data = await db.query('...') - return data - }, - ['cache-key'], - { - tags: ['a', 'b', 'c'], - revalidate: 10, - } - )() -} -``` - -> **Warning**: This API is being developed, and we do not recommend using it in production. It's listed here to show the future direction of the Data Cache. diff --git a/docs/02-app/01-building-your-application/06-optimizing/04-metadata.mdx b/docs/02-app/01-building-your-application/06-optimizing/04-metadata.mdx index 7a38cd5e2c652..d06aa0a194ace 100644 --- a/docs/02-app/01-building-your-application/06-optimizing/04-metadata.mdx +++ b/docs/02-app/01-building-your-application/06-optimizing/04-metadata.mdx @@ -6,6 +6,7 @@ related: links: - app/api-reference/functions/generate-metadata - app/api-reference/file-conventions/metadata + - app/api-reference/functions/generate-viewport --- Next.js has a Metadata API that can be used to define your application metadata (e.g. `meta` and `link` tags inside your HTML `head` element) for improved SEO and web shareability. diff --git a/docs/02-app/01-building-your-application/06-optimizing/index.mdx b/docs/02-app/01-building-your-application/06-optimizing/index.mdx index 526cc4ce9f028..61f98715e1468 100644 --- a/docs/02-app/01-building-your-application/06-optimizing/index.mdx +++ b/docs/02-app/01-building-your-application/06-optimizing/index.mdx @@ -24,7 +24,7 @@ Metadata helps search engines understand your content better (which can result i The Metadata API in Next.js allows you to modify the `` element of a page. You can configure metadata in two ways: -- **Config-based Metadata**: Export a static metadata object or a dynamic generateMetadata function in a `layout.js` or `page.js` file. +- **Config-based Metadata**: Export a [static `metadata` object](/docs/app/api-reference/functions/generate-metadata#metadata-object) or a dynamic [`generateMetadata` function](/docs/app/api-reference/functions/generate-metadata#generatemetadata-function) in a `layout.js` or `page.js` file. - **File-based Metadata**: Add static or dynamically generated special files to route segments. Additionally, you can create dynamic Open Graph Images using JSX and CSS with [imageResponse](/docs/app/api-reference/functions/image-response) constructor. diff --git a/docs/02-app/01-building-your-application/08-deploying/01-static-exports.mdx b/docs/02-app/01-building-your-application/08-deploying/01-static-exports.mdx index f5feb939c1ab8..b610f6c212002 100644 --- a/docs/02-app/01-building-your-application/08-deploying/01-static-exports.mdx +++ b/docs/02-app/01-building-your-application/08-deploying/01-static-exports.mdx @@ -323,7 +323,7 @@ export const dynamic = 'error' With a static export, Next.js can be deployed and hosted on any web server that can serve HTML/CSS/JS static assets. -When running `next build`, Next.js generates the static export into the `out` folder. Using `next export` is no longer needed. For example, let's say you have the following routes: +When running `next build`, Next.js generates the static export into the `out` folder. For example, let's say you have the following routes: - `/` - `/blog/[id]` @@ -365,5 +365,6 @@ server { | Version | Changes | | --------- | -------------------------------------------------------------------------------------------------------------------- | +| `v14.0.0` | `next export` has been removed in favor of `"output": "export"` | | `v13.4.0` | App Router (Stable) adds enhanced static export support, including using React Server Components and Route Handlers. | | `v13.3.0` | `next export` is deprecated and replaced with `"output": "export"` | diff --git a/docs/02-app/01-building-your-application/09-upgrading/01-codemods.mdx b/docs/02-app/01-building-your-application/09-upgrading/01-codemods.mdx index 9dd7ad70de551..61b01bde01936 100644 --- a/docs/02-app/01-building-your-application/09-upgrading/01-codemods.mdx +++ b/docs/02-app/01-building-your-application/09-upgrading/01-codemods.mdx @@ -34,7 +34,7 @@ Replacing `` and `` with appropriate values. npx @next/codemod@latest next-og-import. ``` -This codemo migrates the import path of `ImageResponse` from `'next/server'` to `'next/og'` +This codemod moves transforms imports from `next/server` to `next/og` for usage of [Dynamic OG Image Generation](/docs/app/building-your-application/optimizing/metadata#dynamic-image-generation). For example: @@ -42,7 +42,7 @@ For example: import { ImageResponse } from 'next/server' ``` -Transform into: +Transforms into: ```js import { ImageResponse } from 'next/og' diff --git a/docs/02-app/01-building-your-application/09-upgrading/02-app-router-migration.mdx b/docs/02-app/01-building-your-application/09-upgrading/02-app-router-migration.mdx index 25be180f86e6b..de7aa63612f72 100644 --- a/docs/02-app/01-building-your-application/09-upgrading/02-app-router-migration.mdx +++ b/docs/02-app/01-building-your-application/09-upgrading/02-app-router-migration.mdx @@ -14,7 +14,7 @@ This guide will help you: ### Node.js Version -The minimum Node.js version is now **v16.14**. See the [Node.js documentation](https://nodejs.org/docs/latest-v16.x/api/) for more information. +The minimum Node.js version is now **v18.17**. See the [Node.js documentation](https://nodejs.org/docs/latest-v18.x/api/) for more information. ### Next.js Version diff --git a/docs/02-app/02-api-reference/02-file-conventions/01-metadata/app-icons.mdx b/docs/02-app/02-api-reference/02-file-conventions/01-metadata/app-icons.mdx index 21c92ecb046ab..b55321180cc8e 100644 --- a/docs/02-app/02-api-reference/02-file-conventions/01-metadata/app-icons.mdx +++ b/docs/02-app/02-api-reference/02-file-conventions/01-metadata/app-icons.mdx @@ -124,7 +124,7 @@ export default function Icon() { ``` ```jsx filename="app/icon.js" switcher -import { ImageResponse } from 'next/server' +import { ImageResponse } from 'next/og' // Route segment config export const runtime = 'edge' diff --git a/docs/02-app/02-api-reference/02-file-conventions/01-metadata/opengraph-image.mdx b/docs/02-app/02-api-reference/02-file-conventions/01-metadata/opengraph-image.mdx index 8b07aff325265..40fd8e2e0922a 100644 --- a/docs/02-app/02-api-reference/02-file-conventions/01-metadata/opengraph-image.mdx +++ b/docs/02-app/02-api-reference/02-file-conventions/01-metadata/opengraph-image.mdx @@ -147,7 +147,7 @@ export default async function Image() { ``` ```jsx filename="app/about/opengraph-image.js" switcher -import { ImageResponse } from 'next/server' +import { ImageResponse } from 'next/og' // Route segment config export const runtime = 'edge' diff --git a/docs/02-app/02-api-reference/04-functions/generate-metadata.mdx b/docs/02-app/02-api-reference/04-functions/generate-metadata.mdx index 28d45bb844230..00d5aab0e7dc0 100644 --- a/docs/02-app/02-api-reference/04-functions/generate-metadata.mdx +++ b/docs/02-app/02-api-reference/04-functions/generate-metadata.mdx @@ -7,6 +7,7 @@ related: description: View all the Metadata API options. links: - app/api-reference/file-conventions/metadata + - app/api-reference/functions/generate-viewport - app/building-your-application/optimizing/metadata --- @@ -361,7 +362,6 @@ export const metadata = { referrer: 'origin-when-cross-origin', keywords: ['Next.js', 'React', 'JavaScript'], authors: [{ name: 'Seb' }, { name: 'Josh', url: 'https://nextjs.org' }], - colorScheme: 'dark', creator: 'Jiachi Liu', publisher: 'Sebastian Markbåge', formatDetection: { @@ -635,35 +635,7 @@ export const metadata = { ### `themeColor` -Learn more about [theme-color](https://developer.mozilla.org/docs/Web/HTML/Element/meta/name/theme-color). - -**Simple theme color** - -```jsx filename="layout.js | page.js" -export const metadata = { - themeColor: 'black', -} -``` - -```html filename=" output" hideLineNumbers - -``` - -**With media attribute** - -```jsx filename="layout.js | page.js" -export const metadata = { - themeColor: [ - { media: '(prefers-color-scheme: light)', color: 'cyan' }, - { media: '(prefers-color-scheme: dark)', color: 'black' }, - ], -} -``` - -```html filename=" output" hideLineNumbers - - -``` +> **Deprecated**: The `themeColor` option in `metadata` is deprecated as of Next.js 14. Please use the [`viewport` configuration](/docs/app/api-reference/functions/generate-viewport) instead. ### `manifest` @@ -757,24 +729,7 @@ export const metadata = { ### `viewport` -> **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 = { - viewport: { - width: 'device-width', - initialScale: 1, - maximumScale: 1, - }, -} -``` - -```html filename=" output" hideLineNumbers - -``` +> **Deprecated**: The `themeColor` option in `metadata` is deprecated as of Next.js 14. Please use the [`viewport` configuration](/docs/app/api-reference/functions/generate-viewport) instead. ### `verification` @@ -1154,6 +1109,7 @@ export const metadata = { ## Version History -| Version | Changes | -| --------- | --------------------------------------------- | -| `v13.2.0` | `metadata` and `generateMetadata` introduced. | +| Version | Changes | +| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `v13.2.0` | `viewport`, `themeColor`, and `colorScheme` deprecated in favor of the [`viewport` configuration](/docs/app/api-reference/functions/generate-viewport). | +| `v13.2.0` | `metadata` and `generateMetadata` introduced. | diff --git a/docs/02-app/02-api-reference/04-functions/generate-static-params.mdx b/docs/02-app/02-api-reference/04-functions/generate-static-params.mdx index ff20442f1bbba..1f0ee9c7c410c 100644 --- a/docs/02-app/02-api-reference/04-functions/generate-static-params.mdx +++ b/docs/02-app/02-api-reference/04-functions/generate-static-params.mdx @@ -299,7 +299,7 @@ export default function Page({ params }) { } ``` -> **Good to know**: `fetch` requests are automatically [memoized](/docs/app/building-your-application/caching#request-memoization) for the same data across `generateMetadata`, `generateStaticParams`, Layouts, Pages, and Server Components. React [`cache` can be used](/docs/app/building-your-application/caching#request-memoization) if `fetch` is unavailable. +> **Good to know**: `fetch` requests are automatically [memoized](/docs/app/building-your-application/caching#request-memoization) for the same data across all `generate`-prefixed functions, Layouts, Pages, and Server Components. React [`cache` can be used](/docs/app/building-your-application/caching#request-memoization) if `fetch` is unavailable. ## Version History diff --git a/docs/02-app/02-api-reference/04-functions/generate-viewport.mdx b/docs/02-app/02-api-reference/04-functions/generate-viewport.mdx new file mode 100644 index 0000000000000..31594ee3d0482 --- /dev/null +++ b/docs/02-app/02-api-reference/04-functions/generate-viewport.mdx @@ -0,0 +1,197 @@ +--- +title: generateViewport +description: API Reference for the generateViewport function. +related: + title: Next Steps + description: View all the Metadata API options. + links: + - app/api-reference/file-conventions/metadata + - app/building-your-application/optimizing/metadata +--- + +You can customize the initial viewport of the page with the static `viewport` object or the dynamic `generateViewport` function. + +> **Good to know**: +> +> - The `viewport` object and `generateViewport` function exports are **only supported in Server Components**. +> - You cannot export both the `viewport` object and `generateViewport` function from the same route segment. + +## The `viewport` object + +To define the viewport options, export a `viewport` object from a `layout.js` or `page.js` file. + +```tsx filename="layout.tsx | page.tsx" switcher +import { Viewport } from 'next' + +export const viewport: Viewport = { + themeColor: 'black', +} + +export default function Page() {} +``` + +```jsx filename="layout.js | page.js" switcher +export const viewport = { + themeColor: 'black', +} + +export default function Page() {} +``` + +## `generateViewport` function + +`generateViewport` should return a [`Viewport` object](#viewport-fields) containing one or more viewport fields. + +```tsx filename="layout.tsx | page.tsx" switcher +export function generateViewport({ params }) { + return { + themeColor: '...', + } +} +``` + +```jsx filename="layout.js | page.js" switcher +export function generateViewport({ params }) { + return { + themeColor: '...', + } +} +``` + +> **Good to know**: +> +> - If the viewport doesn't depend on runtime information, it should be defined using the static [`viewport` object](#the-viewport-object) rather than `generateMetadata`. +> - Marking `generateViewport` as `async` is not yet supported. If you still require this functionality, continue using the previous `generateMetadata` option. We will be adding support for `async` in an upcoming minor release. + +## Viewport Fields + +### `themeColor` + +Learn more about [theme-color](https://developer.mozilla.org/docs/Web/HTML/Element/meta/name/theme-color). + +**Simple theme color** + +```jsx filename="layout.js | page.js" +export const viewport = { + themeColor: 'black', +} +``` + +```html filename=" output" hideLineNumbers + +``` + +**With media attribute** + +```jsx filename="layout.js | page.js" +export const viewport = { + themeColor: [ + { media: '(prefers-color-scheme: light)', color: 'cyan' }, + { media: '(prefers-color-scheme: dark)', color: 'black' }, + ], +} +``` + +```html filename=" output" hideLineNumbers + + +``` + +### `width`, `initialScale`, and `maximumScale` + +> **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 viewport = { + width: 'device-width', + initialScale: 1, + maximumScale: 1, + // Also supported by less commonly used + // interactiveWidget: 'resizes-visual', +} +``` + +```html filename=" output" hideLineNumbers + +``` + +### `colorScheme` + +Learn more about [`color-scheme`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name#:~:text=color%2Dscheme%3A%20specifies,of%20the%20following%3A). + +```jsx filename="layout.js | page.js" +export const viewport = { + colorScheme: 'dark', +} +``` + +```html filename=" output" hideLineNumbers + +``` + +## Types + +You can add type safety to your viewport object by using the `Viewport` type. If you are using the [built-in TypeScript plugin](/docs/app/building-your-application/configuring/typescript) in your IDE, you do not need to manually add the type, but you can still explicitly add it if you want. + +### `viewport` object + +```tsx +import type { Viewport } from 'next' + +export const viewport: Viewport = { + themeColor: 'black', +} +``` + +### `generateViewport` function + +#### Regular function + +```tsx +import type { Viewport } from 'next' + +export function generateViewport(): Viewport { + return { + themeColor: 'black', + } +} +``` + +#### With segment props + +```tsx +import type { Viewport } from 'next' + +type Props = { + params: { id: string } + searchParams: { [key: string]: string | string[] | undefined } +} + +export function generateViewport({ params, searchParams }: Props): Viewport { + return { + themeColor: 'black', + } +} + +export default function Page({ params, searchParams }: Props) {} +``` + +#### JavaScript Projects + +For JavaScript projects, you can use JSDoc to add type safety. + +```js +/** @type {import("next").Viewport} */ +export const viewport = { + themeColor: 'black', +} +``` + +## Version History + +| Version | Changes | +| --------- | --------------------------------------------- | +| `v14.0.0` | `viewport` and `generateViewport` introduced. | diff --git a/docs/02-app/02-api-reference/04-functions/revalidatePath.mdx b/docs/02-app/02-api-reference/04-functions/revalidatePath.mdx index a146f3b6397cb..a8425901f17ad 100644 --- a/docs/02-app/02-api-reference/04-functions/revalidatePath.mdx +++ b/docs/02-app/02-api-reference/04-functions/revalidatePath.mdx @@ -56,6 +56,16 @@ revalidatePath('/(main)/post/[slug]', 'layout') This will revalidate any URL that matches the provided `layout` file on the next page visit. This will cause pages beneath with the same layout to revalidate on the next visit. For example, in the above case, `/blog/[slug]/[another]` would also revalidate on the next visit. +### Revalidating All Data + +```ts +import { revalidatePath } from 'next/cache' + +revalidatePath('/', 'layout') +``` + +This will purge the Client-side Router Cache, and revalidate the Data Cache on the next page visit. + ### Server Action ```ts filename="app/actions.ts" switcher diff --git a/docs/02-app/02-api-reference/04-functions/server-actions.mdx b/docs/02-app/02-api-reference/04-functions/server-actions.mdx index a7a9aed1fdf04..c3fa95091b5df 100644 --- a/docs/02-app/02-api-reference/04-functions/server-actions.mdx +++ b/docs/02-app/02-api-reference/04-functions/server-actions.mdx @@ -159,8 +159,8 @@ module.exports = { The following React API pages are currently being documented: - [`"use server"`](https://react.dev/reference/react/use-server) +- [`useFormStatus`](https://react.dev/reference/react-dom/hooks/useFormStatus) - `action` (🚧) - `formAction` (🚧) -- `useFormStatus` (🚧) - `useFormState` (🚧) - `useOptimistic` (🚧) diff --git a/docs/02-app/02-api-reference/04-functions/unstable_cache.mdx b/docs/02-app/02-api-reference/04-functions/unstable_cache.mdx new file mode 100644 index 0000000000000..d618ddaad6412 --- /dev/null +++ b/docs/02-app/02-api-reference/04-functions/unstable_cache.mdx @@ -0,0 +1,39 @@ +--- +title: unstable_cache +description: API Reference for the unstable_cache function. +--- + +`unstable_cache` allows you to cache the results of expensive operations, like database queries, and reuse them across multiple requests. + +```jsx +import { getUser } from './data'; +import { unstable_cache } from 'next/cache'; + +const getCachedUser = unstable_cache( + async (id) => getUser(id), + ['my-app-user'] +); + +export default async function Component({ userID }) { + const user = await getCachedUser(userID); + ... +} +``` + +> **Warning**: This API is unstable and may change in the future. We will provide migration documentation and codemods, if needed, as this API stabilizes. + +## Parameters + +```jsx +const data = unstable_cache(fetchData, keyParts, options)() +``` + +- `fetchData`: This is an asynchronous function that fetches the data you want to cache. It must be a function that returns a `Promise`. +- `keyParts`: This is an array that identifies the cached key. It must contain globally unique values that together identify the key of the data being cached. The cache key also includes the arguments passed to the function. +- `options`: This is an object that controls how the cache behaves. It can contain the following properties: + - `tags`: An array of tags that can be used to control cache invalidation. + - `revalidate`: The number of seconds after which the cache should be revalidated. + +## Returns + +`unstable_cache` returns a function that when invoked, returns a Promise that resolves to the cached data. If the data is not in the cache, the provided function will be invoked, and its result will be cached and returned. diff --git a/docs/02-app/02-api-reference/04-functions/unstable_noStore.mdx b/docs/02-app/02-api-reference/04-functions/unstable_noStore.mdx new file mode 100644 index 0000000000000..3c484a43088a0 --- /dev/null +++ b/docs/02-app/02-api-reference/04-functions/unstable_noStore.mdx @@ -0,0 +1,43 @@ +--- +title: unstable_noStore +description: API Reference for the unstable_noStore function. +--- + +`unstable_noStore` can be used to declaratively opt out of static rendering and indicate a particular component should not be cached. + +```jsx +import { unstable_noStore as noStore } from 'next/cache'; + +export default async function Component() { + noStore(); + const result = await db.query(...); + ... +} +``` + +> **Good to know**: +> +> - `unstable_noStore` is equivalent to `cache: 'no-store'` on a `fetch` +> - `unstable_noStore` is preferred over `export const dynamic = 'force-dynamic'` as it is more granular and can be used on a per-component basis + +- Using `unstable_noStore` inside [`unstable_cache`](/docs/app/api-reference/functions/unstable_cache) will not opt out of static generation. Instead, it will defer to the cache configuration to determine whether to cache the result or not. + +## Usage + +If you prefer not to pass additional options to `fetch`, like `cache: 'no-store'` or `next: { revalidate: 0 }`, you can use `noStore()` as a replacement for all of these use cases. + +```jsx +import { unstable_noStore as noStore } from 'next/cache'; + +export default async function Component() { + noStore(); + const result = await db.query(...); + ... +} +``` + +## Version History + +| Version | Changes | +| --------- | ------------------------------ | +| `v14.0.0` | `unstable_noStore` introduced. | diff --git a/docs/02-app/02-api-reference/05-next-config-js/logging.mdx b/docs/02-app/02-api-reference/05-next-config-js/logging.mdx new file mode 100644 index 0000000000000..1bed8d5398743 --- /dev/null +++ b/docs/02-app/02-api-reference/05-next-config-js/logging.mdx @@ -0,0 +1,20 @@ +--- +title: logging +description: Configure how data fetches are logged to the console when running Next.js in development mode. +--- + +{/* The content of this doc is shared between the app and pages router. You can use the `Content` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */} + +You can configure the logging level and whether the full URL is logged to the console when running Next.js in development mode. + +Currently, `logging` only applies to data fetching using the `fetch` API. It does not yet apply to other logs inside of Next.js. + +```js filename="next.config.js" +module.exports = { + logging: { + fetches: { + fullUrl: true, + }, + }, +} +``` diff --git a/docs/03-pages/01-building-your-application/08-upgrading/03-version-14.mdx b/docs/03-pages/01-building-your-application/08-upgrading/03-version-14.mdx new file mode 100644 index 0000000000000..1b43956e8446e --- /dev/null +++ b/docs/03-pages/01-building-your-application/08-upgrading/03-version-14.mdx @@ -0,0 +1,34 @@ +--- +title: Version 14 +description: Upgrade your Next.js Application from Version 13 to 14. +--- + +## Upgrading from 13 to 14 + +To update to Next.js version 13, run the following command using your preferred package manager: + +```bash filename="Terminal" +npm i next@latest react@latest react-dom@latest eslint-config-next@latest +``` + +```bash filename="Terminal" +yarn add next@latest react@latest react-dom@latest eslint-config-next@latest +``` + +```bash filename="Terminal" +pnpm up next react react-dom eslint-config-next --latest +``` + +```bash filename="Terminal" +bun add next@latest react@latest react-dom@latest eslint-config-next@latest +``` + +> **Good to know:** If you are using TypeScript, ensure you also upgrade `@types/react` and `@types/react-dom` to their latest versions. + +### v14 Summary + +- The minimum Node.js version has been bumped from 16.14 to 18.17, since 16.x has reached end-of-life. +- The `next export` command is deprecated in favor of `output: 'export'`. Please see the [docs](https://nextjs.org/docs/app/building-your-application/deploying/static-exports) for more information. +- The `next/server` import for `ImageResponse` was renamed to `next/og`. A [codemod is available](/docs/app/building-your-application/upgrading/codemods#next-og-import) to safely and automatically rename your imports. +- The `@next/font` package has been fully removed in favor of the built-in `next/font`. A [codemod is available](/docs/app/building-your-application/upgrading/codemods#built-in-next-font) to safely and automatically rename your imports. +- The WASM target for `next-swc` has been removed. diff --git a/docs/03-pages/01-building-your-application/08-upgrading/03-version-13.mdx b/docs/03-pages/01-building-your-application/08-upgrading/04-version-13.mdx similarity index 95% rename from docs/03-pages/01-building-your-application/08-upgrading/03-version-13.mdx rename to docs/03-pages/01-building-your-application/08-upgrading/04-version-13.mdx index d630794851c45..a0ecf42876019 100644 --- a/docs/03-pages/01-building-your-application/08-upgrading/03-version-13.mdx +++ b/docs/03-pages/01-building-your-application/08-upgrading/04-version-13.mdx @@ -9,14 +9,22 @@ To update to Next.js version 13, run the following command using your preferred ```bash filename="Terminal" npm i next@latest react@latest react-dom@latest eslint-config-next@latest -# or +``` + +```bash filename="Terminal" yarn add next@latest react@latest react-dom@latest eslint-config-next@latest -# or +``` + +```bash filename="Terminal" pnpm up next react react-dom eslint-config-next --latest -# or +``` + +```bash filename="Terminal" bun add next@latest react@latest react-dom@latest eslint-config-next@latest ``` +> **Good to know:** If you are using TypeScript, ensure you also upgrade `@types/react` and `@types/react-dom` to their latest versions. + ### v13 Summary - The [Supported Browsers](/docs/architecture/supported-browsers) have been changed to drop Internet Explorer and target modern browsers. diff --git a/docs/03-pages/01-building-your-application/08-upgrading/04-version-12.mdx b/docs/03-pages/01-building-your-application/08-upgrading/05-version-12.mdx similarity index 93% rename from docs/03-pages/01-building-your-application/08-upgrading/04-version-12.mdx rename to docs/03-pages/01-building-your-application/08-upgrading/05-version-12.mdx index 6d105a9b6b769..a420faaca6d68 100644 --- a/docs/03-pages/01-building-your-application/08-upgrading/04-version-12.mdx +++ b/docs/03-pages/01-building-your-application/08-upgrading/05-version-12.mdx @@ -6,15 +6,23 @@ description: Upgrade your Next.js Application from Version 11 to Version 12. To upgrade to version 12, run the following command: ```bash filename="Terminal" -npm install next@12 +npm i next@12 react@17 react-dom@17 eslint-config-next@12 +``` -yarn add next@12 +```bash filename="Terminal" +yarn add next@12 react@17 react-dom@17 eslint-config-next@12 +``` -pnpm update next@12 +```bash filename="Terminal" +pnpm up next@12 react@17 react-dom@17 eslint-config-next@12 +``` -bun add next@12 +```bash filename="Terminal" +bun add next@12 react@17 react-dom@17 eslint-config-next@12 ``` +> **Good to know:** If you are using TypeScript, ensure you also upgrade `@types/react` and `@types/react-dom` to their corresponding versions. + ### Upgrading to 12.2 [Middleware](/docs/messages/middleware-upgrade-guide) - If you were using Middleware prior to `12.2`, please see the [upgrade guide](/docs/messages/middleware-upgrade-guide) for more information. diff --git a/docs/03-pages/01-building-your-application/08-upgrading/06-version-10.mdx b/docs/03-pages/01-building-your-application/08-upgrading/06-version-10.mdx deleted file mode 100644 index 2b13179c81ba2..0000000000000 --- a/docs/03-pages/01-building-your-application/08-upgrading/06-version-10.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Version 10 -description: Upgrade your Next.js Application from Version 9 to Version 10. ---- - -There were no breaking changes between versions 9 and 10. - -To upgrade to version 10, run the following command: - -```bash filename="Terminal" -npm install next@10 - -yarn add next@10 -``` diff --git a/docs/03-pages/01-building-your-application/08-upgrading/05-version-11.mdx b/docs/03-pages/01-building-your-application/08-upgrading/06-version-11.mdx similarity index 93% rename from docs/03-pages/01-building-your-application/08-upgrading/05-version-11.mdx rename to docs/03-pages/01-building-your-application/08-upgrading/06-version-11.mdx index 56c28242de685..59f6cfaadc0f5 100644 --- a/docs/03-pages/01-building-your-application/08-upgrading/05-version-11.mdx +++ b/docs/03-pages/01-building-your-application/08-upgrading/06-version-11.mdx @@ -6,11 +6,23 @@ description: Upgrade your Next.js Application from Version 10 to Version 11. To upgrade to version 11, run the following command: ```bash filename="Terminal" -npm install next@11 +npm i next@11 react@17 react-dom@17 +``` -yarn add next@11 +```bash filename="Terminal" +yarn add next@11 react@17 react-dom@17 +``` + +```bash filename="Terminal" +pnpm up next@11 react@17 react-dom@17 ``` +```bash filename="Terminal" +bun add next@11 react@17 react-dom@17 +``` + +> **Good to know:** If you are using TypeScript, ensure you also upgrade `@types/react` and `@types/react-dom` to their corresponding versions. + ### Webpack 5 Webpack 5 is now the default for all Next.js applications. If you did not have a custom webpack configuration, your application is already using webpack 5. If you do have a custom webpack configuration, you can refer to the [Next.js webpack 5 documentation](/docs/messages/webpack5) for upgrade guidance. diff --git a/docs/03-pages/01-building-your-application/08-upgrading/07-version-10.mdx b/docs/03-pages/01-building-your-application/08-upgrading/07-version-10.mdx new file mode 100644 index 0000000000000..4726722345254 --- /dev/null +++ b/docs/03-pages/01-building-your-application/08-upgrading/07-version-10.mdx @@ -0,0 +1,26 @@ +--- +title: Version 10 +description: Upgrade your Next.js Application from Version 9 to Version 10. +--- + +There were no breaking changes between versions 9 and 10. + +To upgrade to version 10, run the following command: + +```bash filename="Terminal" +npm i next@10 +``` + +```bash filename="Terminal" +yarn add next@10 +``` + +```bash filename="Terminal" +pnpm up next@10 +``` + +```bash filename="Terminal" +bun add next@10 +``` + +> **Good to know:** If you are using TypeScript, ensure you also upgrade `@types/react` and `@types/react-dom` to their corresponding versions. diff --git a/docs/03-pages/01-building-your-application/08-upgrading/07-version-9.mdx b/docs/03-pages/01-building-your-application/08-upgrading/08-version-9.mdx similarity index 95% rename from docs/03-pages/01-building-your-application/08-upgrading/07-version-9.mdx rename to docs/03-pages/01-building-your-application/08-upgrading/08-version-9.mdx index fc386a5a0d4d8..5b240059fef0e 100644 --- a/docs/03-pages/01-building-your-application/08-upgrading/07-version-9.mdx +++ b/docs/03-pages/01-building-your-application/08-upgrading/08-version-9.mdx @@ -7,11 +7,23 @@ description: Upgrade your Next.js Application from Version 8 to Version 9. To upgrade to version 9, run the following command: ```bash filename="Terminal" -npm install next@9 +npm i next@9 +``` +```bash filename="Terminal" yarn add next@9 ``` +```bash filename="Terminal" +pnpm up next@9 +``` + +```bash filename="Terminal" +bun add next@9 +``` + +> **Good to know:** If you are using TypeScript, ensure you also upgrade `@types/react` and `@types/react-dom` to their corresponding versions. + ## Production Deployment on Vercel If you previously configured `routes` in your `vercel.json` file for dynamic routes, these rules can be removed when leveraging Next.js 9's new [Dynamic Routing feature](/docs/pages/building-your-application/routing/dynamic-routes).