Unverified Commit 9c0a8ce7 authored by Ryo's avatar Ryo Committed by GitHub

Docs: Unify note formatting (#48417)

<!-- Thanks for opening a PR! Your contribution is much appreciated.
To make sure your PR is handled as smoothly as possible we request that
you follow the checklist sections below.
Choose the right checklist for the change(s) that you're making:

## For Contributors

### Improving Documentation or adding/fixing Examples

- The "examples guidelines" are followed from our contributing doc
https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md
- Make sure the linting passes by running `pnpm build && pnpm lint`. See
https://github.com/vercel/next.js/blob/canary/contributing/repository/linting.md

### Fixing a bug

- Related issues linked using `fixes #number`
- Tests added. See:
https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md

### Adding a feature

- Implements an existing feature request or RFC. Make sure the feature
request has been accepted for implementation before opening a PR. (A
discussion must be opened, see
https://github.com/vercel/next.js/discussions/new?category=ideas)
- Related issues/discussions are linked using `fixes #number`
- e2e tests added
(https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs
- Documentation added
- Telemetry added. In case of a feature if it's used or not.
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md



## For Maintainers

- Minimal description (aim for explaining to someone not on the team to
understand the PR)
- When linking to a Slack thread, you might want to share details of the
conclusion
- Link both the Linear (Fixes NEXT-xxx) and the GitHub issues
- Add review comments if necessary to explain to the reviewer the logic
behind a change

### What?

### Why?

### How?

Closes NEXT-
Fixes #

-->

closes #48416 

### What?

Standardize the "Note" format in the Next.js documentation for improved
consistency and readability.

### Why?

There are currently four different variations of "Note" formatting in
the documentation.
Standardizing to a single format will improve the overall experience for
users.

### How?

Update all instances of "Note" in the documentation to follow the most
common format, `**Note**:` (used in 27 files).
This will involve updating the following variations:

- `Note` (12 files)
- `Note:` (20 files)
- `**Note:**` (21 files)

---------
Co-authored-by: 's avatarSteven <steven@ceriously.com>
parent f078da3f
...@@ -37,4 +37,4 @@ After: ...@@ -37,4 +37,4 @@ After:
] ]
``` ```
Note: the manifest is checked automatically in the "lint" step in CI when opening a PR. > **Note**: The manifest is checked automatically in the "lint" step in CI when opening a PR.
...@@ -28,7 +28,7 @@ The cases where the query will be updated after hydration triggering another ren ...@@ -28,7 +28,7 @@ The cases where the query will be updated after hydration triggering another ren
To be able to distinguish if the query is fully updated and ready for use, you can leverage the `isReady` field on [`next/router`](/docs/api-reference/next/router.md#router-object). To be able to distinguish if the query is fully updated and ready for use, you can leverage the `isReady` field on [`next/router`](/docs/api-reference/next/router.md#router-object).
> **Note:** Parameters added with [dynamic routes](/docs/routing/dynamic-routes.md) to a page that's using [`getStaticProps`](/docs/basic-features/data-fetching/get-static-props.md) will always be available inside the `query` object. > **Note**: Parameters added with [dynamic routes](/docs/routing/dynamic-routes.md) to a page that's using [`getStaticProps`](/docs/basic-features/data-fetching/get-static-props.md) will always be available inside the `query` object.
`next build` will emit `.html` files for statically optimized pages. For example, the result for the page `pages/about.js` would be: `next build` will emit `.html` files for statically optimized pages. For example, the result for the page `pages/about.js` would be:
......
...@@ -50,7 +50,7 @@ Or add a `className` to the `body` tag: ...@@ -50,7 +50,7 @@ Or add a `className` to the `body` tag:
## Customizing `renderPage` ## Customizing `renderPage`
> **Note:** This is advanced and only needed for libraries like CSS-in-JS to support server-side rendering. This is not needed for built-in `styled-jsx` support. > **Note**: This is advanced and only needed for libraries like CSS-in-JS to support server-side rendering. This is not needed for built-in `styled-jsx` support.
For [React 18](/docs/advanced-features/react-18.md) support, we recommend avoiding customizing `getInitialProps` and `renderPage`, if possible. For [React 18](/docs/advanced-features/react-18.md) support, we recommend avoiding customizing `getInitialProps` and `renderPage`, if possible.
......
...@@ -14,7 +14,7 @@ description: Start a Next.js app programmatically using a custom server. ...@@ -14,7 +14,7 @@ description: Start a Next.js app programmatically using a custom server.
By default, Next.js includes its own server with `next start`. If you have an existing backend, you can still use it with Next.js (this is not a custom server). A custom Next.js server allows you to start a server 100% programmatically in order to use custom server patterns. Most of the time, you will not need this – but it's available for complete customization. By default, Next.js includes its own server with `next start`. If you have an existing backend, you can still use it with Next.js (this is not a custom server). A custom Next.js server allows you to start a server 100% programmatically in order to use custom server patterns. Most of the time, you will not need this – but it's available for complete customization.
> **Note:** A custom server **cannot** be deployed on [Vercel](https://vercel.com/solutions/nextjs). > **Note**: A custom server **cannot** be deployed on [Vercel](https://vercel.com/solutions/nextjs).
> Before deciding to use a custom server, please keep in mind that it should only be used when the integrated router of Next.js can't meet your app requirements. A custom server will remove important performance optimizations, like **serverless functions** and **[Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md).** > Before deciding to use a custom server, please keep in mind that it should only be used when the integrated router of Next.js can't meet your app requirements. A custom server will remove important performance optimizations, like **serverless functions** and **[Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md).**
......
...@@ -97,7 +97,7 @@ Windows users may run into an issue when using `NODE_OPTIONS='--inspect'` as tha ...@@ -97,7 +97,7 @@ Windows users may run into an issue when using `NODE_OPTIONS='--inspect'` as tha
`cross-env` will set the `NODE_OPTIONS` environment variable regardless of which platform you are on (including Mac, Linux, and Windows) and allow you to debug consistently across devices and operating systems. `cross-env` will set the `NODE_OPTIONS` environment variable regardless of which platform you are on (including Mac, Linux, and Windows) and allow you to debug consistently across devices and operating systems.
> **Note:** Ensure Windows Defender is disabled on your machine. This external service will check _every file read_, which has been reported to greatly increase Fast Refresh time with `next dev`. This is a known issue, not related to Next.js, but it does affect Next.js development. > **Note**: Ensure Windows Defender is disabled on your machine. This external service will check _every file read_, which has been reported to greatly increase Fast Refresh time with `next dev`. This is a known issue, not related to Next.js, but it does affect Next.js development.
## More information ## More information
......
...@@ -361,4 +361,4 @@ export async function getStaticProps({ locale }) { ...@@ -361,4 +361,4 @@ export async function getStaticProps({ locale }) {
- `locales`: 100 total locales - `locales`: 100 total locales
- `domains`: 100 total locale domain items - `domains`: 100 total locale domain items
> **Note:** These limits have been added initially to prevent potential [performance issues at build time](#dynamic-routes-and-getStaticProps-pages). You can workaround these limits with custom routing using [Middleware](/docs/middleware.md) in Next.js 12. > **Note**: These limits have been added initially to prevent potential [performance issues at build time](#dynamic-routes-and-getStaticProps-pages). You can workaround these limits with custom routing using [Middleware](/docs/middleware.md) in Next.js 12.
...@@ -21,7 +21,7 @@ Middleware allows you to run code before a request is completed, then based on t ...@@ -21,7 +21,7 @@ Middleware allows you to run code before a request is completed, then based on t
Middleware runs _before_ cached content, so you can personalize static files and pages. Common examples of Middleware would be authentication, A/B testing, localized pages, bot protection, and more. Regarding localized pages, you can start with [i18n routing](/docs/advanced-features/i18n-routing) and implement Middleware for more advanced use cases. Middleware runs _before_ cached content, so you can personalize static files and pages. Common examples of Middleware would be authentication, A/B testing, localized pages, bot protection, and more. Regarding localized pages, you can start with [i18n routing](/docs/advanced-features/i18n-routing) and implement Middleware for more advanced use cases.
> **Note:** If you were using Middleware prior to `12.2`, please see the [upgrade guide](https://nextjs.org/docs/messages/middleware-upgrade-guide). > **Note**: If you were using Middleware prior to `12.2`, please see the [upgrade guide](https://nextjs.org/docs/messages/middleware-upgrade-guide).
## Using Middleware ## Using Middleware
...@@ -105,7 +105,7 @@ export const config = { ...@@ -105,7 +105,7 @@ export const config = {
} }
``` ```
> **Note:** The `matcher` values need to be constants so they can be statically analyzed at build-time. Dynamic values such as variables will be ignored. > **Note**: The `matcher` values need to be constants so they can be statically analyzed at build-time. Dynamic values such as variables will be ignored.
Configured matchers: Configured matchers:
...@@ -116,7 +116,7 @@ Configured matchers: ...@@ -116,7 +116,7 @@ Configured matchers:
Read more details on [path-to-regexp](https://github.com/pillarjs/path-to-regexp#path-to-regexp-1) documentation. Read more details on [path-to-regexp](https://github.com/pillarjs/path-to-regexp#path-to-regexp-1) documentation.
> **Note:** For backward compatibility, Next.js always considers `/public` as `/public/index`. Therefore, a matcher of `/public/:path` will match. > **Note**: For backward compatibility, Next.js always considers `/public` as `/public/index`. Therefore, a matcher of `/public/:path` will match.
### Conditional Statements ### Conditional Statements
...@@ -221,7 +221,7 @@ export function middleware(request: NextRequest) { ...@@ -221,7 +221,7 @@ export function middleware(request: NextRequest) {
} }
``` ```
> **Note:** Avoid setting large headers as it might cause [431 Request Header Fields Too Large](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/431) error depending on your backend web server configuration. > **Note**: Avoid setting large headers as it might cause [431 Request Header Fields Too Large](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/431) error depending on your backend web server configuration.
## Producing a Response ## Producing a Response
......
...@@ -13,9 +13,9 @@ description: Configure module path aliases that allow you to remap certain impor ...@@ -13,9 +13,9 @@ description: Configure module path aliases that allow you to remap certain impor
Next.js automatically supports the `tsconfig.json` and `jsconfig.json` `"paths"` and `"baseUrl"` options since [Next.js 9.4](https://nextjs.org/blog/next-9-4). Next.js automatically supports the `tsconfig.json` and `jsconfig.json` `"paths"` and `"baseUrl"` options since [Next.js 9.4](https://nextjs.org/blog/next-9-4).
> Note: `jsconfig.json` can be used when you don't use TypeScript > **Note**: `jsconfig.json` can be used when you don't use TypeScript
> Note: you need to restart dev server to reflect modifications done in `tsconfig.json` / `jsconfig.json` > **Note**: you need to restart dev server to reflect modifications done in `tsconfig.json` / `jsconfig.json`
These options allow you to configure module aliases, for example a common pattern is aliasing certain directories to use absolute paths. These options allow you to configure module aliases, for example a common pattern is aliasing certain directories to use absolute paths.
......
...@@ -19,7 +19,7 @@ This documentation uses terms like _Span_, _Trace_ or _Exporter_ throughout this ...@@ -19,7 +19,7 @@ This documentation uses terms like _Span_, _Trace_ or _Exporter_ throughout this
Next.js supports OpenTelemetry instrumentation out of the box, which means that we already instrumented Next.js itself. Next.js supports OpenTelemetry instrumentation out of the box, which means that we already instrumented Next.js itself.
When you enable OpenTelemetry we will automatically wrap all your code like `getStaticProps` in _spans_ with helpful attributes. When you enable OpenTelemetry we will automatically wrap all your code like `getStaticProps` in _spans_ with helpful attributes.
> **Note:** We currently support OpenTelemetry bindings only in serverless functions. > **Note**: We currently support OpenTelemetry bindings only in serverless functions.
> We don't provide any for `edge` or client side code. > We don't provide any for `edge` or client side code.
## Getting Started ## Getting Started
......
...@@ -34,9 +34,9 @@ This will create a folder at `.next/standalone` which can then be deployed on it ...@@ -34,9 +34,9 @@ This will create a folder at `.next/standalone` which can then be deployed on it
Additionally, a minimal `server.js` file is also output which can be used instead of `next start`. This minimal server does not copy the `public` or `.next/static` folders by default as these should ideally be handled by a CDN instead, although these folders can be copied to the `standalone/public` and `standalone/.next/static` folders manually, after which `server.js` file will serve these automatically. Additionally, a minimal `server.js` file is also output which can be used instead of `next start`. This minimal server does not copy the `public` or `.next/static` folders by default as these should ideally be handled by a CDN instead, although these folders can be copied to the `standalone/public` and `standalone/.next/static` folders manually, after which `server.js` file will serve these automatically.
Note: `next.config.js` is read during `next build` and serialized into the `server.js` output file. If the legacy [`serverRuntimeConfig` or `publicRuntimeConfig` options](/docs/api-reference/next.config.js/runtime-configuration.md) are being used, the values will be specific to values at build time. > **Note**: `next.config.js` is read during `next build` and serialized into the `server.js` output file. If the legacy [`serverRuntimeConfig` or `publicRuntimeConfig` options](/docs/api-reference/next.config.js/runtime-configuration.md) are being used, the values will be specific to values at build time.
If your project uses [Image Optimization](/docs/basic-features/image-optimization.md) with the default `loader`, you must install `sharp` as a dependency: > **Note**: If your project uses [Image Optimization](/docs/basic-features/image-optimization.md) with the default `loader`, you must install `sharp` as a dependency:
```bash ```bash
npm i sharp npm i sharp
......
...@@ -243,7 +243,7 @@ export default function myApiRoute(req, res) { ...@@ -243,7 +243,7 @@ export default function myApiRoute(req, res) {
Both the bypass cookie value and the private key for encrypting the `previewData` change when `next build` is completed. Both the bypass cookie value and the private key for encrypting the `previewData` change when `next build` is completed.
This ensures that the bypass cookie can’t be guessed. This ensures that the bypass cookie can’t be guessed.
> **Note:** To test Preview Mode locally over HTTP your browser will need to allow third-party cookies and local storage access. > **Note**: To test Preview Mode locally over HTTP your browser will need to allow third-party cookies and local storage access.
## Learn more ## Learn more
......
...@@ -39,7 +39,7 @@ NODE_OPTIONS='-r esm' next ...@@ -39,7 +39,7 @@ NODE_OPTIONS='-r esm' next
NODE_OPTIONS='--inspect' next NODE_OPTIONS='--inspect' next
``` ```
> Note: Running `next` without a command is the same as running `next dev` > **Note**: Running `next` without a command is the same as running `next dev`
## Build ## Build
...@@ -82,7 +82,7 @@ Or using the `PORT` environment variable: ...@@ -82,7 +82,7 @@ Or using the `PORT` environment variable:
PORT=4000 npx next dev PORT=4000 npx next dev
``` ```
> Note: `PORT` cannot be set in `.env` as booting up the HTTP server happens before any other code is initialized. > **Note**: `PORT` cannot be set in `.env` as booting up the HTTP server happens before any other code is initialized.
You can also set the hostname to be different from the default of `0.0.0.0`, this can be useful for making the application available for other devices on the network. The default hostname can be changed with `-H`, like so: You can also set the hostname to be different from the default of `0.0.0.0`, this can be useful for making the application available for other devices on the network. The default hostname can be changed with `-H`, like so:
...@@ -106,9 +106,9 @@ Or using the `PORT` environment variable: ...@@ -106,9 +106,9 @@ Or using the `PORT` environment variable:
PORT=4000 npx next start PORT=4000 npx next start
``` ```
> Note: `PORT` cannot be set in `.env` as booting up the HTTP server happens before any other code is initialized. > **Note**: `PORT` cannot be set in `.env` as booting up the HTTP server happens before any other code is initialized.
> Note: `next start` cannot be used with `output: 'standalone'` or `output: 'export'`. > **Note**: `next start` cannot be used with `output: 'standalone'` or `output: 'export'`.
### Keep Alive Timeout ### Keep Alive Timeout
......
...@@ -126,7 +126,7 @@ If `fallback` is `true`, then the behavior of `getStaticProps` changes in the fo ...@@ -126,7 +126,7 @@ If `fallback` is `true`, then the behavior of `getStaticProps` changes in the fo
- When complete, the browser receives the `JSON` for the generated path. This will be used to automatically render the page with the required props. From the user’s perspective, the page will be swapped from the fallback page to the full page. - When complete, the browser receives the `JSON` for the generated path. This will be used to automatically render the page with the required props. From the user’s perspective, the page will be swapped from the fallback page to the full page.
- At the same time, Next.js adds this path to the list of pre-rendered pages. Subsequent requests to the same path will serve the generated page, like other pages pre-rendered at build time. - At the same time, Next.js adds this path to the list of pre-rendered pages. Subsequent requests to the same path will serve the generated page, like other pages pre-rendered at build time.
> **Note:** `fallback: true` is not supported when using [`output: 'export'`](/docs/advanced-features/static-html-export.md). > **Note**: `fallback: true` is not supported when using [`output: 'export'`](/docs/advanced-features/static-html-export.md).
#### When is `fallback: true` useful? #### When is `fallback: true` useful?
...@@ -153,7 +153,7 @@ If `fallback` is `'blocking'`, new paths not returned by `getStaticPaths` will w ...@@ -153,7 +153,7 @@ If `fallback` is `'blocking'`, new paths not returned by `getStaticPaths` will w
`fallback: 'blocking'` will not _update_ generated pages by default. To update generated pages, use [Incremental Static Regeneration](/docs/basic-features/data-fetching/incremental-static-regeneration.md) in conjunction with `fallback: 'blocking'`. `fallback: 'blocking'` will not _update_ generated pages by default. To update generated pages, use [Incremental Static Regeneration](/docs/basic-features/data-fetching/incremental-static-regeneration.md) in conjunction with `fallback: 'blocking'`.
> **Note:** `fallback: 'blocking'` is not supported when using [`output: 'export'`](/docs/advanced-features/static-html-export.md). > **Note**: `fallback: 'blocking'` is not supported when using [`output: 'export'`](/docs/advanced-features/static-html-export.md).
### Fallback pages ### Fallback pages
......
...@@ -23,7 +23,7 @@ module.exports = { ...@@ -23,7 +23,7 @@ module.exports = {
} }
``` ```
Note: this value must be set at build time and can not be changed without re-building as the value is inlined in the client-side bundles. > **Note**: This value must be set at build time and cannot be changed without re-building as the value is inlined in the client-side bundles.
## Links ## Links
......
...@@ -6,7 +6,7 @@ description: In development mode, pages include an indicator to let you know if ...@@ -6,7 +6,7 @@ description: In development mode, pages include an indicator to let you know if
When you edit your code, and Next.js is compiling the application, a compilation indicator appears in the bottom right corner of the page. When you edit your code, and Next.js is compiling the application, a compilation indicator appears in the bottom right corner of the page.
> **Note:** This indicator is only present in development mode and will not appear when building and running the app in production mode. > **Note**: This indicator is only present in development mode and will not appear when building and running the app in production mode.
In some cases this indicator can be misplaced on your page, for example, when conflicting with a chat launcher. To change its position, open `next.config.js` and set the `buildActivityPosition` in the `devIndicators` object to `bottom-right` (default), `bottom-left`, `top-right` or `top-left`: In some cases this indicator can be misplaced on your page, for example, when conflicting with a chat launcher. To change its position, open `next.config.js` and set the `buildActivityPosition` in the `devIndicators` object to `bottom-right` (default), `bottom-left`, `top-right` or `top-left`:
......
...@@ -4,7 +4,7 @@ description: Extend the default webpack config added by Next.js. ...@@ -4,7 +4,7 @@ description: Extend the default webpack config added by Next.js.
# Custom Webpack Config # Custom Webpack Config
> Note: changes to webpack config are not covered by semver so proceed at your own risk > **Note**: changes to webpack config are not covered by semver so proceed at your own risk
Before continuing to add custom webpack configuration to your application make sure Next.js doesn't already support your use-case: Before continuing to add custom webpack configuration to your application make sure Next.js doesn't already support your use-case:
......
...@@ -40,7 +40,7 @@ module.exports = { ...@@ -40,7 +40,7 @@ module.exports = {
} }
``` ```
> Note: the `query` field in `exportPathMap` cannot be used with [automatically statically optimized pages](/docs/advanced-features/automatic-static-optimization) or [`getStaticProps` pages](/docs/basic-features/data-fetching/get-static-props.md) as they are rendered to HTML files at build-time and additional query information cannot be provided during `next export`. > **Note**: the `query` field in `exportPathMap` cannot be used with [automatically statically optimized pages](/docs/advanced-features/automatic-static-optimization) or [`getStaticProps` pages](/docs/basic-features/data-fetching/get-static-props.md) as they are rendered to HTML files at build-time and additional query information cannot be provided during `next export`.
The pages will then be exported as HTML files, for example, `/about` will become `/about.html`. The pages will then be exported as HTML files, for example, `/about` will become `/about.html`.
......
...@@ -311,7 +311,7 @@ module.exports = { ...@@ -311,7 +311,7 @@ module.exports = {
} }
``` ```
In some rare cases, you might need to assign a custom status code for older HTTP Clients to properly redirect. In these cases, you can use the `statusCode` property instead of the `permanent` property, but not both. Note: to ensure IE11 compatibility a `Refresh` header is automatically added for the 308 status code. In some rare cases, you might need to assign a custom status code for older HTTP Clients to properly redirect. In these cases, you can use the `statusCode` property instead of the `permanent` property, but not both. To to ensure IE11 compatibility, a `Refresh` header is automatically added for the 308 status code.
## Other Redirects ## Other Redirects
......
...@@ -89,7 +89,7 @@ module.exports = { ...@@ -89,7 +89,7 @@ module.exports = {
} }
``` ```
Note: rewrites in `beforeFiles` do not check the filesystem/dynamic routes immediately after matching a source, they continue until all `beforeFiles` have been checked. > **Note**: rewrites in `beforeFiles` do not check the filesystem/dynamic routes immediately after matching a source, they continue until all `beforeFiles` have been checked.
The order Next.js routes are checked is: The order Next.js routes are checked is:
...@@ -150,7 +150,7 @@ module.exports = { ...@@ -150,7 +150,7 @@ module.exports = {
} }
``` ```
Note: for static pages from the [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md) or [prerendering](/docs/basic-features/data-fetching/get-static-props.md) params from rewrites will be parsed on the client after hydration and provided in the query. > **Note**: Static pages from [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md) or [prerendering](/docs/basic-features/data-fetching/get-static-props.md) params from rewrites will be parsed on the client after hydration and provided in the query.
## Path Matching ## Path Matching
......
...@@ -4,7 +4,7 @@ description: Add client and server runtime configuration to your Next.js app. ...@@ -4,7 +4,7 @@ description: Add client and server runtime configuration to your Next.js app.
# Runtime Configuration # Runtime Configuration
> Note: This feature is considered legacy and does not work with [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md), [Output File Tracing](/docs/advanced-features/output-file-tracing.md#automatically-copying-traced-files), or [React Server Components](/docs/advanced-features/react-18/server-components.md). Please use [environment variables](/docs/basic-features/environment-variables.md) instead in order to avoid initialization overhead. > **Note**: This feature is considered legacy and does not work with [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md), [Output File Tracing](/docs/advanced-features/output-file-tracing.md#automatically-copying-traced-files), or [React Server Components](/docs/advanced-features/react-18/server-components.md). Please use [environment variables](/docs/basic-features/environment-variables.md) instead in order to avoid initialization overhead.
To add runtime configuration to your app, open `next.config.js` and add the `publicRuntimeConfig` and `serverRuntimeConfig` configs: To add runtime configuration to your app, open `next.config.js` and add the `publicRuntimeConfig` and `serverRuntimeConfig` configs:
......
...@@ -4,7 +4,7 @@ description: Optimized pages include an indicator to let you know if it's being ...@@ -4,7 +4,7 @@ description: Optimized pages include an indicator to let you know if it's being
# Static Optimization Indicator # Static Optimization Indicator
> **Note:** This indicator was removed in Next.js version 10.0.1. We recommend upgrading to the latest version of Next.js. > **Note**: This indicator was removed in Next.js version 10.0.1. We recommend upgrading to the latest version of Next.js.
When a page qualifies for [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md) we show an indicator to let you know. When a page qualifies for [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md) we show an indicator to let you know.
......
...@@ -317,7 +317,7 @@ module.exports = { ...@@ -317,7 +317,7 @@ module.exports = {
} }
``` ```
> Note: The example above will ensure the `src` property of `next/image` must start with `https://example.com/account123/`. Any other protocol, hostname, port, or unmatched path will respond with 400 Bad Request. > **Note**: The example above will ensure the `src` property of `next/image` must start with `https://example.com/account123/`. Any other protocol, hostname, port, or unmatched path will respond with 400 Bad Request.
Below is another example of the `remotePatterns` property in the `next.config.js` file: Below is another example of the `remotePatterns` property in the `next.config.js` file:
...@@ -334,7 +334,7 @@ module.exports = { ...@@ -334,7 +334,7 @@ module.exports = {
} }
``` ```
> Note: The example above will ensure the `src` property of `next/image` must start with `https://img1.example.com` or `https://me.avatar.example.com` or any number of subdomains. Any other protocol or unmatched hostname will respond with 400 Bad Request. > **Note**: The example above will ensure the `src` property of `next/image` must start with `https://img1.example.com` or `https://me.avatar.example.com` or any number of subdomains. Any other protocol or unmatched hostname will respond with 400 Bad Request.
Wildcard patterns can be used for both `pathname` and `hostname` and have the following syntax: Wildcard patterns can be used for both `pathname` and `hostname` and have the following syntax:
...@@ -345,7 +345,7 @@ The `**` syntax does not work in the middle of the pattern. ...@@ -345,7 +345,7 @@ The `**` syntax does not work in the middle of the pattern.
### Domains ### Domains
> Note: We recommend using [`remotePatterns`](#remote-patterns) instead so you can restrict protocol and pathname. > **Note**: We recommend using [`remotePatterns`](#remote-patterns) instead so you can restrict protocol and pathname.
Similar to [`remotePatterns`](#remote-patterns), the `domains` configuration can be used to provide a list of allowed hostnames for external images. Similar to [`remotePatterns`](#remote-patterns), the `domains` configuration can be used to provide a list of allowed hostnames for external images.
...@@ -448,9 +448,9 @@ module.exports = { ...@@ -448,9 +448,9 @@ module.exports = {
} }
``` ```
> Note: AVIF generally takes 20% longer to encode but it compresses 20% smaller compared to WebP. This means that the first time an image is requested, it will typically be slower and then subsequent requests that are cached will be faster. > **Note**: AVIF generally takes 20% longer to encode but it compresses 20% smaller compared to WebP. This means that the first time an image is requested, it will typically be slower and then subsequent requests that are cached will be faster.
> Note: If you self-host with a Proxy/CDN in front of Next.js, you must configure the Proxy to forward the `Accept` header. > **Note**: If you self-host with a Proxy/CDN in front of Next.js, you must configure the Proxy to forward the `Accept` header.
## Caching Behavior ## Caching Behavior
......
...@@ -379,7 +379,7 @@ module.exports = { ...@@ -379,7 +379,7 @@ module.exports = {
} }
``` ```
> Note: The example above will ensure the `src` property of `next/legacy/image` must start with `https://example.com/account123/`. Any other protocol, hostname, port, or unmatched path will respond with 400 Bad Request. > **Note**: The example above will ensure the `src` property of `next/legacy/image` must start with `https://example.com/account123/`. Any other protocol, hostname, port, or unmatched path will respond with 400 Bad Request.
Below is another example of the `remotePatterns` property in the `next.config.js` file: Below is another example of the `remotePatterns` property in the `next.config.js` file:
...@@ -396,7 +396,7 @@ module.exports = { ...@@ -396,7 +396,7 @@ module.exports = {
} }
``` ```
> Note: The example above will ensure the `src` property of `next/legacy/image` must start with `https://img1.example.com` or `https://me.avatar.example.com` or any number of subdomains. Any other protocol or unmatched hostname will respond with 400 Bad Request. > **Note**: The example above will ensure the `src` property of `next/legacy/image` must start with `https://img1.example.com` or `https://me.avatar.example.com` or any number of subdomains. Any other protocol or unmatched hostname will respond with 400 Bad Request.
Wildcard patterns can be used for both `pathname` and `hostname` and have the following syntax: Wildcard patterns can be used for both `pathname` and `hostname` and have the following syntax:
...@@ -407,7 +407,7 @@ The `**` syntax does not work in the middle of the pattern. ...@@ -407,7 +407,7 @@ The `**` syntax does not work in the middle of the pattern.
### Domains ### Domains
> Note: We recommend using [`remotePatterns`](#remote-patterns) instead so you can restrict protocol and pathname. > **Note**: We recommend using [`remotePatterns`](#remote-patterns) instead so you can restrict protocol and pathname.
Similar to [`remotePatterns`](#remote-patterns), the `domains` configuration can be used to provide a list of allowed hostnames for external images. Similar to [`remotePatterns`](#remote-patterns), the `domains` configuration can be used to provide a list of allowed hostnames for external images.
...@@ -513,7 +513,7 @@ module.exports = { ...@@ -513,7 +513,7 @@ module.exports = {
} }
``` ```
> Note: AVIF generally takes 20% longer to encode but it compresses 20% smaller compared to WebP. This means that the first time an image is requested, it will typically be slower and then subsequent requests that are cached will be faster. > **Note**: AVIF generally takes 20% longer to encode but it compresses 20% smaller compared to WebP. This means that the first time an image is requested, it will typically be slower and then subsequent requests that are cached will be faster.
## Caching Behavior ## Caching Behavior
......
...@@ -49,7 +49,7 @@ export default Home ...@@ -49,7 +49,7 @@ export default Home
`Link` accepts the following props: `Link` accepts the following props:
- `href` - The path or URL to navigate to. This is the only required prop. It can also be an object, see [example here](/docs/api-reference/next/link.md#with-url-object) - `href` - The path or URL to navigate to. This is the only required prop. It can also be an object, see [example here](/docs/api-reference/next/link.md#with-url-object)
- `as` - Optional decorator for the path that will be shown in the browser URL bar. Before Next.js 9.5.3 this was used for dynamic routes, check our [previous docs](https://nextjs.org/docs/tag/v9.5.2/api-reference/next/link#dynamic-routes) to see how it worked. Note: when this path differs from the one provided in `href` the previous `href`/`as` behavior is used as shown in the [previous docs](https://nextjs.org/docs/tag/v9.5.2/api-reference/next/link#dynamic-routes). - `as` - Optional decorator for the path that will be shown in the browser URL bar. Before Next.js 9.5.3 this was used for dynamic routes, check our [previous docs](https://nextjs.org/docs/tag/v9.5.2/api-reference/next/link#dynamic-routes) to see how it worked. When this path differs from the one provided in `href` the previous `href`/`as` behavior is used as shown in the [previous docs](https://nextjs.org/docs/tag/v9.5.2/api-reference/next/link#dynamic-routes).
- [`legacyBehavior`](#if-the-child-is-a-tag) - Changes behavior so that child must be `<a>`. Defaults to `false`. - [`legacyBehavior`](#if-the-child-is-a-tag) - Changes behavior so that child must be `<a>`. Defaults to `false`.
- [`passHref`](#if-the-child-is-a-custom-component-that-wraps-an-a-tag) - Forces `Link` to send the `href` property to its child. Defaults to `false` - [`passHref`](#if-the-child-is-a-custom-component-that-wraps-an-a-tag) - Forces `Link` to send the `href` property to its child. Defaults to `false`
- `prefetch` - Prefetch the page in the background. Defaults to `true`. Any `<Link />` that is in the viewport (initially or through scroll) will be preloaded. Prefetch can be disabled by passing `prefetch={false}`. When `prefetch` is set to `false`, prefetching will still occur on hover. Pages using [Static Generation](/docs/basic-features/data-fetching/get-static-props.md) will preload `JSON` files with the data for faster page transitions. Prefetching is only enabled in production. - `prefetch` - Prefetch the page in the background. Defaults to `true`. Any `<Link />` that is in the viewport (initially or through scroll) will be preloaded. Prefetch can be disabled by passing `prefetch={false}`. When `prefetch` is set to `false`, prefetching will still occur on hover. Pages using [Static Generation](/docs/basic-features/data-fetching/get-static-props.md) will preload `JSON` files with the data for faster page transitions. Prefetching is only enabled in production.
...@@ -58,7 +58,7 @@ export default Home ...@@ -58,7 +58,7 @@ export default Home
- [`shallow`](/docs/routing/shallow-routing.md) - Update the path of the current page without rerunning [`getStaticProps`](/docs/basic-features/data-fetching/get-static-props.md), [`getServerSideProps`](/docs/basic-features/data-fetching/get-server-side-props.md) or [`getInitialProps`](/docs/api-reference/data-fetching/get-initial-props.md). Defaults to `false` - [`shallow`](/docs/routing/shallow-routing.md) - Update the path of the current page without rerunning [`getStaticProps`](/docs/basic-features/data-fetching/get-static-props.md), [`getServerSideProps`](/docs/basic-features/data-fetching/get-server-side-props.md) or [`getInitialProps`](/docs/api-reference/data-fetching/get-initial-props.md). Defaults to `false`
- `locale` - The active locale is automatically prepended. `locale` allows for providing a different locale. When `false` `href` has to include the locale as the default behavior is disabled. - `locale` - The active locale is automatically prepended. `locale` allows for providing a different locale. When `false` `href` has to include the locale as the default behavior is disabled.
Note, when `legacyBehavior` is not set to `true`, all [`anchor`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) tag properties can be passed to `next/link` as well such as, `className`, `onClick`, etc. > **Note**: when `legacyBehavior` is not set to `true`, all [`anchor`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) tag properties can be passed to `next/link` as well such as, `className`, `onClick`, etc.
## If the route has dynamic segments ## If the route has dynamic segments
...@@ -259,4 +259,4 @@ export default function Page() { ...@@ -259,4 +259,4 @@ export default function Page() {
} }
``` ```
> **Note:** If you're using [Dynamic Routes](/docs/routing/dynamic-routes), you'll need to adapt your `as` and `href` props. For example, if you have a Dynamic Route like `/dashboard/[user]` that you want to present differently via middleware, you would write: `<Link href={{ pathname: '/dashboard/authed/[user]', query: { user: username } }} as="/dashboard/[user]">Profile</Link>`. > **Note**: If you're using [Dynamic Routes](/docs/routing/dynamic-routes), you'll need to adapt your `as` and `href` props. For example, if you have a Dynamic Route like `/dashboard/[user]` that you want to present differently via middleware, you would write: `<Link href={{ pathname: '/dashboard/authed/[user]', query: { user: username } }} as="/dashboard/[user]">Profile</Link>`.
...@@ -73,7 +73,7 @@ router.push(url, as, options) ...@@ -73,7 +73,7 @@ router.push(url, as, options)
``` ```
- `url`: `UrlObject | String` - The URL to navigate to (see [Node.JS URL module documentation](https://nodejs.org/api/url.html#legacy-urlobject) for `UrlObject` properties). - `url`: `UrlObject | String` - The URL to navigate to (see [Node.JS URL module documentation](https://nodejs.org/api/url.html#legacy-urlobject) for `UrlObject` properties).
- `as`: `UrlObject | String` - Optional decorator for the path that will be shown in the browser URL bar. Before Next.js 9.5.3 this was used for dynamic routes, check our [previous docs](https://nextjs.org/docs/tag/v9.5.2/api-reference/next/link#dynamic-routes) to see how it worked. Note: when this path differs from the one provided in `href` the previous `href`/`as` behavior is used as shown in the [previous docs](https://nextjs.org/docs/tag/v9.5.2/api-reference/next/link#dynamic-routes) - `as`: `UrlObject | String` - Optional decorator for the path that will be shown in the browser URL bar. Before Next.js 9.5.3 this was used for dynamic routes, check our [previous docs](https://nextjs.org/docs/tag/v9.5.2/api-reference/next/link#dynamic-routes) to see how it worked. When this path differs from the one provided in `href` the previous `href`/`as` behavior is used as shown in the [previous docs](https://nextjs.org/docs/tag/v9.5.2/api-reference/next/link#dynamic-routes)
- `options` - Optional object with the following configuration options: - `options` - Optional object with the following configuration options:
- `scroll` - Optional boolean, controls scrolling to the top of the page after navigation. Defaults to `true` - `scroll` - Optional boolean, controls scrolling to the top of the page after navigation. Defaults to `true`
- [`shallow`](/docs/routing/shallow-routing.md): Update the path of the current page without rerunning [`getStaticProps`](/docs/basic-features/data-fetching/get-static-props.md), [`getServerSideProps`](/docs/basic-features/data-fetching/get-server-side-props.md) or [`getInitialProps`](/docs/api-reference/data-fetching/get-initial-props.md). Defaults to `false` - [`shallow`](/docs/routing/shallow-routing.md): Update the path of the current page without rerunning [`getStaticProps`](/docs/basic-features/data-fetching/get-static-props.md), [`getServerSideProps`](/docs/basic-features/data-fetching/get-server-side-props.md) or [`getInitialProps`](/docs/api-reference/data-fetching/get-initial-props.md). Defaults to `false`
...@@ -396,7 +396,7 @@ You can listen to different events happening inside the Next.js Router. Here's a ...@@ -396,7 +396,7 @@ You can listen to different events happening inside the Next.js Router. Here's a
- `hashChangeStart(url, { shallow })` - Fires when the hash will change but not the page - `hashChangeStart(url, { shallow })` - Fires when the hash will change but not the page
- `hashChangeComplete(url, { shallow })` - Fires when the hash has changed but not the page - `hashChangeComplete(url, { shallow })` - Fires when the hash has changed but not the page
> **Note:** Here `url` is the URL shown in the browser, including the [`basePath`](/docs/api-reference/next.config.js/basepath.md). > **Note**: Here `url` is the URL shown in the browser, including the [`basePath`](/docs/api-reference/next.config.js/basepath.md).
#### Usage #### Usage
......
...@@ -50,7 +50,7 @@ The `<Script />` component requires the following properties. ...@@ -50,7 +50,7 @@ The `<Script />` component requires the following properties.
A path string specifying the URL of an external script. This can be either an absolute external URL or an internal path. A path string specifying the URL of an external script. This can be either an absolute external URL or an internal path.
> **Note:** The `src` property is required unless an inline script is used. > **Note**: The `src` property is required unless an inline script is used.
## Optional Props ## Optional Props
...@@ -151,7 +151,7 @@ Examples of scripts that do not need to load immediately and can be fetched with ...@@ -151,7 +151,7 @@ Examples of scripts that do not need to load immediately and can be fetched with
#### `worker` #### `worker`
> **Note:** The `worker` strategy is not yet stable and does not yet work with the [`app/`](/docs/routing/defining-routes) directory. Use with caution. > **Note**: The `worker` strategy is not yet stable and does not yet work with the [`app/`](/docs/routing/defining-routes) directory. Use with caution.
Scripts that use the `worker` strategy are off-loaded to a web worker in order to free up the main thread and ensure that only critical, first-party resources are processed on it. While this strategy can be used for any script, it is an advanced use case that is not guaranteed to support all third-party scripts. Scripts that use the `worker` strategy are off-loaded to a web worker in order to free up the main thread and ensure that only critical, first-party resources are processed on it. While this strategy can be used for any script, it is an advanced use case that is not guaranteed to support all third-party scripts.
...@@ -181,7 +181,7 @@ export default function Home() { ...@@ -181,7 +181,7 @@ export default function Home() {
### `onLoad` ### `onLoad`
> **Note:** `onLoad` can't be used with `beforeInteractive` – consider using `onReady` instead. Learn more about usage of `onLoad` in the [`app/` directory](https://beta.nextjs.org/docs/optimizing/scripts#onload). > **Note**: `onLoad` can't be used with `beforeInteractive` – consider using `onReady` instead. Learn more about usage of `onLoad` in the [`app/` directory](https://beta.nextjs.org/docs/optimizing/scripts#onload).
Some third-party scripts require users to run JavaScript code once after the script has finished loading in order to instantiate content or call a function. If you are loading a script with either afterInteractive or lazyOnload as a loading strategy, you can execute code after it has loaded using the onLoad property. Some third-party scripts require users to run JavaScript code once after the script has finished loading in order to instantiate content or call a function. If you are loading a script with either afterInteractive or lazyOnload as a loading strategy, you can execute code after it has loaded using the onLoad property.
...@@ -206,7 +206,7 @@ export default function Page() { ...@@ -206,7 +206,7 @@ export default function Page() {
### `onReady` ### `onReady`
> **Note:** Learn more about usage of `onReady` in the [`app/` directory](https://beta.nextjs.org/docs/optimizing/scripts#onready). > **Note**: Learn more about usage of `onReady` in the [`app/` directory](https://beta.nextjs.org/docs/optimizing/scripts#onready).
Some third-party scripts require users to run JavaScript code after the script has finished loading and every time the component is mounted (after a route navigation for example). You can execute code after the script's load event when it first loads and then after every subsequent component re-mount using the onReady property. Some third-party scripts require users to run JavaScript code after the script has finished loading and every time the component is mounted (after a route navigation for example). You can execute code after the script's load event when it first loads and then after every subsequent component re-mount using the onReady property.
...@@ -239,7 +239,7 @@ export default function Page() { ...@@ -239,7 +239,7 @@ export default function Page() {
### `onError` ### `onError`
> **Note:** `onError` cannot be used with the `beforeInteractive` loading strategy. Learn more about usage of `onError` in the [`app/` directory](https://beta.nextjs.org/docs/optimizing/scripts#onError). > **Note**: `onError` cannot be used with the `beforeInteractive` loading strategy. Learn more about usage of `onError` in the [`app/` directory](https://beta.nextjs.org/docs/optimizing/scripts#onError).
Sometimes it is helpful to catch when a script fails to load. These errors can be handled with the onError property: Sometimes it is helpful to catch when a script fails to load. These errors can be handled with the onError property:
......
...@@ -110,7 +110,7 @@ export default async function handler(req: NextRequest) { ...@@ -110,7 +110,7 @@ export default async function handler(req: NextRequest) {
You may want to restrict your edge function to specific regions when deploying so that you can colocate near your data sources ensuring lower response times which can be achieved as shown. You may want to restrict your edge function to specific regions when deploying so that you can colocate near your data sources ensuring lower response times which can be achieved as shown.
Note: this config is available in `v12.3.2` of Next.js and up. > **Note**: This configuration is available in `v12.3.2` of Next.js and up.
```js ```js
import { NextResponse } from 'next/server' import { NextResponse } from 'next/server'
...@@ -131,6 +131,6 @@ Edge API Routes use the [Edge Runtime](/docs/api-reference/edge-runtime.md), whe ...@@ -131,6 +131,6 @@ Edge API Routes use the [Edge Runtime](/docs/api-reference/edge-runtime.md), whe
Edge API Routes can [stream responses](/docs/api-reference/edge-runtime.md#web-stream-apis) from the server and run _after_ cached files (e.g. HTML, CSS, JavaScript) have been accessed. Server-side streaming can help improve performance with faster [Time To First Byte (TTFB)](https://web.dev/ttfb/). Edge API Routes can [stream responses](/docs/api-reference/edge-runtime.md#web-stream-apis) from the server and run _after_ cached files (e.g. HTML, CSS, JavaScript) have been accessed. Server-side streaming can help improve performance with faster [Time To First Byte (TTFB)](https://web.dev/ttfb/).
> Note: Using [Edge Runtime](/docs/api-reference/edge-runtime.md) with `getServerSideProps` does not give you access to the response object. If you need access to `res`, you should use the [Node.js runtime](/docs/advanced-features/react-18/switchable-runtime.md) by setting `runtime: 'nodejs'`. > **Note**: Using [Edge Runtime](/docs/api-reference/edge-runtime.md) with `getServerSideProps` does not give you access to the response object. If you need access to `res`, you should use the [Node.js runtime](/docs/advanced-features/react-18/switchable-runtime.md) by setting `runtime: 'nodejs'`.
View the [supported APIs](/docs/api-reference/edge-runtime.md) and [unsupported APIs](/docs/api-reference/edge-runtime.md#unsupported-apis) for the Edge Runtime. View the [supported APIs](/docs/api-reference/edge-runtime.md) and [unsupported APIs](/docs/api-reference/edge-runtime.md#unsupported-apis) for the Edge Runtime.
...@@ -98,7 +98,7 @@ export default function handler( ...@@ -98,7 +98,7 @@ export default function handler(
} }
``` ```
> Note: The body of `NextApiRequest` is `any` because the client may include any payload. You should validate the type/shape of the body at runtime before using it. > **Note**: The body of `NextApiRequest` is `any` because the client may include any payload. You should validate the type/shape of the body at runtime before using it.
To view more examples using types, check out the [TypeScript documentation](/docs/basic-features/typescript.md#api-routes). To view more examples using types, check out the [TypeScript documentation](/docs/basic-features/typescript.md#api-routes).
......
...@@ -134,7 +134,7 @@ One of the reasons for this restriction is that React needs to have all the requ ...@@ -134,7 +134,7 @@ One of the reasons for this restriction is that React needs to have all the requ
Also, you must use export `getStaticProps` as a standalone function — it will **not** work if you add `getStaticProps` as a property of the page component. Also, you must use export `getStaticProps` as a standalone function — it will **not** work if you add `getStaticProps` as a property of the page component.
> Note: if you have created a [custom app](/docs/advanced-features/custom-app.md), ensure you are passing the `pageProps` to the page component as shown in the linked document, otherwise the props will be empty. > **Note**: if you have created a [custom app](/docs/advanced-features/custom-app.md), ensure you are passing the `pageProps` to the page component as shown in the linked document, otherwise the props will be empty.
## Runs on every request in development ## Runs on every request in development
......
...@@ -27,7 +27,7 @@ description: 'Learn how to create or update static pages at runtime with Increme ...@@ -27,7 +27,7 @@ description: 'Learn how to create or update static pages at runtime with Increme
Next.js allows you to create or update static pages _after_ you’ve built your site. Incremental Static Regeneration (ISR) enables you to use static-generation on a per-page basis, **without needing to rebuild the entire site**. With ISR, you can retain the benefits of static while scaling to millions of pages. Next.js allows you to create or update static pages _after_ you’ve built your site. Incremental Static Regeneration (ISR) enables you to use static-generation on a per-page basis, **without needing to rebuild the entire site**. With ISR, you can retain the benefits of static while scaling to millions of pages.
> Note: The [`experimental-edge` runtime](https://nextjs.org/docs/api-reference/edge-runtime) is currently not compatible with ISR, although you can leverage `stale-while-revalidate` by setting the `cache-control` header manually. > **Note**: The [`experimental-edge` runtime](https://nextjs.org/docs/api-reference/edge-runtime) is currently not compatible with ISR, although you can leverage `stale-while-revalidate` by setting the `cache-control` header manually.
To use ISR, add the `revalidate` prop to `getStaticProps`: To use ISR, add the `revalidate` prop to `getStaticProps`:
...@@ -90,7 +90,7 @@ When a request is made to a page that was pre-rendered at build time, it will in ...@@ -90,7 +90,7 @@ When a request is made to a page that was pre-rendered at build time, it will in
When a request is made to a path that hasn’t been generated, Next.js will server-render the page on the first request. Future requests will serve the static file from the cache. ISR on Vercel [persists the cache globally and handles rollbacks](https://vercel.com/docs/concepts/next.js/incremental-static-regeneration?utm_source=next-site&utm_medium=docs&utm_campaign=next-website). When a request is made to a path that hasn’t been generated, Next.js will server-render the page on the first request. Future requests will serve the static file from the cache. ISR on Vercel [persists the cache globally and handles rollbacks](https://vercel.com/docs/concepts/next.js/incremental-static-regeneration?utm_source=next-site&utm_medium=docs&utm_campaign=next-website).
> Note: Check if your upstream data provider has caching enabled by default. You might need to disable (e.g. `useCdn: false`), otherwise a revalidation won't be able to pull fresh data to update the ISR cache. Caching can occur at a CDN (for an endpoint being requested) when it returns the `Cache-Control` header. > **Note**: Check if your upstream data provider has caching enabled by default. You might need to disable (e.g. `useCdn: false`), otherwise a revalidation won't be able to pull fresh data to update the ISR cache. Caching can occur at a CDN (for an endpoint being requested) when it returns the `Cache-Control` header.
## On-Demand Revalidation ## On-Demand Revalidation
...@@ -103,7 +103,7 @@ Starting with `v12.2.0`, Next.js supports On-Demand Incremental Static Regenerat ...@@ -103,7 +103,7 @@ Starting with `v12.2.0`, Next.js supports On-Demand Incremental Static Regenerat
Inside `getStaticProps`, you do not need to specify `revalidate` to use on-demand revalidation. If `revalidate` is omitted, Next.js will use the default value of `false` (no revalidation) and only revalidate the page on-demand when `revalidate()` is called. Inside `getStaticProps`, you do not need to specify `revalidate` to use on-demand revalidation. If `revalidate` is omitted, Next.js will use the default value of `false` (no revalidation) and only revalidate the page on-demand when `revalidate()` is called.
> **Note:** [Middleware](/docs/advanced-features/middleware.md) won't be executed for On-Demand ISR requests. Instead, call `revalidate()` on the _exact_ path that you want revalidated. For example, if you have `pages/blog/[slug].js` and a rewrite from `/post-1` -> `/blog/post-1`, you would need to call `res.revalidate('/blog/post-1')`. > **Note**: [Middleware](/docs/advanced-features/middleware.md) won't be executed for On-Demand ISR requests. Instead, call `revalidate()` on the _exact_ path that you want revalidated. For example, if you have `pages/blog/[slug].js` and a rewrite from `/post-1` -> `/blog/post-1`, you would need to call `res.revalidate('/blog/post-1')`.
### Using On-Demand Revalidation ### Using On-Demand Revalidation
...@@ -201,7 +201,7 @@ module.exports = { ...@@ -201,7 +201,7 @@ module.exports = {
} }
``` ```
> **Note:** You might need to consider a race condition between multiple pods trying to update the cache at the same time, depending on how your shared mount is configured. > **Note**: You might need to consider a race condition between multiple pods trying to update the cache at the same time, depending on how your shared mount is configured.
## Related ## Related
......
...@@ -170,4 +170,4 @@ Environment variables are looked up in the following places, in order, stopping ...@@ -170,4 +170,4 @@ Environment variables are looked up in the following places, in order, stopping
For example, if `NODE_ENV` is `development` and you define a variable in both `.env.development.local` and `.env`, the value in `.env.development.local` will be used. For example, if `NODE_ENV` is `development` and you define a variable in both `.env.development.local` and `.env`, the value in `.env.development.local` will be used.
> **Note:** The allowed values for `NODE_ENV` are `production`, `development` and `test`. > **Note**: The allowed values for `NODE_ENV` are `production`, `development` and `test`.
...@@ -94,7 +94,7 @@ Refer to the [`next/script`](/docs/api-reference/next/script.md#strategy) API re ...@@ -94,7 +94,7 @@ Refer to the [`next/script`](/docs/api-reference/next/script.md#strategy) API re
### Offloading Scripts To A Web Worker (experimental) ### Offloading Scripts To A Web Worker (experimental)
> **Note:** The `worker` strategy is not yet stable and does not yet work with the [`app/`](https://beta.nextjs.org/docs/routing/defining-routes) directory. Use with caution. > **Note**: The `worker` strategy is not yet stable and does not yet work with the [`app/`](https://beta.nextjs.org/docs/routing/defining-routes) directory. Use with caution.
Scripts that use the `worker` strategy are offloaded and executed in a web worker with [Partytown](https://partytown.builder.io/). This can improve the performance of your site by dedicating the main thread to the rest of your application code. Scripts that use the `worker` strategy are offloaded and executed in a web worker with [Partytown](https://partytown.builder.io/). This can improve the performance of your site by dedicating the main thread to the rest of your application code.
......
...@@ -18,7 +18,7 @@ function Avatar() { ...@@ -18,7 +18,7 @@ function Avatar() {
export default Avatar export default Avatar
``` ```
> Note: `next/image` requires Next.js 10 or later. > **Note**: `next/image` requires Next.js 10 or later.
This folder is also useful for `robots.txt`, `favicon.ico`, Google Site Verification, and any other static files (including `.html`)! This folder is also useful for `robots.txt`, `favicon.ico`, Google Site Verification, and any other static files (including `.html`)!
......
...@@ -103,7 +103,7 @@ The following services support Next.js `v12+`. Below, you’ll find examples or ...@@ -103,7 +103,7 @@ The following services support Next.js `v12+`. Below, you’ll find examples or
- [Railway](https://docs.railway.app/getting-started) - [Railway](https://docs.railway.app/getting-started)
- [Render](https://render.com/docs/deploy-nextjs-app) - [Render](https://render.com/docs/deploy-nextjs-app)
> **Note:** There are also managed platforms that allow you to use a Dockerfile as shown in the [example above](/docs/deployment.md#docker-image). > **Note**: There are also managed platforms that allow you to use a Dockerfile as shown in the [example above](/docs/deployment.md#docker-image).
### Static Only ### Static Only
...@@ -123,7 +123,7 @@ You can also manually deploy the output from [`output: 'export'`](/docs/advanced ...@@ -123,7 +123,7 @@ You can also manually deploy the output from [`output: 'export'`](/docs/advanced
- [Terraform](https://github.com/milliHQ/terraform-aws-next-js) - [Terraform](https://github.com/milliHQ/terraform-aws-next-js)
- [SST](https://docs.sst.dev/start/nextjs) - [SST](https://docs.sst.dev/start/nextjs)
> **Note:** Not all serverless providers implement the [Next.js Build API](/docs/deployment.md#nextjs-build-api) from `next start`. Please check with the provider to see what features are supported. > **Note**: Not all serverless providers implement the [Next.js Build API](/docs/deployment.md#nextjs-build-api) from `next start`. Please check with the provider to see what features are supported.
## Automatic Updates ## Automatic Updates
...@@ -131,7 +131,7 @@ When you deploy your Next.js application, you want to see the latest version wit ...@@ -131,7 +131,7 @@ When you deploy your Next.js application, you want to see the latest version wit
Next.js will automatically load the latest version of your application in the background when routing. For client-side navigations, `next/link` will temporarily function as a normal `<a>` tag. Next.js will automatically load the latest version of your application in the background when routing. For client-side navigations, `next/link` will temporarily function as a normal `<a>` tag.
**Note:** If a new page (with an old version) has already been prefetched by `next/link`, Next.js will use the old version. Navigating to a page that has _not_ been prefetched (and is not cached at the CDN level) will load the latest version. **Note**: If a new page (with an old version) has already been prefetched by `next/link`, Next.js will use the old version. Navigating to a page that has _not_ been prefetched (and is not cached at the CDN level) will load the latest version.
## Manual Graceful shutdowns ## Manual Graceful shutdowns
......
...@@ -41,7 +41,7 @@ Cache-Control: public, max-age=31536000, immutable ...@@ -41,7 +41,7 @@ Cache-Control: public, max-age=31536000, immutable
`Cache-Control` headers set in `next.config.js` will be overwritten in production to ensure that static assets can be cached effectively. If you need to revalidate the cache of a page that has been [statically generated](/docs/basic-features/pages.md#static-generation-recommended), you can do so by setting `revalidate` in the page's [`getStaticProps`](/docs/basic-features/data-fetching/get-static-props.md) function. If you're using `next/image`, you can configure the [`minimumCacheTTL`](/docs/api-reference/next/image#minimum-cache-ttl) for the default Image Optimization loader. `Cache-Control` headers set in `next.config.js` will be overwritten in production to ensure that static assets can be cached effectively. If you need to revalidate the cache of a page that has been [statically generated](/docs/basic-features/pages.md#static-generation-recommended), you can do so by setting `revalidate` in the page's [`getStaticProps`](/docs/basic-features/data-fetching/get-static-props.md) function. If you're using `next/image`, you can configure the [`minimumCacheTTL`](/docs/api-reference/next/image#minimum-cache-ttl) for the default Image Optimization loader.
**Note:** When running your application locally with `next dev`, your headers are overwritten to prevent caching locally. > **Note**: When running your application locally with `next dev`, your headers are overwritten to prevent caching locally.
``` ```
Cache-Control: no-cache, no-store, max-age=0, must-revalidate Cache-Control: no-cache, no-store, max-age=0, must-revalidate
...@@ -74,7 +74,7 @@ By default, `Cache-Control` headers will be set differently depending on how you ...@@ -74,7 +74,7 @@ By default, `Cache-Control` headers will be set differently depending on how you
- If the page uses `getServerSideProps` or `getInitialProps`, it will use the default `Cache-Control` header set by `next start` in order to prevent accidental caching of responses that cannot be cached. If you want a different cache behavior while using `getServerSideProps`, use `res.setHeader('Cache-Control', 'value_you_prefer')` inside of the function as shown above. - If the page uses `getServerSideProps` or `getInitialProps`, it will use the default `Cache-Control` header set by `next start` in order to prevent accidental caching of responses that cannot be cached. If you want a different cache behavior while using `getServerSideProps`, use `res.setHeader('Cache-Control', 'value_you_prefer')` inside of the function as shown above.
- If the page is using `getStaticProps`, it will have a `Cache-Control` header of `s-maxage=REVALIDATE_SECONDS, stale-while-revalidate`, or if `revalidate` is _not_ used, `s-maxage=31536000, stale-while-revalidate` to cache for the maximum age possible. - If the page is using `getStaticProps`, it will have a `Cache-Control` header of `s-maxage=REVALIDATE_SECONDS, stale-while-revalidate`, or if `revalidate` is _not_ used, `s-maxage=31536000, stale-while-revalidate` to cache for the maximum age possible.
> **Note:** Your deployment provider must support caching for dynamic responses. If you are self-hosting, you will need to add this logic yourself using a key/value store like Redis. If you are using Vercel, [Edge Caching works without configuration](https://vercel.com/docs/edge-network/caching?utm_source=next-site&utm_medium=docs&utm_campaign=next-website). > **Note**: Your deployment provider must support caching for dynamic responses. If you are self-hosting, you will need to add this logic yourself using a key/value store like Redis. If you are using Vercel, [Edge Caching works without configuration](https://vercel.com/docs/edge-network/caching?utm_source=next-site&utm_medium=docs&utm_campaign=next-website).
## Reducing JavaScript Size ## Reducing JavaScript Size
......
...@@ -39,7 +39,7 @@ The second strategy is to create a new Next.js app that points to the root URL o ...@@ -39,7 +39,7 @@ The second strategy is to create a new Next.js app that points to the root URL o
For example, let's say you created a Next.js app to be served from `example.com` with the following `next.config.js`. Now, requests for the pages you’ve added to this Next.js app (e.g. `/about` if you’ve added `pages/about.js`) will be handled by Next.js, and requests for any other route (e.g. `/dashboard`) will be proxied to `proxy.example.com`. For example, let's say you created a Next.js app to be served from `example.com` with the following `next.config.js`. Now, requests for the pages you’ve added to this Next.js app (e.g. `/about` if you’ve added `pages/about.js`) will be handled by Next.js, and requests for any other route (e.g. `/dashboard`) will be proxied to `proxy.example.com`.
> **Note:** If you use [fallback: true/'blocking'](/docs/api-reference/data-fetching/get-static-paths#fallback-true) in `getStaticPaths`, the catch-all fallback `rewrites` defined in `next.config.js` will not be run. They are instead caught by the `getStaticPaths` fallback. > **Note**: If you use [fallback: true/'blocking'](/docs/api-reference/data-fetching/get-static-paths#fallback-true) in `getStaticPaths`, the catch-all fallback `rewrites` defined in `next.config.js` will not be run. They are instead caught by the `getStaticPaths` fallback.
```jsx ```jsx
// next.config.js // next.config.js
...@@ -76,7 +76,7 @@ module.exports = { ...@@ -76,7 +76,7 @@ module.exports = {
To learn more about rewrites, take a look at our [documentation](/docs/api-reference/next.config.js/rewrites.md). To learn more about rewrites, take a look at our [documentation](/docs/api-reference/next.config.js/rewrites.md).
> **Note:** If you are incrementally migrating to a dynamic route (e.g. `[slug].js`) and using `fallback: true` or `fallback: 'blocking'` along with a fallback `rewrite`, ensure you consider the case where pages are not found. When Next.js matches the dynamic route it stops checking any further routes. Using `notFound: true` in `getStaticProps` will return the 404 page without applying the fallback `rewrite`. If this is not desired, you can use `getServerSideProps` with `stale-while-revalidate` Cache-Control headers when returning your props. Then, you can _manually_ proxy to your existing backend using something like [http-proxy](https://github.com/vercel/next.js/discussions/38839#discussioncomment-3744442) instead of returning `notFound: true`. > **Note**: If you are incrementally migrating to a dynamic route (e.g. `[slug].js`) and using `fallback: true` or `fallback: 'blocking'` along with a fallback `rewrite`, ensure you consider the case where pages are not found. When Next.js matches the dynamic route it stops checking any further routes. Using `notFound: true` in `getStaticProps` will return the 404 page without applying the fallback `rewrite`. If this is not desired, you can use `getServerSideProps` with `stale-while-revalidate` Cache-Control headers when returning your props. Then, you can _manually_ proxy to your existing backend using something like [http-proxy](https://github.com/vercel/next.js/discussions/38839#discussioncomment-3744442) instead of returning `notFound: true`.
### Micro-Frontends with Monorepos and Subdomains ### Micro-Frontends with Monorepos and Subdomains
......
...@@ -117,7 +117,7 @@ You can use `cy.visit("/")` instead of `cy.visit("http://localhost:3000/")` if y ...@@ -117,7 +117,7 @@ You can use `cy.visit("/")` instead of `cy.visit("http://localhost:3000/")` if y
Component tests build and mount a specific component without having to bundle your whole application or launch a server. This allows for more performant tests that still provide visual feedback and the same API used for Cypress E2E tests. Component tests build and mount a specific component without having to bundle your whole application or launch a server. This allows for more performant tests that still provide visual feedback and the same API used for Cypress E2E tests.
> **Note:** Since component tests do not launch a Next.js server, capabilities like `<Image />` and `getServerSideProps` which rely on a server being available will not function out-of-the-box. See the [Cypress Next.js docs](https://docs.cypress.io/guides/component-testing/react/overview#Nextjs) for examples of getting these features working within component tests. > **Note**: Since component tests do not launch a Next.js server, capabilities like `<Image />` and `getServerSideProps` which rely on a server being available will not function out-of-the-box. See the [Cypress Next.js docs](https://docs.cypress.io/guides/component-testing/react/overview#Nextjs) for examples of getting these features working within component tests.
Assuming the same components from the previous section, add a test to validate a component is rendering the expected output: Assuming the same components from the previous section, add a test to validate a component is rendering the expected output:
...@@ -148,7 +148,7 @@ Since Cypress E2E tests are testing a real Next.js application they require the ...@@ -148,7 +148,7 @@ Since Cypress E2E tests are testing a real Next.js application they require the
Run `npm run build` and `npm run start`, then run `npm run cypress -- --e2e` in another terminal window to start Cypress and run your E2E testing suite. Run `npm run build` and `npm run start`, then run `npm run cypress -- --e2e` in another terminal window to start Cypress and run your E2E testing suite.
> **Note:** Alternatively, you can install the `start-server-and-test` package and add it to the `package.json` scripts field: `"test": "start-server-and-test start http://localhost:3000 cypress"` to start the Next.js production server in conjunction with Cypress. Remember to rebuild your application after new changes. > **Note**: Alternatively, you can install the `start-server-and-test` package and add it to the `package.json` scripts field: `"test": "start-server-and-test start http://localhost:3000 cypress"` to start the Next.js production server in conjunction with Cypress. Remember to rebuild your application after new changes.
#### Component Tests #### Component Tests
...@@ -264,7 +264,7 @@ Since Playwright is testing a real Next.js application, it requires the Next.js ...@@ -264,7 +264,7 @@ Since Playwright is testing a real Next.js application, it requires the Next.js
Run `npm run build` and `npm run start`, then run `npm run test:e2e` in another terminal window to run the Playwright tests. Run `npm run build` and `npm run start`, then run `npm run test:e2e` in another terminal window to run the Playwright tests.
> **Note:** Alternatively, you can use the [`webServer`](https://playwright.dev/docs/test-advanced#launching-a-development-web-server-during-the-tests) feature to let Playwright start the development server and wait until it's fully available. > **Note**: Alternatively, you can use the [`webServer`](https://playwright.dev/docs/test-advanced#launching-a-development-web-server-during-the-tests) feature to let Playwright start the development server and wait until it's fully available.
### Running Playwright on Continuous Integration (CI) ### Running Playwright on Continuous Integration (CI)
......
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