Recipe-app main
This commit is contained in:
Generated
Vendored
+8
@@ -0,0 +1,8 @@
|
||||
---
|
||||
title: Font Module
|
||||
nav_title: Font
|
||||
description: API Reference for the Font Module
|
||||
source: app/api-reference/components/font
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Form
|
||||
description: Learn how to use the `<Form>` component to handle form submissions and search params updates with client-side navigation.
|
||||
source: app/api-reference/components/form
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+67
@@ -0,0 +1,67 @@
|
||||
---
|
||||
title: Head
|
||||
description: Add custom elements to the `head` of your page with the built-in Head component.
|
||||
---
|
||||
|
||||
We expose a built-in component for appending elements to the `head` of the page:
|
||||
|
||||
```jsx
|
||||
import Head from 'next/head'
|
||||
|
||||
function IndexPage() {
|
||||
return (
|
||||
<div>
|
||||
<Head>
|
||||
<title>My page title</title>
|
||||
</Head>
|
||||
<p>Hello world!</p>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export default IndexPage
|
||||
```
|
||||
|
||||
## Avoid duplicated tags
|
||||
|
||||
To avoid duplicate tags in your `head` you can use the `key` property, which will make sure the tag is only rendered once, as in the following example:
|
||||
|
||||
```jsx
|
||||
import Head from 'next/head'
|
||||
|
||||
function IndexPage() {
|
||||
return (
|
||||
<div>
|
||||
<Head>
|
||||
<title>My page title</title>
|
||||
<meta property="og:title" content="My page title" key="title" />
|
||||
</Head>
|
||||
<Head>
|
||||
<meta property="og:title" content="My new title" key="title" />
|
||||
</Head>
|
||||
<p>Hello world!</p>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export default IndexPage
|
||||
```
|
||||
|
||||
In this case only the second `<meta property="og:title" />` is rendered. `meta` tags with duplicate `key` attributes are automatically handled.
|
||||
|
||||
> **Good to know**: `<title>` and `<base>` tags are automatically checked for duplicates by Next.js, so using key is not necessary for these tags.
|
||||
|
||||
> The contents of `head` get cleared upon unmounting the component, so make sure each page completely defines what it needs in `head`, without making assumptions about what other pages added.
|
||||
|
||||
## Use minimal nesting
|
||||
|
||||
`title`, `meta` or any other elements (e.g. `script`) need to be contained as **direct** children of the `Head` element,
|
||||
or wrapped into maximum one level of `<React.Fragment>` or arrays—otherwise the tags won't be correctly picked up on client-side navigations.
|
||||
|
||||
## Use `next/script` for scripts
|
||||
|
||||
We recommend using [`next/script`](/docs/pages/guides/scripts) in your component instead of manually creating a `<script>` in `next/head`.
|
||||
|
||||
## No `html` or `body` tags
|
||||
|
||||
You **cannot** use `<Head>` to set attributes on `<html>` or `<body>` tags. This will result in an `next-head-count is missing` error. `next/head` can only handle tags inside the HTML `<head>` tag.
|
||||
Generated
Vendored
+659
@@ -0,0 +1,659 @@
|
||||
---
|
||||
title: Image (Legacy)
|
||||
description: Backwards compatible Image Optimization with the Legacy Image component.
|
||||
version: legacy
|
||||
---
|
||||
|
||||
Starting with Next.js 13, the `next/image` component was rewritten to improve both the performance and developer experience. In order to provide a backwards compatible upgrade solution, the old `next/image` was renamed to `next/legacy/image`.
|
||||
|
||||
> **Warning**: `next/legacy/image` is deprecated and will be removed in a future version of Next.js. Please use [`next/image`](/docs/app/api-reference/components/image) instead.
|
||||
|
||||
## Comparison
|
||||
|
||||
Compared to `next/legacy/image`, the new `next/image` component has the following changes:
|
||||
|
||||
- Removes `<span>` wrapper around `<img>` in favor of [native computed aspect ratio](https://caniuse.com/mdn-html_elements_img_aspect_ratio_computed_from_attributes)
|
||||
- Adds support for canonical `style` prop
|
||||
- Removes `layout` prop in favor of `style` or `className`
|
||||
- Removes `objectFit` prop in favor of `style` or `className`
|
||||
- Removes `objectPosition` prop in favor of `style` or `className`
|
||||
- Removes `IntersectionObserver` implementation in favor of [native lazy loading](https://caniuse.com/loading-lazy-attr)
|
||||
- Removes `lazyBoundary` prop since there is no native equivalent
|
||||
- Removes `lazyRoot` prop since there is no native equivalent
|
||||
- Removes `loader` config in favor of [`loader`](#loader) prop
|
||||
- Changed `alt` prop from optional to required
|
||||
- Changed `onLoadingComplete` callback to receive reference to `<img>` element
|
||||
|
||||
## Required Props
|
||||
|
||||
The `<Image />` component requires the following properties.
|
||||
|
||||
### src
|
||||
|
||||
Must be one of the following:
|
||||
|
||||
- A [statically imported](/docs/pages/api-reference/components/image#src) image file
|
||||
- A path string. This can be either an absolute external URL, or an internal path depending on the [loader](#loader) prop or [loader configuration](#loader-configuration).
|
||||
|
||||
When using the default [loader](#loader), also consider the following for source images:
|
||||
|
||||
- When src is an external URL, you must also configure [remotePatterns](#remote-patterns)
|
||||
- When src is [animated](#animated-images) or not a known format (JPEG, PNG, WebP, AVIF, GIF, TIFF) the image will be served as-is
|
||||
- When src is SVG format, it will be blocked unless `unoptimized` or `dangerouslyAllowSVG` is enabled
|
||||
|
||||
### width
|
||||
|
||||
The `width` property can represent either the _rendered_ width or _original_ width in pixels, depending on the [`layout`](#layout) and [`sizes`](#sizes) properties.
|
||||
|
||||
When using `layout="intrinsic"` or `layout="fixed"` the `width` property represents the _rendered_ width in pixels, so it will affect how large the image appears.
|
||||
|
||||
When using `layout="responsive"`, `layout="fill"`, the `width` property represents the _original_ width in pixels, so it will only affect the aspect ratio.
|
||||
|
||||
The `width` property is required, except for [statically imported images](/docs/pages/api-reference/components/image#src), or those with `layout="fill"`.
|
||||
|
||||
### height
|
||||
|
||||
The `height` property can represent either the _rendered_ height or _original_ height in pixels, depending on the [`layout`](#layout) and [`sizes`](#sizes) properties.
|
||||
|
||||
When using `layout="intrinsic"` or `layout="fixed"` the `height` property represents the _rendered_ height in pixels, so it will affect how large the image appears.
|
||||
|
||||
When using `layout="responsive"`, `layout="fill"`, the `height` property represents the _original_ height in pixels, so it will only affect the aspect ratio.
|
||||
|
||||
The `height` property is required, except for [statically imported images](/docs/pages/api-reference/components/image#src), or those with `layout="fill"`.
|
||||
|
||||
## Optional Props
|
||||
|
||||
The `<Image />` component accepts a number of additional properties beyond those which are required. This section describes the most commonly-used properties of the Image component. Find details about more rarely-used properties in the [Advanced Props](#advanced-props) section.
|
||||
|
||||
### layout
|
||||
|
||||
The layout behavior of the image as the viewport changes size.
|
||||
|
||||
| `layout` | Behavior | `srcSet` | `sizes` | Has wrapper and sizer |
|
||||
| --------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------- | --------------------- |
|
||||
| `intrinsic` (default) | Scale _down_ to fit width of container, up to image size | `1x`, `2x` (based on [imageSizes](#image-sizes)) | N/A | yes |
|
||||
| `fixed` | Sized to `width` and `height` exactly | `1x`, `2x` (based on [imageSizes](#image-sizes)) | N/A | yes |
|
||||
| `responsive` | Scale to fit width of container | `640w`, `750w`, ... `2048w`, `3840w` (based on [imageSizes](#image-sizes) and [deviceSizes](#device-sizes)) | `100vw` | yes |
|
||||
| `fill` | Grow in both X and Y axes to fill container | `640w`, `750w`, ... `2048w`, `3840w` (based on [imageSizes](#image-sizes) and [deviceSizes](#device-sizes)) | `100vw` | yes |
|
||||
|
||||
- [Demo the `intrinsic` layout (default)](https://image-legacy-component.nextjs.gallery/layout-intrinsic)
|
||||
- When `intrinsic`, the image will scale the dimensions down for smaller viewports, but maintain the original dimensions for larger viewports.
|
||||
- [Demo the `fixed` layout](https://image-legacy-component.nextjs.gallery/layout-fixed)
|
||||
- When `fixed`, the image dimensions will not change as the viewport changes (no responsiveness) similar to the native `img` element.
|
||||
- [Demo the `responsive` layout](https://image-legacy-component.nextjs.gallery/layout-responsive)
|
||||
- When `responsive`, the image will scale the dimensions down for smaller viewports and scale up for larger viewports.
|
||||
- Ensure the parent element uses `display: block` in their stylesheet.
|
||||
- [Demo the `fill` layout](https://image-legacy-component.nextjs.gallery/layout-fill)
|
||||
- When `fill`, the image will stretch both width and height to the dimensions of the parent element, provided the parent element is relative.
|
||||
- This is usually paired with the [`objectFit`](#objectfit) property.
|
||||
- Ensure the parent element has `position: relative` in their stylesheet.
|
||||
- [Demo background image](https://image-legacy-component.nextjs.gallery/background)
|
||||
|
||||
### loader
|
||||
|
||||
A custom function used to resolve URLs. Setting the loader as a prop on the Image component overrides the default loader defined in the [`images` section of `next.config.js`](#loader-configuration).
|
||||
|
||||
A `loader` is a function returning a URL string for the image, given the following parameters:
|
||||
|
||||
- [`src`](#src)
|
||||
- [`width`](#width)
|
||||
- [`quality`](#quality)
|
||||
|
||||
Here is an example of using a custom loader:
|
||||
|
||||
```js
|
||||
import Image from 'next/legacy/image'
|
||||
|
||||
const myLoader = ({ src, width, quality }) => {
|
||||
return `https://example.com/${src}?w=${width}&q=${quality || 75}`
|
||||
}
|
||||
|
||||
const MyImage = (props) => {
|
||||
return (
|
||||
<Image
|
||||
loader={myLoader}
|
||||
src="me.png"
|
||||
alt="Picture of the author"
|
||||
width={500}
|
||||
height={500}
|
||||
/>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### sizes
|
||||
|
||||
A string that provides information about how wide the image will be at different breakpoints. The value of `sizes` will greatly affect performance for images using `layout="responsive"` or `layout="fill"`. It will be ignored for images using `layout="intrinsic"` or `layout="fixed"`.
|
||||
|
||||
The `sizes` property serves two important purposes related to image performance:
|
||||
|
||||
First, the value of `sizes` is used by the browser to determine which size of the image to download, from `next/legacy/image`'s automatically-generated source set. When the browser chooses, it does not yet know the size of the image on the page, so it selects an image that is the same size or larger than the viewport. The `sizes` property allows you to tell the browser that the image will actually be smaller than full screen. If you don't specify a `sizes` value, a default value of `100vw` (full screen width) is used.
|
||||
|
||||
Second, the `sizes` value is parsed and used to trim the values in the automatically-created source set. If the `sizes` property includes sizes such as `50vw`, which represent a percentage of the viewport width, then the source set is trimmed to not include any values which are too small to ever be necessary.
|
||||
|
||||
For example, if you know your styling will cause an image to be full-width on mobile devices, in a 2-column layout on tablets, and a 3-column layout on desktop displays, you should include a sizes property such as the following:
|
||||
|
||||
```js
|
||||
import Image from 'next/legacy/image'
|
||||
const Example = () => (
|
||||
<div className="grid-element">
|
||||
<Image
|
||||
src="/example.png"
|
||||
layout="fill"
|
||||
sizes="(max-width: 768px) 100vw,
|
||||
(max-width: 1200px) 50vw,
|
||||
33vw"
|
||||
/>
|
||||
</div>
|
||||
)
|
||||
```
|
||||
|
||||
This example `sizes` could have a dramatic effect on performance metrics. Without the `33vw` sizes, the image selected from the server would be 3 times as wide as it needs to be. Because file size is proportional to the square of the width, without `sizes` the user would download an image that's 9 times larger than necessary.
|
||||
|
||||
Learn more about `srcset` and `sizes`:
|
||||
|
||||
- [web.dev](https://web.dev/learn/design/responsive-images/#sizes)
|
||||
- [mdn](https://developer.mozilla.org/docs/Web/HTML/Element/img#attr-sizes)
|
||||
|
||||
### quality
|
||||
|
||||
The quality of the optimized image, an integer between `1` and `100` where `100` is the best quality. Defaults to `75`.
|
||||
|
||||
### priority
|
||||
|
||||
When true, the image will be considered high priority and
|
||||
[preload](https://web.dev/preload-responsive-images/). Lazy loading is automatically disabled for images using `priority`.
|
||||
|
||||
You should use the `priority` property on any image detected as the [Largest Contentful Paint (LCP)](https://nextjs.org/learn/seo/web-performance/lcp) element. It may be appropriate to have multiple priority images, as different images may be the LCP element for different viewport sizes.
|
||||
|
||||
Should only be used when the image is visible above the fold. Defaults to `false`.
|
||||
|
||||
### placeholder
|
||||
|
||||
A placeholder to use while the image is loading. Possible values are `blur` or `empty`. Defaults to `empty`.
|
||||
|
||||
When `blur`, the [`blurDataURL`](#blurdataurl) property will be used as the placeholder. If `src` is an object from a [static import](/docs/pages/api-reference/components/image#src) and the imported image is `.jpg`, `.png`, `.webp`, or `.avif`, then `blurDataURL` will be automatically populated.
|
||||
|
||||
For dynamic images, you must provide the [`blurDataURL`](#blurdataurl) property. Solutions such as [Plaiceholder](https://github.com/joe-bell/plaiceholder) can help with `base64` generation.
|
||||
|
||||
When `empty`, there will be no placeholder while the image is loading, only empty space.
|
||||
|
||||
Try it out:
|
||||
|
||||
- [Demo the `blur` placeholder](https://image-legacy-component.nextjs.gallery/placeholder)
|
||||
- [Demo the shimmer effect with `blurDataURL` prop](https://image-legacy-component.nextjs.gallery/shimmer)
|
||||
- [Demo the color effect with `blurDataURL` prop](https://image-legacy-component.nextjs.gallery/color)
|
||||
|
||||
## Advanced Props
|
||||
|
||||
In some cases, you may need more advanced usage. The `<Image />` component optionally accepts the following advanced properties.
|
||||
|
||||
### style
|
||||
|
||||
Allows [passing CSS styles](https://developer.mozilla.org/docs/Web/HTML/Element/style) to the underlying image element.
|
||||
|
||||
Note that all `layout` modes apply their own styles to the image element, and these automatic styles take precedence over the `style` prop.
|
||||
|
||||
Also keep in mind that the required `width` and `height` props can interact with your styling. If you use styling to modify an image's `width`, you must set the `height="auto"` style as well, or your image will be distorted.
|
||||
|
||||
### objectFit
|
||||
|
||||
Defines how the image will fit into its parent container when using `layout="fill"`.
|
||||
|
||||
This value is passed to the [object-fit CSS property](https://developer.mozilla.org/docs/Web/CSS/object-fit) for the `src` image.
|
||||
|
||||
### objectPosition
|
||||
|
||||
Defines how the image is positioned within its parent element when using `layout="fill"`.
|
||||
|
||||
This value is passed to the [object-position CSS property](https://developer.mozilla.org/docs/Web/CSS/object-position) applied to the image.
|
||||
|
||||
### onLoadingComplete
|
||||
|
||||
A callback function that is invoked once the image is completely loaded and the [placeholder](#placeholder) has been removed.
|
||||
|
||||
The `onLoadingComplete` function accepts one parameter, an object with the following properties:
|
||||
|
||||
- [`naturalWidth`](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/naturalWidth)
|
||||
- [`naturalHeight`](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/naturalHeight)
|
||||
|
||||
### loading
|
||||
|
||||
The loading behavior of the image. Defaults to `lazy`.
|
||||
|
||||
When `lazy`, defer loading the image until it reaches a calculated distance from
|
||||
the viewport.
|
||||
|
||||
When `eager`, load the image immediately.
|
||||
|
||||
[Learn more](https://developer.mozilla.org/docs/Web/HTML/Element/img#attr-loading)
|
||||
|
||||
### blurDataURL
|
||||
|
||||
A [Data URL](https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URIs) to
|
||||
be used as a placeholder image before the `src` image successfully loads. Only takes effect when combined
|
||||
with [`placeholder="blur"`](#placeholder).
|
||||
|
||||
Must be a base64-encoded image. It will be enlarged and blurred, so a very small image (10px or
|
||||
less) is recommended. Including larger images as placeholders may harm your application performance.
|
||||
|
||||
Try it out:
|
||||
|
||||
- [Demo the default `blurDataURL` prop](https://image-legacy-component.nextjs.gallery/placeholder)
|
||||
- [Demo the shimmer effect with `blurDataURL` prop](https://image-legacy-component.nextjs.gallery/shimmer)
|
||||
- [Demo the color effect with `blurDataURL` prop](https://image-legacy-component.nextjs.gallery/color)
|
||||
|
||||
You can also [generate a solid color Data URL](https://png-pixel.com) to match the image.
|
||||
|
||||
### lazyBoundary
|
||||
|
||||
A string (with similar syntax to the margin property) that acts as the bounding box used to detect the intersection of the viewport with the image and trigger lazy [loading](#loading). Defaults to `"200px"`.
|
||||
|
||||
If the image is nested in a scrollable parent element other than the root document, you will also need to assign the [lazyRoot](#lazyroot) prop.
|
||||
|
||||
[Learn more](https://developer.mozilla.org/docs/Web/API/IntersectionObserver/rootMargin)
|
||||
|
||||
### lazyRoot
|
||||
|
||||
A React [Ref](https://react.dev/learn/referencing-values-with-refs) pointing to the scrollable parent element. Defaults to `null` (the document viewport).
|
||||
|
||||
The Ref must point to a DOM element or a React component that [forwards the Ref](https://react.dev/reference/react/forwardRef) to the underlying DOM element.
|
||||
|
||||
**Example pointing to a DOM element**
|
||||
|
||||
```jsx
|
||||
import Image from 'next/legacy/image'
|
||||
import React from 'react'
|
||||
|
||||
const Example = () => {
|
||||
const lazyRoot = React.useRef(null)
|
||||
|
||||
return (
|
||||
<div ref={lazyRoot} style={{ overflowX: 'scroll', width: '500px' }}>
|
||||
<Image lazyRoot={lazyRoot} src="/one.jpg" width="500" height="500" />
|
||||
<Image lazyRoot={lazyRoot} src="/two.jpg" width="500" height="500" />
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
**Example pointing to a React component**
|
||||
|
||||
```jsx
|
||||
import Image from 'next/legacy/image'
|
||||
import React from 'react'
|
||||
|
||||
const Container = React.forwardRef((props, ref) => {
|
||||
return (
|
||||
<div ref={ref} style={{ overflowX: 'scroll', width: '500px' }}>
|
||||
{props.children}
|
||||
</div>
|
||||
)
|
||||
})
|
||||
|
||||
const Example = () => {
|
||||
const lazyRoot = React.useRef(null)
|
||||
|
||||
return (
|
||||
<Container ref={lazyRoot}>
|
||||
<Image lazyRoot={lazyRoot} src="/one.jpg" width="500" height="500" />
|
||||
<Image lazyRoot={lazyRoot} src="/two.jpg" width="500" height="500" />
|
||||
</Container>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
[Learn more](https://developer.mozilla.org/docs/Web/API/IntersectionObserver/root)
|
||||
|
||||
### unoptimized
|
||||
|
||||
When true, the source image will be served as-is from the `src` instead of changing quality, size, or format. Defaults to `false`.
|
||||
|
||||
This is useful for images that do not benefit from optimization such as small images (less than 1KB), vector images (SVG), or animated images (GIF).
|
||||
|
||||
```js
|
||||
import Image from 'next/image'
|
||||
|
||||
const UnoptimizedImage = (props) => {
|
||||
return <Image {...props} unoptimized />
|
||||
}
|
||||
```
|
||||
|
||||
Since Next.js 12.3.0, this prop can be assigned to all images by updating `next.config.js` with the following configuration:
|
||||
|
||||
```js filename="next.config.js"
|
||||
module.exports = {
|
||||
images: {
|
||||
unoptimized: true,
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Other Props
|
||||
|
||||
Other properties on the `<Image />` component will be passed to the underlying
|
||||
`img` element with the exception of the following:
|
||||
|
||||
- `srcSet`. Use
|
||||
[Device Sizes](#device-sizes)
|
||||
instead.
|
||||
- `ref`. Use [`onLoadingComplete`](#onloadingcomplete) instead.
|
||||
- `decoding`. It is always `"async"`.
|
||||
|
||||
## Configuration Options
|
||||
|
||||
### Remote Patterns
|
||||
|
||||
To protect your application from malicious users, configuration is required in order to use external images. This ensures that only external images from your account can be served from the Next.js Image Optimization API. These external images can be configured with the `remotePatterns` property in your `next.config.js` file, as shown below:
|
||||
|
||||
```js filename="next.config.js"
|
||||
module.exports = {
|
||||
images: {
|
||||
remotePatterns: [
|
||||
{
|
||||
protocol: 'https',
|
||||
hostname: 'example.com',
|
||||
port: '',
|
||||
pathname: '/account123/**',
|
||||
search: '',
|
||||
},
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
> **Good to know**: The example above will ensure the `src` property of `next/legacy/image` must start with `https://example.com/account123/` and must not have a query string. Any other protocol, hostname, port, or unmatched path will respond with 400 Bad Request.
|
||||
|
||||
Below is an example of the `remotePatterns` property in the `next.config.js` file using a wildcard pattern in the `hostname`:
|
||||
|
||||
```js filename="next.config.js"
|
||||
module.exports = {
|
||||
images: {
|
||||
remotePatterns: [
|
||||
{
|
||||
protocol: 'https',
|
||||
hostname: '**.example.com',
|
||||
port: '',
|
||||
search: '',
|
||||
},
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
> **Good to know**: The example above will ensure the `src` property of `next/legacy/image` must start with `https://img1.example.com` or `https://me.avatar.example.com` or any number of subdomains. It cannot have a port or query string. 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:
|
||||
|
||||
- `*` match a single path segment or subdomain
|
||||
- `**` match any number of path segments at the end or subdomains at the beginning
|
||||
|
||||
The `**` syntax does not work in the middle of the pattern.
|
||||
|
||||
> **Good to know**: When omitting `protocol`, `port`, `pathname`, or `search` then the wildcard `**` is implied. This is not recommended because it may allow malicious actors to optimize urls you did not intend.
|
||||
|
||||
Below is an example of the `remotePatterns` property in the `next.config.js` file using `search`:
|
||||
|
||||
```js filename="next.config.js"
|
||||
module.exports = {
|
||||
images: {
|
||||
remotePatterns: [
|
||||
{
|
||||
protocol: 'https',
|
||||
hostname: 'assets.example.com',
|
||||
search: '?v=1727111025337',
|
||||
},
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
> **Good to know**: The example above will ensure the `src` property of `next/legacy/image` must start with `https://assets.example.com` and must have the exact query string `?v=1727111025337`. Any other protocol or query string will respond with 400 Bad Request.
|
||||
|
||||
### Domains
|
||||
|
||||
> **Warning**: Deprecated since Next.js 14 in favor of strict [`remotePatterns`](#remote-patterns) in order to protect your application from malicious users. Only use `domains` if you own all the content served from the domain.
|
||||
|
||||
Similar to [`remotePatterns`](#remote-patterns), the `domains` configuration can be used to provide a list of allowed hostnames for external images.
|
||||
|
||||
However, the `domains` configuration does not support wildcard pattern matching and it cannot restrict protocol, port, or pathname.
|
||||
|
||||
Below is an example of the `domains` property in the `next.config.js` file:
|
||||
|
||||
```js filename="next.config.js"
|
||||
module.exports = {
|
||||
images: {
|
||||
domains: ['assets.acme.com'],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Loader Configuration
|
||||
|
||||
If you want to use a cloud provider to optimize images instead of using the Next.js built-in Image Optimization API, you can configure the `loader` and `path` prefix in your `next.config.js` file. This allows you to use relative URLs for the Image [`src`](#src) and automatically generate the correct absolute URL for your provider.
|
||||
|
||||
```js filename="next.config.js"
|
||||
module.exports = {
|
||||
images: {
|
||||
loader: 'imgix',
|
||||
path: 'https://example.com/myaccount/',
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
#### Customizing the Built-in Image Path
|
||||
|
||||
If you want to change or prefix the default path for the built-in Next.js image optimization, you can do so with the `path` property. The default value for `path` is `/_next/image`.
|
||||
|
||||
```js filename="next.config.js"
|
||||
module.exports = {
|
||||
images: {
|
||||
path: '/my-prefix/_next/image',
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Built-in Loaders
|
||||
|
||||
The following Image Optimization cloud providers are included:
|
||||
|
||||
- Default: Works automatically with `next dev`, `next start`, or a custom server
|
||||
- [Vercel](https://vercel.com): Works automatically when you deploy on Vercel, no configuration necessary. [Learn more](https://vercel.com/docs/concepts/image-optimization?utm_source=next-site&utm_medium=docs&utm_campaign=next-website)
|
||||
- [Imgix](https://www.imgix.com): `loader: 'imgix'`
|
||||
- [Cloudinary](https://cloudinary.com): `loader: 'cloudinary'`
|
||||
- [Akamai](https://www.akamai.com): `loader: 'akamai'`
|
||||
- Custom: `loader: 'custom'` use a custom cloud provider by implementing the [`loader`](#loader) prop on the `next/legacy/image` component
|
||||
|
||||
If you need a different provider, you can use the [`loader`](#loader) prop with `next/legacy/image`.
|
||||
|
||||
> Images cannot be optimized at build time using [`output: 'export'`](/docs/pages/guides/static-exports), only on-demand. To use `next/legacy/image` with `output: 'export'`, you will need to use a different loader than the default. [Read more in the discussion.](https://github.com/vercel/next.js/discussions/19065)
|
||||
|
||||
## Advanced
|
||||
|
||||
The following configuration is for advanced use cases and is usually not necessary. If you choose to configure the properties below, you will override any changes to the Next.js defaults in future updates.
|
||||
|
||||
### Device Sizes
|
||||
|
||||
If you know the expected device widths of your users, you can specify a list of device width breakpoints using the `deviceSizes` property in `next.config.js`. These widths are used when the `next/legacy/image` component uses `layout="responsive"` or `layout="fill"` to ensure the correct image is served for user's device.
|
||||
|
||||
If no configuration is provided, the default below is used.
|
||||
|
||||
```js filename="next.config.js"
|
||||
module.exports = {
|
||||
images: {
|
||||
deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Image Sizes
|
||||
|
||||
You can specify a list of image widths using the `images.imageSizes` property in your `next.config.js` file. These widths are concatenated with the array of [device sizes](#device-sizes) to form the full array of sizes used to generate image [srcset](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/srcset)s.
|
||||
|
||||
The reason there are two separate lists is that imageSizes is only used for images which provide a [`sizes`](#sizes) prop, which indicates that the image is less than the full width of the screen. **Therefore, the sizes in imageSizes should all be smaller than the smallest size in deviceSizes.**
|
||||
|
||||
If no configuration is provided, the default below is used.
|
||||
|
||||
```js filename="next.config.js"
|
||||
module.exports = {
|
||||
images: {
|
||||
imageSizes: [32, 48, 64, 96, 128, 256, 384],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Acceptable Formats
|
||||
|
||||
The default [Image Optimization API](#loader-configuration) will automatically detect the browser's supported image formats via the request's `Accept` header in order to determine the best output format.
|
||||
|
||||
If the `Accept` header matches more than one of the configured formats, the first match in the array is used. Therefore, the array order matters. If there is no match (or the source image is [animated](#animated-images)), the Image Optimization API will fallback to the original image's format.
|
||||
|
||||
If no configuration is provided, the default below is used.
|
||||
|
||||
```js filename="next.config.js"
|
||||
module.exports = {
|
||||
images: {
|
||||
formats: ['image/webp'],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
You can enable AVIF support, which will fallback to the original format of the src image if the browser [does not support AVIF](https://caniuse.com/avif):
|
||||
|
||||
```js filename="next.config.js"
|
||||
module.exports = {
|
||||
images: {
|
||||
formats: ['image/avif'],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
You can also enable both AVIF and WebP formats together. AVIF will be preferred for browsers that support it, with WebP as a fallback:
|
||||
|
||||
```js filename="next.config.js"
|
||||
module.exports = {
|
||||
images: {
|
||||
formats: ['image/avif', 'image/webp'],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
> **Good to know**:
|
||||
>
|
||||
> - We still recommend using WebP for most use cases.
|
||||
> - AVIF generally takes 50% 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.
|
||||
> - When using multiple formats, Next.js will cache each format separately. This means increased storage requirements compared to using a single format, as both AVIF and WebP versions of images will be stored for different browser support.
|
||||
> - 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
|
||||
|
||||
The following describes the caching algorithm for the default [loader](#loader). For all other loaders, please refer to your cloud provider's documentation.
|
||||
|
||||
Images are optimized dynamically upon request and stored in the `<distDir>/cache/images` directory. The optimized image file will be served for subsequent requests until the expiration is reached. When a request is made that matches a cached but expired file, the expired image is served stale immediately. Then the image is optimized again in the background (also called revalidation) and saved to the cache with the new expiration date.
|
||||
|
||||
The cache status of an image can be determined by reading the value of the `x-nextjs-cache` (`x-vercel-cache` when deployed on Vercel) response header. The possible values are the following:
|
||||
|
||||
- `MISS` - the path is not in the cache (occurs at most once, on the first visit)
|
||||
- `STALE` - the path is in the cache but exceeded the revalidate time so it will be updated in the background
|
||||
- `HIT` - the path is in the cache and has not exceeded the revalidate time
|
||||
|
||||
The expiration (or rather Max Age) is defined by either the [`minimumCacheTTL`](#minimum-cache-ttl) configuration or the upstream image `Cache-Control` header, whichever is larger. Specifically, the `max-age` value of the `Cache-Control` header is used. If both `s-maxage` and `max-age` are found, then `s-maxage` is preferred. The `max-age` is also passed-through to any downstream clients including CDNs and browsers.
|
||||
|
||||
- You can configure [`minimumCacheTTL`](#minimum-cache-ttl) to increase the cache duration when the upstream image does not include `Cache-Control` header or the value is very low.
|
||||
- You can configure [`deviceSizes`](#device-sizes) and [`imageSizes`](#image-sizes) to reduce the total number of possible generated images.
|
||||
- You can configure [formats](#acceptable-formats) to disable multiple formats in favor of a single image format.
|
||||
|
||||
### Minimum Cache TTL
|
||||
|
||||
You can configure the Time to Live (TTL) in seconds for cached optimized images. In many cases, it's better to use a [Static Image Import](/docs/pages/api-reference/components/image#src) which will automatically hash the file contents and cache the image forever with a `Cache-Control` header of `immutable`.
|
||||
|
||||
If no configuration is provided, the default below is used.
|
||||
|
||||
```js filename="next.config.js"
|
||||
module.exports = {
|
||||
images: {
|
||||
minimumCacheTTL: 14400, // 4 hours
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
You can increase the TTL to reduce the number of revalidations and potentially lower cost:
|
||||
|
||||
```js filename="next.config.js"
|
||||
module.exports = {
|
||||
images: {
|
||||
minimumCacheTTL: 2678400, // 31 days
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
The expiration (or rather Max Age) of the optimized image is defined by either the `minimumCacheTTL` or the upstream image `Cache-Control` header, whichever is larger.
|
||||
|
||||
If you need to change the caching behavior per image, you can configure [`headers`](/docs/pages/api-reference/config/next-config-js/headers) to set the `Cache-Control` header on the upstream image (e.g. `/some-asset.jpg`, not `/_next/image` itself).
|
||||
|
||||
There is no mechanism to invalidate the cache at this time, so its best to keep `minimumCacheTTL` low. Otherwise you may need to manually change the [`src`](#src) prop or delete `<distDir>/cache/images`.
|
||||
|
||||
### Disable Static Imports
|
||||
|
||||
The default behavior allows you to import static files such as `import icon from './icon.png'` and then pass that to the `src` property.
|
||||
|
||||
In some cases, you may wish to disable this feature if it conflicts with other plugins that expect the import to behave differently.
|
||||
|
||||
You can disable static image imports inside your `next.config.js`:
|
||||
|
||||
```js filename="next.config.js"
|
||||
module.exports = {
|
||||
images: {
|
||||
disableStaticImages: true,
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Dangerously Allow SVG
|
||||
|
||||
The default [loader](#loader) does not optimize SVG images for a few reasons. First, SVG is a vector format meaning it can be resized losslessly. Second, SVG has many of the same features as HTML/CSS, which can lead to vulnerabilities without proper [Content Security Policy (CSP) headers](/docs/app/api-reference/config/next-config-js/headers#content-security-policy).
|
||||
|
||||
Therefore, we recommended using the [`unoptimized`](#unoptimized) prop when the [`src`](#src) prop is known to be SVG. This happens automatically when `src` ends with `".svg"`.
|
||||
|
||||
However, if you need to serve SVG images with the default Image Optimization API, you can set `dangerouslyAllowSVG` inside your `next.config.js`:
|
||||
|
||||
```js filename="next.config.js"
|
||||
module.exports = {
|
||||
images: {
|
||||
dangerouslyAllowSVG: true,
|
||||
contentDispositionType: 'attachment',
|
||||
contentSecurityPolicy: "default-src 'self'; script-src 'none'; sandbox;",
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
In addition, it is strongly recommended to also set `contentDispositionType` to force the browser to download the image, as well as `contentSecurityPolicy` to prevent scripts embedded in the image from executing.
|
||||
|
||||
### `contentDispositionType`
|
||||
|
||||
The default [loader](#loader) sets the [`Content-Disposition`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition#as_a_response_header_for_the_main_body) header to `attachment` for added protection since the API can serve arbitrary remote images.
|
||||
|
||||
The default value is `attachment` which forces the browser to download the image when visiting directly. This is particularly important when [`dangerouslyAllowSVG`](#dangerously-allow-svg) is true.
|
||||
|
||||
You can optionally configure `inline` to allow the browser to render the image when visiting directly, without downloading it.
|
||||
|
||||
```js filename="next.config.js"
|
||||
module.exports = {
|
||||
images: {
|
||||
contentDispositionType: 'inline',
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Animated Images
|
||||
|
||||
The default [loader](#loader) will automatically bypass Image Optimization for animated images and serve the image as-is.
|
||||
|
||||
Auto-detection for animated files is best-effort and supports GIF, APNG, and WebP. If you want to explicitly bypass Image Optimization for a given animated image, use the [unoptimized](#unoptimized) prop.
|
||||
|
||||
## Version History
|
||||
|
||||
| Version | Changes |
|
||||
| --------- | ------------------------------------------------------------------------------------------------------------------- |
|
||||
| `v16.0.0` | `next/legacy/image` deprecated and will be removed in a future version of Next.js. Please use `next/image` instead. |
|
||||
| `v13.0.0` | `next/image` renamed to `next/legacy/image` |
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Image
|
||||
description: Optimize Images in your Next.js Application using the built-in `next/image` Component.
|
||||
source: app/api-reference/components/image
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Components
|
||||
description: API Reference for Next.js built-in components in the Pages Router.
|
||||
source: app/api-reference/components
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Link
|
||||
description: API reference for the `<Link>` component.
|
||||
source: app/api-reference/components/link
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Script
|
||||
description: Optimize third-party scripts in your Next.js application using the built-in `next/script` Component.
|
||||
source: app/api-reference/components/script
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+4
@@ -0,0 +1,4 @@
|
||||
---
|
||||
title: File-system conventions
|
||||
description: API Reference for Next.js file-system conventions.
|
||||
---
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: instrumentation.js
|
||||
description: API reference for the instrumentation.js file.
|
||||
source: app/api-reference/file-conventions/instrumentation
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Proxy
|
||||
description: Learn how to use Proxy to run code before a request is completed.
|
||||
source: app/api-reference/file-conventions/proxy
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+8
@@ -0,0 +1,8 @@
|
||||
---
|
||||
title: public Folder
|
||||
nav_title: public
|
||||
description: Next.js allows you to serve static files, like images, in the public directory. You can learn how it works here.
|
||||
source: app/api-reference/file-conventions/public-folder
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: src Directory
|
||||
description: Save pages under the `src` folder as an alternative to the root `pages` directory.
|
||||
source: app/api-reference/file-conventions/src-folder
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+58
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: getInitialProps
|
||||
description: Fetch dynamic data on the server for your React component with getInitialProps.
|
||||
---
|
||||
|
||||
> **Good to know**: `getInitialProps` is a legacy API. We recommend using [`getStaticProps`](/docs/pages/building-your-application/data-fetching/get-static-props) or [`getServerSideProps`](/docs/pages/building-your-application/data-fetching/get-server-side-props) instead.
|
||||
|
||||
`getInitialProps` is an `async` function that can be added to the default exported React component for the page. It will run on both the server-side and again on the client-side during page transitions. The result of the function will be forwarded to the React component as `props`.
|
||||
|
||||
```tsx filename="pages/index.tsx" switcher
|
||||
import { NextPageContext } from 'next'
|
||||
|
||||
Page.getInitialProps = async (ctx: NextPageContext) => {
|
||||
const res = await fetch('https://api.github.com/repos/vercel/next.js')
|
||||
const json = await res.json()
|
||||
return { stars: json.stargazers_count }
|
||||
}
|
||||
|
||||
export default function Page({ stars }: { stars: number }) {
|
||||
return stars
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="pages/index.js" switcher
|
||||
Page.getInitialProps = async (ctx) => {
|
||||
const res = await fetch('https://api.github.com/repos/vercel/next.js')
|
||||
const json = await res.json()
|
||||
return { stars: json.stargazers_count }
|
||||
}
|
||||
|
||||
export default function Page({ stars }) {
|
||||
return stars
|
||||
}
|
||||
```
|
||||
|
||||
> **Good to know**:
|
||||
>
|
||||
> - Data returned from `getInitialProps` is serialized when server rendering. Ensure the returned object from `getInitialProps` is a plain `Object`, and not using `Date`, `Map` or `Set`.
|
||||
> - For the initial page load, `getInitialProps` will run on the server only. `getInitialProps` will then also run on the client when navigating to a different route with the [`next/link`](/docs/pages/api-reference/components/link) component or by using [`next/router`](/docs/pages/api-reference/functions/use-router).
|
||||
> - If `getInitialProps` is used in a custom `_app.js`, and the page being navigated to is using `getServerSideProps`, then `getInitialProps` will **only** run on the server.
|
||||
|
||||
## Context Object
|
||||
|
||||
`getInitialProps` receives a single argument called `context`, which is an object with the following properties:
|
||||
|
||||
| Name | Description |
|
||||
| ---------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| `pathname` | Current route, the path of the page in `/pages` |
|
||||
| `query` | Query string of the URL, parsed as an object |
|
||||
| `asPath` | `String` of the actual path (including the query) shown in the browser |
|
||||
| `req` | [HTTP request object](https://nodejs.org/api/http.html#http_class_http_incomingmessage) (server only) |
|
||||
| `res` | [HTTP response object](https://nodejs.org/api/http.html#http_class_http_serverresponse) (server only) |
|
||||
| `err` | Error object if any error is encountered during the rendering |
|
||||
|
||||
## Caveats
|
||||
|
||||
- `getInitialProps` can only be used in `pages/` top level files, and not in nested components. To have nested data fetching at the component level, consider exploring the [App Router](/docs/app/getting-started/fetching-data).
|
||||
- Regardless of whether your route is static or dynamic, any data returned from `getInitialProps` as `props` will be able to be examined on the client-side in the initial HTML. This is to allow the page to be [hydrated](https://react.dev/reference/react-dom/hydrate) correctly. Make sure that you don't pass any sensitive information that shouldn't be available on the client in `props`.
|
||||
frontend/node_modules/next/dist/docs/02-pages/04-api-reference/03-functions/get-server-side-props.md
Generated
Vendored
+140
@@ -0,0 +1,140 @@
|
||||
---
|
||||
title: getServerSideProps
|
||||
description: API reference for `getServerSideProps`. Learn how to fetch data on each request with Next.js.
|
||||
---
|
||||
|
||||
When exporting a function called `getServerSideProps` (Server-Side Rendering) from a page, Next.js will prerender this page on each request using the data returned by `getServerSideProps`. This is useful if you want to fetch data that changes often, and have the page update to show the most current data.
|
||||
|
||||
```tsx filename="pages/index.tsx" switcher
|
||||
import type { InferGetServerSidePropsType, GetServerSideProps } from 'next'
|
||||
|
||||
type Repo = {
|
||||
name: string
|
||||
stargazers_count: number
|
||||
}
|
||||
|
||||
export const getServerSideProps = (async () => {
|
||||
// Fetch data from external API
|
||||
const res = await fetch('https://api.github.com/repos/vercel/next.js')
|
||||
const repo: Repo = await res.json()
|
||||
// Pass data to the page via props
|
||||
return { props: { repo } }
|
||||
}) satisfies GetServerSideProps<{ repo: Repo }>
|
||||
|
||||
export default function Page({
|
||||
repo,
|
||||
}: InferGetServerSidePropsType<typeof getServerSideProps>) {
|
||||
return (
|
||||
<main>
|
||||
<p>{repo.stargazers_count}</p>
|
||||
</main>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="pages/index.js" switcher
|
||||
export async function getServerSideProps() {
|
||||
// Fetch data from external API
|
||||
const res = await fetch('https://api.github.com/repos/vercel/next.js')
|
||||
const repo = await res.json()
|
||||
// Pass data to the page via props
|
||||
return { props: { repo } }
|
||||
}
|
||||
|
||||
export default function Page({ repo }) {
|
||||
return (
|
||||
<main>
|
||||
<p>{repo.stargazers_count}</p>
|
||||
</main>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
You can import modules in top-level scope for use in `getServerSideProps`. Imports used will **not be bundled for the client-side**. This means you can write **server-side code directly in `getServerSideProps`**, including fetching data from your database.
|
||||
|
||||
## Context parameter
|
||||
|
||||
The `context` parameter is an object containing the following keys:
|
||||
|
||||
| Name | Description |
|
||||
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `params` | If this page uses a [dynamic route](/docs/pages/building-your-application/routing/dynamic-routes), `params` contains the route parameters. If the page name is `[id].js`, then `params` will look like `{ id: ... }`. |
|
||||
| `req` | [The `HTTP` IncomingMessage object](https://nodejs.org/api/http.html#http_class_http_incomingmessage), with an additional `cookies` prop, which is an object with string keys mapping to string values of cookies. |
|
||||
| `res` | [The `HTTP` response object](https://nodejs.org/api/http.html#http_class_http_serverresponse). |
|
||||
| `query` | An object representing the query string, including dynamic route parameters. |
|
||||
| `preview` | (Deprecated for `draftMode`) `preview` is `true` if the page is in the [Preview Mode](/docs/pages/guides/preview-mode) and `false` otherwise. |
|
||||
| `previewData` | (Deprecated for `draftMode`) The [preview](/docs/pages/guides/preview-mode) data set by `setPreviewData`. |
|
||||
| `draftMode` | `draftMode` is `true` if the page is in the [Draft Mode](/docs/pages/guides/draft-mode) and `false` otherwise. |
|
||||
| `resolvedUrl` | A normalized version of the request `URL` that strips the `_next/data` prefix for client transitions and includes original query values. |
|
||||
| `locale` | Contains the active locale (if enabled). |
|
||||
| `locales` | Contains all supported locales (if enabled). |
|
||||
| `defaultLocale` | Contains the configured default locale (if enabled). |
|
||||
|
||||
## getServerSideProps return values
|
||||
|
||||
The `getServerSideProps` function should return an object with **any one of the following** properties:
|
||||
|
||||
### `props`
|
||||
|
||||
The `props` object is a key-value pair, where each value is received by the page component. It should be a [serializable object](https://developer.mozilla.org/docs/Glossary/Serialization) so that any props passed, could be serialized with [`JSON.stringify`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify).
|
||||
|
||||
```jsx
|
||||
export async function getServerSideProps(context) {
|
||||
return {
|
||||
props: { message: `Next.js is awesome` }, // will be passed to the page component as props
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `notFound`
|
||||
|
||||
The `notFound` boolean allows the page to return a `404` status and [404 Page](/docs/pages/building-your-application/routing/custom-error#404-page). With `notFound: true`, the page will return a `404` even if there was a successfully generated page before. This is meant to support use cases like user-generated content getting removed by its author.
|
||||
|
||||
```js
|
||||
export async function getServerSideProps(context) {
|
||||
const res = await fetch(`https://.../data`)
|
||||
const data = await res.json()
|
||||
|
||||
if (!data) {
|
||||
return {
|
||||
notFound: true,
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
props: { data }, // will be passed to the page component as props
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `redirect`
|
||||
|
||||
The `redirect` object allows redirecting to internal and external resources. It should match the shape of `{ destination: string, permanent: boolean }`. 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.
|
||||
|
||||
```js
|
||||
export async function getServerSideProps(context) {
|
||||
const res = await fetch(`https://.../data`)
|
||||
const data = await res.json()
|
||||
|
||||
if (!data) {
|
||||
return {
|
||||
redirect: {
|
||||
destination: '/',
|
||||
permanent: false,
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
props: {}, // will be passed to the page component as props
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Version History
|
||||
|
||||
| Version | Changes |
|
||||
| --------- | ------------------------------------------------------------------------------------------------- |
|
||||
| `v13.4.0` | [App Router](/docs/app/getting-started/fetching-data) is now stable with simplified data fetching |
|
||||
| `v10.0.0` | `locale`, `locales`, `defaultLocale`, and `notFound` options added. |
|
||||
| `v9.3.0` | `getServerSideProps` introduced. |
|
||||
Generated
Vendored
+259
@@ -0,0 +1,259 @@
|
||||
---
|
||||
title: getStaticPaths
|
||||
description: API reference for `getStaticPaths`. Learn how to fetch data and generate static pages with `getStaticPaths`.
|
||||
---
|
||||
|
||||
When exporting a function called `getStaticPaths` from a page that uses [Dynamic Routes](/docs/pages/building-your-application/routing/dynamic-routes), Next.js will statically prerender all the paths specified by `getStaticPaths`.
|
||||
|
||||
```tsx filename="pages/repo/[name].tsx" switcher
|
||||
import type {
|
||||
InferGetStaticPropsType,
|
||||
GetStaticProps,
|
||||
GetStaticPaths,
|
||||
} from 'next'
|
||||
|
||||
type Repo = {
|
||||
name: string
|
||||
stargazers_count: number
|
||||
}
|
||||
|
||||
export const getStaticPaths = (async () => {
|
||||
return {
|
||||
paths: [
|
||||
{
|
||||
params: {
|
||||
name: 'next.js',
|
||||
},
|
||||
}, // See the "paths" section below
|
||||
],
|
||||
fallback: true, // false or "blocking"
|
||||
}
|
||||
}) satisfies GetStaticPaths
|
||||
|
||||
export const getStaticProps = (async (context) => {
|
||||
const res = await fetch('https://api.github.com/repos/vercel/next.js')
|
||||
const repo = await res.json()
|
||||
return { props: { repo } }
|
||||
}) satisfies GetStaticProps<{
|
||||
repo: Repo
|
||||
}>
|
||||
|
||||
export default function Page({
|
||||
repo,
|
||||
}: InferGetStaticPropsType<typeof getStaticProps>) {
|
||||
return repo.stargazers_count
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="pages/repo/[name].js" switcher
|
||||
export async function getStaticPaths() {
|
||||
return {
|
||||
paths: [
|
||||
{
|
||||
params: {
|
||||
name: 'next.js',
|
||||
},
|
||||
}, // See the "paths" section below
|
||||
],
|
||||
fallback: true, // false or "blocking"
|
||||
}
|
||||
}
|
||||
|
||||
export async function getStaticProps() {
|
||||
const res = await fetch('https://api.github.com/repos/vercel/next.js')
|
||||
const repo = await res.json()
|
||||
return { props: { repo } }
|
||||
}
|
||||
|
||||
export default function Page({ repo }) {
|
||||
return repo.stargazers_count
|
||||
}
|
||||
```
|
||||
|
||||
## getStaticPaths return values
|
||||
|
||||
The `getStaticPaths` function should return an object with the following **required** properties:
|
||||
|
||||
### `paths`
|
||||
|
||||
The `paths` key determines which paths will be prerendered. For example, suppose that you have a page that uses [Dynamic Routes](/docs/pages/building-your-application/routing/dynamic-routes) named `pages/posts/[id].js`. If you export `getStaticPaths` from this page and return the following for `paths`:
|
||||
|
||||
```js
|
||||
return {
|
||||
paths: [
|
||||
{ params: { id: '1' }},
|
||||
{
|
||||
params: { id: '2' },
|
||||
// with i18n configured the locale for the path can be returned as well
|
||||
locale: "en",
|
||||
},
|
||||
],
|
||||
fallback: ...
|
||||
}
|
||||
```
|
||||
|
||||
Then, Next.js will statically generate `/posts/1` and `/posts/2` during `next build` using the page component in `pages/posts/[id].js`.
|
||||
|
||||
The value for each `params` object must match the parameters used in the page name:
|
||||
|
||||
- If the page name is `pages/posts/[postId]/[commentId]`, then `params` should contain `postId` and `commentId`.
|
||||
- If the page name uses [catch-all routes](/docs/pages/building-your-application/routing/dynamic-routes#catch-all-segments) like `pages/[...slug]`, then `params` should contain `slug` (which is an array). If this array is `['hello', 'world']`, then Next.js will statically generate the page at `/hello/world`.
|
||||
- If the page uses an [optional catch-all route](/docs/pages/building-your-application/routing/dynamic-routes#optional-catch-all-segments), use `null`, `[]`, `undefined` or `false` to render the root-most route. For example, if you supply `slug: false` for `pages/[[...slug]]`, Next.js will statically generate the page `/`.
|
||||
|
||||
The `params` strings are **case-sensitive** and ideally should be normalized to ensure the paths are generated correctly. For example, if `WoRLD` is returned for a param it will only match if `WoRLD` is the actual path visited, not `world` or `World`.
|
||||
|
||||
Separate of the `params` object a `locale` field can be returned when [i18n is configured](/docs/pages/guides/internationalization), which configures the locale for the path being generated.
|
||||
|
||||
### `fallback: false`
|
||||
|
||||
If `fallback` is `false`, then any paths not returned by `getStaticPaths` will result in a **404 page**.
|
||||
|
||||
When `next build` is run, Next.js will check if `getStaticPaths` returned `fallback: false`, it will then build **only** the paths returned by `getStaticPaths`. This option is useful if you have a small number of paths to create, or new page data is not added often. If you find that you need to add more paths, and you have `fallback: false`, you will need to run `next build` again so that the new paths can be generated.
|
||||
|
||||
The following example prerenders one blog post per page called `pages/posts/[id].js`. The list of blog posts will be fetched from a CMS and returned by `getStaticPaths`. Then, for each page, it fetches the post data from a CMS using [`getStaticProps`](/docs/pages/building-your-application/data-fetching/get-static-props).
|
||||
|
||||
```jsx filename="pages/posts/[id].js"
|
||||
function Post({ post }) {
|
||||
// Render post...
|
||||
}
|
||||
|
||||
// This function gets called at build time
|
||||
export async function getStaticPaths() {
|
||||
// Call an external API endpoint to get posts
|
||||
const res = await fetch('https://.../posts')
|
||||
const posts = await res.json()
|
||||
|
||||
// Get the paths we want to prerender based on posts
|
||||
const paths = posts.map((post) => ({
|
||||
params: { id: post.id },
|
||||
}))
|
||||
|
||||
// We'll prerender only these paths at build time.
|
||||
// { fallback: false } means other routes should 404.
|
||||
return { paths, fallback: false }
|
||||
}
|
||||
|
||||
// This also gets called at build time
|
||||
export async function getStaticProps({ params }) {
|
||||
// params contains the post `id`.
|
||||
// If the route is like /posts/1, then params.id is 1
|
||||
const res = await fetch(`https://.../posts/${params.id}`)
|
||||
const post = await res.json()
|
||||
|
||||
// Pass post data to the page via props
|
||||
return { props: { post } }
|
||||
}
|
||||
|
||||
export default Post
|
||||
```
|
||||
|
||||
### `fallback: true`
|
||||
|
||||
<details>
|
||||
<summary>Examples</summary>
|
||||
|
||||
- [Static generation of a large number of pages](https://react-tweet.vercel.app/)
|
||||
|
||||
</details>
|
||||
|
||||
If `fallback` is `true`, then the behavior of `getStaticProps` changes in the following ways:
|
||||
|
||||
- The paths returned from `getStaticPaths` will be rendered to `HTML` at build time by `getStaticProps`.
|
||||
- The paths that have not been generated at build time will **not** result in a 404 page. Instead, Next.js will serve a [“fallback”](#fallback-pages) version of the page on the first request to such a path. Web crawlers, such as Google, won't be served a fallback and instead the path will behave as in [`fallback: 'blocking'`](#fallback-blocking).
|
||||
- When a page with `fallback: true` is navigated to through `next/link` or `next/router` (client-side) Next.js will _not_ serve a fallback and instead the page will behave as [`fallback: 'blocking'`](#fallback-blocking).
|
||||
- In the background, Next.js will statically generate the requested path `HTML` and `JSON`. This includes running `getStaticProps`.
|
||||
- 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 prerendered pages. Subsequent requests to the same path will serve the generated page, like other pages prerendered at build time.
|
||||
|
||||
> **Good to know**: `fallback: true` is not supported when using [`output: 'export'`](/docs/pages/guides/static-exports).
|
||||
|
||||
#### When is `fallback: true` useful?
|
||||
|
||||
`fallback: true` is useful if your app has a very large number of static pages that depend on data (such as a very large e-commerce site). If you want to prerender all product pages, the builds would take a very long time.
|
||||
|
||||
Instead, you may statically generate a small subset of pages and use `fallback: true` for the rest. When someone requests a page that is not generated yet, the user will see the page with a loading indicator or skeleton component.
|
||||
|
||||
Shortly after, `getStaticProps` finishes and the page will be rendered with the requested data. From now on, everyone who requests the same page will get the statically prerendered page.
|
||||
|
||||
This ensures that users always have a fast experience while preserving fast builds and the benefits of Static Generation.
|
||||
|
||||
`fallback: true` will not _update_ generated pages, for that take a look at [Incremental Static Regeneration](/docs/pages/guides/incremental-static-regeneration).
|
||||
|
||||
### `fallback: 'blocking'`
|
||||
|
||||
If `fallback` is `'blocking'`, new paths not returned by `getStaticPaths` will wait for the `HTML` to be generated, identical to SSR (hence why _blocking_), and then be cached for future requests so it only happens once per path.
|
||||
|
||||
`getStaticProps` will behave as follows:
|
||||
|
||||
- The paths returned from `getStaticPaths` will be rendered to `HTML` at build time by `getStaticProps`.
|
||||
- The paths that have not been generated at build time will **not** result in a 404 page. Instead, Next.js will SSR on the first request and return the generated `HTML`.
|
||||
- When complete, the browser receives the `HTML` for the generated path. From the user’s perspective, it will transition from "the browser is requesting the page" to "the full page is loaded". There is no flash of loading/fallback state.
|
||||
- At the same time, Next.js adds this path to the list of prerendered pages. Subsequent requests to the same path will serve the generated page, like other pages prerendered at build time.
|
||||
|
||||
`fallback: 'blocking'` will not _update_ generated pages by default. To update generated pages, use [Incremental Static Regeneration](/docs/pages/guides/incremental-static-regeneration) in conjunction with `fallback: 'blocking'`.
|
||||
|
||||
> **Good to know**: `fallback: 'blocking'` is not supported when using [`output: 'export'`](/docs/pages/guides/static-exports).
|
||||
|
||||
### Fallback pages
|
||||
|
||||
In the “fallback” version of a page:
|
||||
|
||||
- The page’s props will be empty.
|
||||
- Using the [router](/docs/pages/api-reference/functions/use-router), you can detect if the fallback is being rendered, `router.isFallback` will be `true`.
|
||||
|
||||
The following example showcases using `isFallback`:
|
||||
|
||||
```jsx filename="pages/posts/[id].js"
|
||||
import { useRouter } from 'next/router'
|
||||
|
||||
function Post({ post }) {
|
||||
const router = useRouter()
|
||||
|
||||
// If the page is not yet generated, this will be displayed
|
||||
// initially until getStaticProps() finishes running
|
||||
if (router.isFallback) {
|
||||
return <div>Loading...</div>
|
||||
}
|
||||
|
||||
// Render post...
|
||||
}
|
||||
|
||||
// This function gets called at build time
|
||||
export async function getStaticPaths() {
|
||||
return {
|
||||
// Only `/posts/1` and `/posts/2` are generated at build time
|
||||
paths: [{ params: { id: '1' } }, { params: { id: '2' } }],
|
||||
// Enable statically generating additional pages
|
||||
// For example: `/posts/3`
|
||||
fallback: true,
|
||||
}
|
||||
}
|
||||
|
||||
// This also gets called at build time
|
||||
export async function getStaticProps({ params }) {
|
||||
// params contains the post `id`.
|
||||
// If the route is like /posts/1, then params.id is 1
|
||||
const res = await fetch(`https://.../posts/${params.id}`)
|
||||
const post = await res.json()
|
||||
|
||||
// Pass post data to the page via props
|
||||
return {
|
||||
props: { post },
|
||||
// Re-generate the post at most once per second
|
||||
// if a request comes in
|
||||
revalidate: 1,
|
||||
}
|
||||
}
|
||||
|
||||
export default Post
|
||||
```
|
||||
|
||||
## Version History
|
||||
|
||||
| Version | Changes |
|
||||
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `v13.4.0` | [App Router](/docs/app/getting-started/fetching-data) is now stable with simplified data fetching, including [`generateStaticParams()`](/docs/app/api-reference/functions/generate-static-params) |
|
||||
| `v12.2.0` | [On-Demand Incremental Static Regeneration](/docs/pages/guides/incremental-static-regeneration#on-demand-revalidation-with-revalidatepath) is stable. |
|
||||
| `v12.1.0` | [On-Demand Incremental Static Regeneration](/docs/pages/guides/incremental-static-regeneration#on-demand-revalidation-with-revalidatepath) added (beta). |
|
||||
| `v9.5.0` | Stable [Incremental Static Regeneration](/docs/pages/guides/incremental-static-regeneration) |
|
||||
| `v9.3.0` | `getStaticPaths` introduced. |
|
||||
Generated
Vendored
+229
@@ -0,0 +1,229 @@
|
||||
---
|
||||
title: getStaticProps
|
||||
description: API reference for `getStaticProps`. Learn how to use `getStaticProps` to generate static pages with Next.js.
|
||||
---
|
||||
|
||||
Exporting a function called `getStaticProps` will prerender a page at build time using the props returned from the function:
|
||||
|
||||
```tsx filename="pages/index.tsx" switcher
|
||||
import type { InferGetStaticPropsType, GetStaticProps } from 'next'
|
||||
|
||||
type Repo = {
|
||||
name: string
|
||||
stargazers_count: number
|
||||
}
|
||||
|
||||
export const getStaticProps = (async (context) => {
|
||||
const res = await fetch('https://api.github.com/repos/vercel/next.js')
|
||||
const repo = await res.json()
|
||||
return { props: { repo } }
|
||||
}) satisfies GetStaticProps<{
|
||||
repo: Repo
|
||||
}>
|
||||
|
||||
export default function Page({
|
||||
repo,
|
||||
}: InferGetStaticPropsType<typeof getStaticProps>) {
|
||||
return repo.stargazers_count
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="pages/index.js" switcher
|
||||
export async function getStaticProps() {
|
||||
const res = await fetch('https://api.github.com/repos/vercel/next.js')
|
||||
const repo = await res.json()
|
||||
return { props: { repo } }
|
||||
}
|
||||
|
||||
export default function Page({ repo }) {
|
||||
return repo.stargazers_count
|
||||
}
|
||||
```
|
||||
|
||||
You can import modules in top-level scope for use in `getStaticProps`. Imports used will **not be bundled for the client-side**. This means you can write **server-side code directly in `getStaticProps`**, including fetching data from your database.
|
||||
|
||||
## Context parameter
|
||||
|
||||
The `context` parameter is an object containing the following keys:
|
||||
|
||||
| Name | Description |
|
||||
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `params` | Contains the route parameters for pages using [dynamic routes](/docs/pages/building-your-application/routing/dynamic-routes). For example, if the page name is `[id].js`, then `params` will look like `{ id: ... }`. You should use this together with `getStaticPaths`, which we'll explain later. |
|
||||
| `preview` | (Deprecated for `draftMode`) `preview` is `true` if the page is in the [Preview Mode](/docs/pages/guides/preview-mode) and `false` otherwise. |
|
||||
| `previewData` | (Deprecated for `draftMode`) The [preview](/docs/pages/guides/preview-mode) data set by `setPreviewData`. |
|
||||
| `draftMode` | `draftMode` is `true` if the page is in the [Draft Mode](/docs/pages/guides/draft-mode) and `false` otherwise. |
|
||||
| `locale` | Contains the active locale (if enabled). |
|
||||
| `locales` | Contains all supported locales (if enabled). |
|
||||
| `defaultLocale` | Contains the configured default locale (if enabled). |
|
||||
| `revalidateReason` | Provides a reason for why the function was called. Can be one of: "build" (run at build time), "stale" (revalidate period expired, or running in [development mode](/docs/pages/building-your-application/data-fetching/get-static-props#runs-on-every-request-in-development)), "on-demand" (triggered via [on-demand revalidation](/docs/pages/guides/incremental-static-regeneration#on-demand-revalidation-with-revalidatepath)) |
|
||||
|
||||
## getStaticProps return values
|
||||
|
||||
The `getStaticProps` function should return an object containing either `props`, `redirect`, or `notFound` followed by an **optional** `revalidate` property.
|
||||
|
||||
### `props`
|
||||
|
||||
The `props` object is a key-value pair, where each value is received by the page component. It should be a [serializable object](https://developer.mozilla.org/docs/Glossary/Serialization) so that any props passed, could be serialized with [`JSON.stringify`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify).
|
||||
|
||||
```jsx
|
||||
export async function getStaticProps(context) {
|
||||
return {
|
||||
props: { message: `Next.js is awesome` }, // will be passed to the page component as props
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `revalidate`
|
||||
|
||||
The `revalidate` property is the amount in seconds after which a page re-generation can occur (defaults to `false` or no revalidation).
|
||||
|
||||
```js
|
||||
// This function gets called at build time on server-side.
|
||||
// It may be called again, on a serverless function, if
|
||||
// revalidation is enabled and a new request comes in
|
||||
export async function getStaticProps() {
|
||||
const res = await fetch('https://.../posts')
|
||||
const posts = await res.json()
|
||||
|
||||
return {
|
||||
props: {
|
||||
posts,
|
||||
},
|
||||
// Next.js will attempt to re-generate the page:
|
||||
// - When a request comes in
|
||||
// - At most once every 10 seconds
|
||||
revalidate: 10, // In seconds
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Learn more about [Incremental Static Regeneration](/docs/pages/guides/incremental-static-regeneration).
|
||||
|
||||
The cache status of a page leveraging ISR can be determined by reading the value of the `x-nextjs-cache` response header. The possible values are the following:
|
||||
|
||||
- `MISS` - the path is not in the cache (occurs at most once, on the first visit)
|
||||
- `STALE` - the path is in the cache but exceeded the revalidate time so it will be updated in the background
|
||||
- `HIT` - the path is in the cache and has not exceeded the revalidate time
|
||||
|
||||
### `notFound`
|
||||
|
||||
The `notFound` boolean allows the page to return a `404` status and [404 Page](/docs/pages/building-your-application/routing/custom-error#404-page). With `notFound: true`, the page will return a `404` even if there was a successfully generated page before. This is meant to support use cases like user-generated content getting removed by its author. Note, `notFound` follows the same `revalidate` behavior [described here](#revalidate).
|
||||
|
||||
```js
|
||||
export async function getStaticProps(context) {
|
||||
const res = await fetch(`https://.../data`)
|
||||
const data = await res.json()
|
||||
|
||||
if (!data) {
|
||||
return {
|
||||
notFound: true,
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
props: { data }, // will be passed to the page component as props
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **Good to know**: `notFound` is not needed for [`fallback: false`](/docs/pages/api-reference/functions/get-static-paths#fallback-false) mode as only paths returned from `getStaticPaths` will be prerendered.
|
||||
|
||||
### `redirect`
|
||||
|
||||
The `redirect` object allows redirecting to internal or external resources. It should match the shape of `{ destination: string, permanent: boolean }`.
|
||||
|
||||
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**. You can also set `basePath: false` similar to redirects in `next.config.js`.
|
||||
|
||||
```js
|
||||
export async function getStaticProps(context) {
|
||||
const res = await fetch(`https://...`)
|
||||
const data = await res.json()
|
||||
|
||||
if (!data) {
|
||||
return {
|
||||
redirect: {
|
||||
destination: '/',
|
||||
permanent: false,
|
||||
// statusCode: 301
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
props: { data }, // will be passed to the page component as props
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If the redirects are known at build-time, they should be added in [`next.config.js`](/docs/pages/api-reference/config/next-config-js/redirects) instead.
|
||||
|
||||
## Reading files: Use `process.cwd()`
|
||||
|
||||
Files can be read directly from the filesystem in `getStaticProps`.
|
||||
|
||||
In order to do so you have to get the full path to a file.
|
||||
|
||||
Since Next.js compiles your code into a separate directory you can't use `__dirname` as the path it returns will be different from the Pages Router.
|
||||
|
||||
Instead you can use `process.cwd()` which gives you the directory where Next.js is being executed.
|
||||
|
||||
```jsx
|
||||
import { promises as fs } from 'fs'
|
||||
import path from 'path'
|
||||
|
||||
// posts will be populated at build time by getStaticProps()
|
||||
function Blog({ posts }) {
|
||||
return (
|
||||
<ul>
|
||||
{posts.map((post) => (
|
||||
<li>
|
||||
<h3>{post.filename}</h3>
|
||||
<p>{post.content}</p>
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
)
|
||||
}
|
||||
|
||||
// This function gets called at build time on server-side.
|
||||
// It won't be called on client-side, so you can even do
|
||||
// direct database queries.
|
||||
export async function getStaticProps() {
|
||||
const postsDirectory = path.join(process.cwd(), 'posts')
|
||||
const filenames = await fs.readdir(postsDirectory)
|
||||
|
||||
const posts = filenames.map(async (filename) => {
|
||||
const filePath = path.join(postsDirectory, filename)
|
||||
const fileContents = await fs.readFile(filePath, 'utf8')
|
||||
|
||||
// Generally you would parse/transform the contents
|
||||
// For example you can transform markdown to HTML here
|
||||
|
||||
return {
|
||||
filename,
|
||||
content: fileContents,
|
||||
}
|
||||
})
|
||||
// By returning { props: { posts } }, the Blog component
|
||||
// will receive `posts` as a prop at build time
|
||||
return {
|
||||
props: {
|
||||
posts: await Promise.all(posts),
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
export default Blog
|
||||
```
|
||||
|
||||
## Version History
|
||||
|
||||
| Version | Changes |
|
||||
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `v13.4.0` | [App Router](/docs/app/getting-started/fetching-data) is now stable with simplified data fetching |
|
||||
| `v12.2.0` | [On-Demand Incremental Static Regeneration](/docs/pages/guides/incremental-static-regeneration#on-demand-revalidation-with-revalidatepath) is stable. |
|
||||
| `v12.1.0` | [On-Demand Incremental Static Regeneration](/docs/pages/guides/incremental-static-regeneration#on-demand-revalidation-with-revalidatepath) added (beta). |
|
||||
| `v10.0.0` | `locale`, `locales`, `defaultLocale`, and `notFound` options added. |
|
||||
| `v10.0.0` | `fallback: 'blocking'` return option added. |
|
||||
| `v9.5.0` | Stable [Incremental Static Regeneration](/docs/pages/guides/incremental-static-regeneration) |
|
||||
| `v9.3.0` | `getStaticProps` introduced. |
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Functions
|
||||
description: API Reference for Functions and Hooks in Pages Router.
|
||||
source: app/api-reference/functions
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: NextRequest
|
||||
description: API Reference for NextRequest.
|
||||
source: app/api-reference/functions/next-request
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: NextResponse
|
||||
description: API Reference for NextResponse.
|
||||
source: app/api-reference/functions/next-response
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+242
@@ -0,0 +1,242 @@
|
||||
---
|
||||
title: useParams
|
||||
description: API Reference for the useParams hook in the Pages Router.
|
||||
---
|
||||
|
||||
`useParams` is a hook that lets you read a route's [dynamic params](/docs/pages/building-your-application/routing/dynamic-routes) filled in by the current URL.
|
||||
|
||||
```tsx filename="pages/shop/[slug].tsx" switcher
|
||||
import { useParams } from 'next/navigation'
|
||||
|
||||
export default function ShopPage() {
|
||||
const params = useParams<{ slug: string }>()
|
||||
|
||||
if (!params) {
|
||||
// Render fallback UI while params are not yet available
|
||||
return null
|
||||
}
|
||||
|
||||
// Route -> /shop/[slug]
|
||||
// URL -> /shop/shoes
|
||||
// `params` -> { slug: 'shoes' }
|
||||
return <>Shop: {params.slug}</>
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="pages/shop/[slug].js" switcher
|
||||
import { useParams } from 'next/navigation'
|
||||
|
||||
export default function ShopPage() {
|
||||
const params = useParams()
|
||||
|
||||
if (!params) {
|
||||
// Render fallback UI while params are not yet available
|
||||
return null
|
||||
}
|
||||
|
||||
// Route -> /shop/[slug]
|
||||
// URL -> /shop/shoes
|
||||
// `params` -> { slug: 'shoes' }
|
||||
return <>Shop: {params.slug}</>
|
||||
}
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
```tsx
|
||||
const params = useParams()
|
||||
```
|
||||
|
||||
`useParams` does not take any parameters.
|
||||
|
||||
## Returns
|
||||
|
||||
`useParams` returns an object containing the current route's filled in [dynamic parameters](/docs/pages/building-your-application/routing/dynamic-routes), or `null` during [prerendering](#behavior-during-prerendering).
|
||||
|
||||
- Each property in the object is an active dynamic segment.
|
||||
- The property name is the segment's name, and the property value is what the segment is filled in with.
|
||||
- The property value will either be a `string` or array of `string`s depending on the [type of dynamic segment](/docs/pages/building-your-application/routing/dynamic-routes).
|
||||
- If the route contains no dynamic parameters, `useParams` returns an empty object.
|
||||
|
||||
For example:
|
||||
|
||||
| Route | URL | `useParams()` |
|
||||
| ---------------------------- | ----------- | ------------------------- |
|
||||
| `pages/shop/page.js` | `/shop` | `{}` |
|
||||
| `pages/shop/[slug].js` | `/shop/1` | `{ slug: '1' }` |
|
||||
| `pages/shop/[tag]/[item].js` | `/shop/1/2` | `{ tag: '1', item: '2' }` |
|
||||
| `pages/shop/[...slug].js` | `/shop/1/2` | `{ slug: ['1', '2'] }` |
|
||||
|
||||
> **Good to know**: `useParams` is a [React Hook](https://react.dev/learn#using-hooks) and cannot be used with classes.
|
||||
|
||||
## Behavior
|
||||
|
||||
### Behavior during prerendering
|
||||
|
||||
For pages that are [statically optimized](/docs/pages/building-your-application/rendering/automatic-static-optimization), `useParams` will return `null` on the initial render. After hydration, the value will be updated to the actual params once the router is ready.
|
||||
|
||||
This is because params cannot be known during static generation for dynamic routes.
|
||||
|
||||
```tsx filename="pages/shop/[slug].tsx" switcher
|
||||
import { useParams } from 'next/navigation'
|
||||
|
||||
export default function ShopPage() {
|
||||
const params = useParams<{ slug: string }>()
|
||||
|
||||
if (!params) {
|
||||
// Return a fallback UI while params are loading
|
||||
// This prevents hydration mismatches
|
||||
return <ShopPageSkeleton />
|
||||
}
|
||||
|
||||
return <>Shop: {params.slug}</>
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="pages/shop/[slug].js" switcher
|
||||
import { useParams } from 'next/navigation'
|
||||
|
||||
export default function ShopPage() {
|
||||
const params = useParams()
|
||||
|
||||
if (!params) {
|
||||
// Return a fallback UI while params are loading
|
||||
// This prevents hydration mismatches
|
||||
return <ShopPageSkeleton />
|
||||
}
|
||||
|
||||
return <>Shop: {params.slug}</>
|
||||
}
|
||||
```
|
||||
|
||||
### Using with `getServerSideProps`
|
||||
|
||||
When using [`getServerSideProps`](/docs/pages/building-your-application/data-fetching/get-server-side-props), the page is server-rendered on each request and `useParams` will return the actual params immediately:
|
||||
|
||||
```tsx filename="pages/shop/[slug].tsx" switcher
|
||||
import { useParams } from 'next/navigation'
|
||||
|
||||
export default function ShopPage() {
|
||||
const params = useParams<{ slug: string }>()
|
||||
|
||||
// With getServerSideProps, this fallback is never rendered because
|
||||
// params is always available on the server. However, keeping
|
||||
// the fallback allows this component to be reused on other pages
|
||||
// that may not use getServerSideProps.
|
||||
if (!params) {
|
||||
return null
|
||||
}
|
||||
|
||||
return <>Shop: {params.slug}</>
|
||||
}
|
||||
|
||||
export async function getServerSideProps() {
|
||||
return { props: {} }
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="pages/shop/[slug].js" switcher
|
||||
import { useParams } from 'next/navigation'
|
||||
|
||||
export default function ShopPage() {
|
||||
const params = useParams()
|
||||
|
||||
// With getServerSideProps, this fallback is never rendered because
|
||||
// params is always available on the server. However, keeping
|
||||
// the fallback allows this component to be reused on other pages
|
||||
// that may not use getServerSideProps.
|
||||
if (!params) {
|
||||
return null
|
||||
}
|
||||
|
||||
return <>Shop: {params.slug}</>
|
||||
}
|
||||
|
||||
export async function getServerSideProps() {
|
||||
return { props: {} }
|
||||
}
|
||||
```
|
||||
|
||||
### Comparison with `router.query`
|
||||
|
||||
`useParams` only returns the dynamic route parameters, whereas [`router.query`](/docs/pages/api-reference/functions/use-router#router-object) from `useRouter` includes both dynamic parameters and query string parameters.
|
||||
|
||||
```tsx filename="pages/shop/[slug].tsx" switcher
|
||||
import { useRouter } from 'next/router'
|
||||
import { useParams } from 'next/navigation'
|
||||
|
||||
export default function ShopPage() {
|
||||
const router = useRouter()
|
||||
const params = useParams()
|
||||
|
||||
// URL -> /shop/shoes?color=red
|
||||
|
||||
// router.query -> { slug: 'shoes', color: 'red' }
|
||||
// params -> { slug: 'shoes' }
|
||||
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="pages/shop/[slug].js" switcher
|
||||
import { useRouter } from 'next/router'
|
||||
import { useParams } from 'next/navigation'
|
||||
|
||||
export default function ShopPage() {
|
||||
const router = useRouter()
|
||||
const params = useParams()
|
||||
|
||||
// URL -> /shop/shoes?color=red
|
||||
|
||||
// router.query -> { slug: 'shoes', color: 'red' }
|
||||
// params -> { slug: 'shoes' }
|
||||
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Sharing components with App Router
|
||||
|
||||
`useParams` from `next/navigation` works in both the Pages Router and App Router. This allows you to create shared components that work in either context:
|
||||
|
||||
```tsx filename="components/breadcrumb.tsx" switcher
|
||||
import { useParams } from 'next/navigation'
|
||||
|
||||
// This component works in both pages/ and app/
|
||||
export function Breadcrumb() {
|
||||
const params = useParams<{ slug: string }>()
|
||||
|
||||
if (!params) {
|
||||
// Fallback for Pages Router during prerendering
|
||||
return <nav>Home / ...</nav>
|
||||
}
|
||||
|
||||
return <nav>Home / {params.slug}</nav>
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="components/breadcrumb.js" switcher
|
||||
import { useParams } from 'next/navigation'
|
||||
|
||||
// This component works in both pages/ and app/
|
||||
export function Breadcrumb() {
|
||||
const params = useParams()
|
||||
|
||||
if (!params) {
|
||||
// Fallback for Pages Router during prerendering
|
||||
return <nav>Home / ...</nav>
|
||||
}
|
||||
|
||||
return <nav>Home / {params.slug}</nav>
|
||||
}
|
||||
```
|
||||
|
||||
> **Good to know**: When using this component in the App Router, `useParams` never returns `null`, so the fallback branch will not be rendered.
|
||||
|
||||
## Version History
|
||||
|
||||
| Version | Changes |
|
||||
| --------- | ----------------------- |
|
||||
| `v13.3.0` | `useParams` introduced. |
|
||||
frontend/node_modules/next/dist/docs/02-pages/04-api-reference/03-functions/use-report-web-vitals.md
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: useReportWebVitals
|
||||
description: useReportWebVitals
|
||||
source: app/api-reference/functions/use-report-web-vitals
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+588
@@ -0,0 +1,588 @@
|
||||
---
|
||||
title: useRouter
|
||||
description: Learn more about the API of the Next.js Router, and access the router instance in your page with the useRouter hook.
|
||||
---
|
||||
|
||||
If you want to access the [`router` object](#router-object) inside any function component in your app, you can use the `useRouter` hook, take a look at the following example:
|
||||
|
||||
```jsx
|
||||
import { useRouter } from 'next/router'
|
||||
|
||||
function ActiveLink({ children, href }) {
|
||||
const router = useRouter()
|
||||
const style = {
|
||||
marginRight: 10,
|
||||
color: router.asPath === href ? 'red' : 'black',
|
||||
}
|
||||
|
||||
const handleClick = (e) => {
|
||||
e.preventDefault()
|
||||
router.push(href)
|
||||
}
|
||||
|
||||
return (
|
||||
<a href={href} onClick={handleClick} style={style}>
|
||||
{children}
|
||||
</a>
|
||||
)
|
||||
}
|
||||
|
||||
export default ActiveLink
|
||||
```
|
||||
|
||||
> `useRouter` is a [React Hook](https://react.dev/learn#using-hooks), meaning it cannot be used with classes. You can either use [withRouter](#withrouter) or wrap your class in a function component.
|
||||
|
||||
## `router` object
|
||||
|
||||
The following is the definition of the `router` object returned by both [`useRouter`](#top) and [`withRouter`](#withrouter):
|
||||
|
||||
- `pathname`: `String` - The path for current route file that comes after `/pages`. Therefore, `basePath`, `locale` and trailing slash (`trailingSlash: true`) are not included.
|
||||
- `query`: `Object` - The query string parsed to an object, including [dynamic route](/docs/pages/building-your-application/routing/dynamic-routes) parameters. It will be an empty object during prerendering if the page doesn't use [Server-side Rendering](/docs/pages/building-your-application/data-fetching/get-server-side-props). Defaults to `{}`
|
||||
- `asPath`: `String` - The path as shown in the browser including the search params and respecting the `trailingSlash` configuration. `basePath` and `locale` are not included.
|
||||
- `isFallback`: `boolean` - Whether the current page is in [fallback mode](/docs/pages/api-reference/functions/get-static-paths#fallback-true).
|
||||
- `basePath`: `String` - The active [basePath](/docs/app/api-reference/config/next-config-js/basePath) (if enabled).
|
||||
- `locale`: `String` - The active locale (if enabled).
|
||||
- `locales`: `String[]` - All supported locales (if enabled).
|
||||
- `defaultLocale`: `String` - The current default locale (if enabled).
|
||||
- `domainLocales`: `Array<{domain, defaultLocale, locales}>` - Any configured domain locales.
|
||||
- `isReady`: `boolean` - Whether the router fields are updated client-side and ready for use. Should only be used inside of `useEffect` methods and not for conditionally rendering on the server. See related docs for use case with [automatically statically optimized pages](/docs/pages/building-your-application/rendering/automatic-static-optimization)
|
||||
- `isPreview`: `boolean` - Whether the application is currently in [preview mode](/docs/pages/guides/preview-mode).
|
||||
|
||||
> Using the `asPath` field may lead to a mismatch between client and server if the page is rendered using server-side rendering or [automatic static optimization](/docs/pages/building-your-application/rendering/automatic-static-optimization). Avoid using `asPath` until the `isReady` field is `true`.
|
||||
|
||||
The following methods are included inside `router`:
|
||||
|
||||
### router.push
|
||||
|
||||
Handles client-side transitions, this method is useful for cases where [`next/link`](/docs/pages/api-reference/components/link) is not enough.
|
||||
|
||||
```js
|
||||
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).
|
||||
- `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.
|
||||
- `options` - Optional object with the following configuration options:
|
||||
- `scroll` - Optional boolean, controls scrolling to the top of the page after navigation. Defaults to `true`
|
||||
- [`shallow`](/docs/pages/building-your-application/routing/linking-and-navigating#shallow-routing): Update the path of the current page without rerunning [`getStaticProps`](/docs/pages/building-your-application/data-fetching/get-static-props), [`getServerSideProps`](/docs/pages/building-your-application/data-fetching/get-server-side-props) or [`getInitialProps`](/docs/pages/api-reference/functions/get-initial-props). Defaults to `false`
|
||||
- `locale` - Optional string, indicates locale of the new page
|
||||
|
||||
> You don't need to use `router.push` for external URLs. [window.location](https://developer.mozilla.org/docs/Web/API/Window/location) is better suited for those cases.
|
||||
|
||||
Navigating to `pages/about.js`, which is a predefined route:
|
||||
|
||||
```jsx
|
||||
import { useRouter } from 'next/router'
|
||||
|
||||
export default function Page() {
|
||||
const router = useRouter()
|
||||
|
||||
return (
|
||||
<button type="button" onClick={() => router.push('/about')}>
|
||||
Click me
|
||||
</button>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Navigating `pages/post/[pid].js`, which is a dynamic route:
|
||||
|
||||
```jsx
|
||||
import { useRouter } from 'next/router'
|
||||
|
||||
export default function Page() {
|
||||
const router = useRouter()
|
||||
|
||||
return (
|
||||
<button type="button" onClick={() => router.push('/post/abc')}>
|
||||
Click me
|
||||
</button>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Redirecting the user to `pages/login.js`, useful for pages behind [authentication](/docs/pages/guides/authentication):
|
||||
|
||||
```jsx
|
||||
import { useEffect } from 'react'
|
||||
import { useRouter } from 'next/router'
|
||||
|
||||
// Here you would fetch and return the user
|
||||
const useUser = () => ({ user: null, loading: false })
|
||||
|
||||
export default function Page() {
|
||||
const { user, loading } = useUser()
|
||||
const router = useRouter()
|
||||
|
||||
useEffect(() => {
|
||||
if (!(user || loading)) {
|
||||
router.push('/login')
|
||||
}
|
||||
}, [user, loading])
|
||||
|
||||
return <p>Redirecting...</p>
|
||||
}
|
||||
```
|
||||
|
||||
#### Resetting state after navigation
|
||||
|
||||
When navigating to the same page in Next.js, the page's state **will not** be reset by default as React does not unmount unless the parent component has changed.
|
||||
|
||||
```jsx filename="pages/[slug].js"
|
||||
import Link from 'next/link'
|
||||
import { useState } from 'react'
|
||||
import { useRouter } from 'next/router'
|
||||
|
||||
export default function Page(props) {
|
||||
const router = useRouter()
|
||||
const [count, setCount] = useState(0)
|
||||
return (
|
||||
<div>
|
||||
<h1>Page: {router.query.slug}</h1>
|
||||
<p>Count: {count}</p>
|
||||
<button onClick={() => setCount(count + 1)}>Increase count</button>
|
||||
<Link href="/one">one</Link> <Link href="/two">two</Link>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
In the above example, navigating between `/one` and `/two` **will not** reset the count . The `useState` is maintained between renders because the top-level React component, `Page`, is the same.
|
||||
|
||||
If you do not want this behavior, you have a couple of options:
|
||||
|
||||
- Manually ensure each state is updated using `useEffect`. In the above example, that could look like:
|
||||
|
||||
```jsx
|
||||
useEffect(() => {
|
||||
setCount(0)
|
||||
}, [router.query.slug])
|
||||
```
|
||||
|
||||
- Use a React `key` to [tell React to remount the component](https://react.dev/learn/rendering-lists#keeping-list-items-in-order-with-key). To do this for all pages, you can use a custom app:
|
||||
|
||||
```jsx filename="pages/_app.js"
|
||||
import { useRouter } from 'next/router'
|
||||
|
||||
export default function MyApp({ Component, pageProps }) {
|
||||
const router = useRouter()
|
||||
return <Component key={router.asPath} {...pageProps} />
|
||||
}
|
||||
```
|
||||
|
||||
#### With URL object
|
||||
|
||||
You can use a URL object in the same way you can use it for [`next/link`](/docs/pages/api-reference/components/link#passing-a-url-object). Works for both the `url` and `as` parameters:
|
||||
|
||||
```jsx
|
||||
import { useRouter } from 'next/router'
|
||||
|
||||
export default function ReadMore({ post }) {
|
||||
const router = useRouter()
|
||||
|
||||
return (
|
||||
<button
|
||||
type="button"
|
||||
onClick={() => {
|
||||
router.push({
|
||||
pathname: '/post/[pid]',
|
||||
query: { pid: post.id },
|
||||
})
|
||||
}}
|
||||
>
|
||||
Click here to read more
|
||||
</button>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### router.replace
|
||||
|
||||
Similar to the `replace` prop in [`next/link`](/docs/pages/api-reference/components/link), `router.replace` will prevent adding a new URL entry into the `history` stack.
|
||||
|
||||
```js
|
||||
router.replace(url, as, options)
|
||||
```
|
||||
|
||||
- The API for `router.replace` is exactly the same as the API for [`router.push`](#routerpush).
|
||||
|
||||
Take a look at the following example:
|
||||
|
||||
```jsx
|
||||
import { useRouter } from 'next/router'
|
||||
|
||||
export default function Page() {
|
||||
const router = useRouter()
|
||||
|
||||
return (
|
||||
<button type="button" onClick={() => router.replace('/home')}>
|
||||
Click me
|
||||
</button>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### router.prefetch
|
||||
|
||||
Prefetch pages for faster client-side transitions. This method is only useful for navigations without [`next/link`](/docs/pages/api-reference/components/link), as `next/link` takes care of prefetching pages automatically.
|
||||
|
||||
> This is a production only feature. Next.js doesn't prefetch pages in development.
|
||||
|
||||
```js
|
||||
router.prefetch(url, as, options)
|
||||
```
|
||||
|
||||
- `url` - The URL to prefetch, including explicit routes (e.g. `/dashboard`) and dynamic routes (e.g. `/product/[id]`)
|
||||
- `as` - Optional decorator for `url`. Before Next.js 9.5.3 this was used to prefetch dynamic routes.
|
||||
- `options` - Optional object with the following allowed fields:
|
||||
- `locale` - allows providing a different locale from the active one. If `false`, `url` has to include the locale as the active locale won't be used.
|
||||
|
||||
Let's say you have a login page, and after a login, you redirect the user to the dashboard. For that case, we can prefetch the dashboard to make a faster transition, like in the following example:
|
||||
|
||||
```jsx
|
||||
import { useCallback, useEffect } from 'react'
|
||||
import { useRouter } from 'next/router'
|
||||
|
||||
export default function Login() {
|
||||
const router = useRouter()
|
||||
const handleSubmit = useCallback((e) => {
|
||||
e.preventDefault()
|
||||
|
||||
fetch('/api/login', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({
|
||||
/* Form data */
|
||||
}),
|
||||
}).then((res) => {
|
||||
// Do a fast client-side transition to the already prefetched dashboard page
|
||||
if (res.ok) router.push('/dashboard')
|
||||
})
|
||||
}, [])
|
||||
|
||||
useEffect(() => {
|
||||
// Prefetch the dashboard page
|
||||
router.prefetch('/dashboard')
|
||||
}, [router])
|
||||
|
||||
return (
|
||||
<form onSubmit={handleSubmit}>
|
||||
{/* Form fields */}
|
||||
<button type="submit">Login</button>
|
||||
</form>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### router.beforePopState
|
||||
|
||||
In some cases (for example, if using a [Custom Server](/docs/pages/guides/custom-server)), you may wish to listen to [popstate](https://developer.mozilla.org/docs/Web/API/Window/popstate_event) and do something before the router acts on it.
|
||||
|
||||
```js
|
||||
router.beforePopState(cb)
|
||||
```
|
||||
|
||||
- `cb` - The function to run on incoming `popstate` events. The function receives the state of the event as an object with the following props:
|
||||
- `url`: `String` - the route for the new state. This is usually the name of a `page`
|
||||
- `as`: `String` - the url that will be shown in the browser
|
||||
- `options`: `Object` - Additional options sent by [router.push](#routerpush)
|
||||
|
||||
If `cb` returns `false`, the Next.js router will not handle `popstate`, and you'll be responsible for handling it in that case. See [Disabling file-system routing](/docs/pages/guides/custom-server#disabling-file-system-routing).
|
||||
|
||||
You could use `beforePopState` to manipulate the request, or force a SSR refresh, as in the following example:
|
||||
|
||||
```jsx
|
||||
import { useEffect } from 'react'
|
||||
import { useRouter } from 'next/router'
|
||||
|
||||
export default function Page() {
|
||||
const router = useRouter()
|
||||
|
||||
useEffect(() => {
|
||||
router.beforePopState(({ url, as, options }) => {
|
||||
// I only want to allow these two routes!
|
||||
if (as !== '/' && as !== '/other') {
|
||||
// Have SSR render bad routes as a 404.
|
||||
window.location.href = as
|
||||
return false
|
||||
}
|
||||
|
||||
return true
|
||||
})
|
||||
}, [router])
|
||||
|
||||
return <p>Welcome to the page</p>
|
||||
}
|
||||
```
|
||||
|
||||
### router.back
|
||||
|
||||
Navigate back in history. Equivalent to clicking the browser’s back button. It executes `window.history.back()`.
|
||||
|
||||
```jsx
|
||||
import { useRouter } from 'next/router'
|
||||
|
||||
export default function Page() {
|
||||
const router = useRouter()
|
||||
|
||||
return (
|
||||
<button type="button" onClick={() => router.back()}>
|
||||
Click here to go back
|
||||
</button>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### router.reload
|
||||
|
||||
Reload the current URL. Equivalent to clicking the browser’s refresh button. It executes `window.location.reload()`.
|
||||
|
||||
```jsx
|
||||
import { useRouter } from 'next/router'
|
||||
|
||||
export default function Page() {
|
||||
const router = useRouter()
|
||||
|
||||
return (
|
||||
<button type="button" onClick={() => router.reload()}>
|
||||
Click here to reload
|
||||
</button>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### router.events
|
||||
|
||||
You can listen to different events happening inside the Next.js Router. Here's a list of supported events:
|
||||
|
||||
- `routeChangeStart(url, { shallow })` - Fires when a route starts to change
|
||||
- `routeChangeComplete(url, { shallow })` - Fires when a route changed completely
|
||||
- `routeChangeError(err, url, { shallow })` - Fires when there's an error when changing routes, or a route load is cancelled
|
||||
- `err.cancelled` - Indicates if the navigation was cancelled
|
||||
- `beforeHistoryChange(url, { shallow })` - Fires before changing the browser's history
|
||||
- `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
|
||||
|
||||
> **Good to know**: Here `url` is the URL shown in the browser, including the [`basePath`](/docs/app/api-reference/config/next-config-js/basePath).
|
||||
|
||||
For example, to listen to the router event `routeChangeStart`, open or create `pages/_app.js` and subscribe to the event, like so:
|
||||
|
||||
```jsx
|
||||
import { useEffect } from 'react'
|
||||
import { useRouter } from 'next/router'
|
||||
|
||||
export default function MyApp({ Component, pageProps }) {
|
||||
const router = useRouter()
|
||||
|
||||
useEffect(() => {
|
||||
const handleRouteChange = (url, { shallow }) => {
|
||||
console.log(
|
||||
`App is changing to ${url} ${
|
||||
shallow ? 'with' : 'without'
|
||||
} shallow routing`
|
||||
)
|
||||
}
|
||||
|
||||
router.events.on('routeChangeStart', handleRouteChange)
|
||||
|
||||
// If the component is unmounted, unsubscribe
|
||||
// from the event with the `off` method:
|
||||
return () => {
|
||||
router.events.off('routeChangeStart', handleRouteChange)
|
||||
}
|
||||
}, [router])
|
||||
|
||||
return <Component {...pageProps} />
|
||||
}
|
||||
```
|
||||
|
||||
> We use a [Custom App](/docs/pages/building-your-application/routing/custom-app) (`pages/_app.js`) for this example to subscribe to the event because it's not unmounted on page navigations, but you can subscribe to router events on any component in your application.
|
||||
|
||||
Router events should be registered when a component mounts ([useEffect](https://react.dev/reference/react/useEffect) or [componentDidMount](https://react.dev/reference/react/Component#componentdidmount) / [componentWillUnmount](https://react.dev/reference/react/Component#componentwillunmount)) or imperatively when an event happens.
|
||||
|
||||
If a route load is cancelled (for example, by clicking two links rapidly in succession), `routeChangeError` will fire. And the passed `err` will contain a `cancelled` property set to `true`, as in the following example:
|
||||
|
||||
```jsx
|
||||
import { useEffect } from 'react'
|
||||
import { useRouter } from 'next/router'
|
||||
|
||||
export default function MyApp({ Component, pageProps }) {
|
||||
const router = useRouter()
|
||||
|
||||
useEffect(() => {
|
||||
const handleRouteChangeError = (err, url) => {
|
||||
if (err.cancelled) {
|
||||
console.log(`Route to ${url} was cancelled!`)
|
||||
}
|
||||
}
|
||||
|
||||
router.events.on('routeChangeError', handleRouteChangeError)
|
||||
|
||||
// If the component is unmounted, unsubscribe
|
||||
// from the event with the `off` method:
|
||||
return () => {
|
||||
router.events.off('routeChangeError', handleRouteChangeError)
|
||||
}
|
||||
}, [router])
|
||||
|
||||
return <Component {...pageProps} />
|
||||
}
|
||||
```
|
||||
|
||||
## The `next/compat/router` export
|
||||
|
||||
This is the same `useRouter` hook, but can be used in both `app` and `pages` directories.
|
||||
|
||||
It differs from `next/router` in that it does not throw an error when the pages router is not mounted, and instead has a return type of `NextRouter | null`.
|
||||
This allows developers to convert components to support running in both `app` and `pages` as they transition to the `app` router.
|
||||
|
||||
A component that previously looked like this:
|
||||
|
||||
```jsx
|
||||
import { useRouter } from 'next/router'
|
||||
const MyComponent = () => {
|
||||
const { isReady, query } = useRouter()
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
Will error when converted over to `next/compat/router`, as `null` cannot be destructured. Instead, developers will be able to take advantage of new hooks:
|
||||
|
||||
```jsx
|
||||
import { useEffect } from 'react'
|
||||
import { useRouter } from 'next/compat/router'
|
||||
import { useSearchParams } from 'next/navigation'
|
||||
const MyComponent = () => {
|
||||
const router = useRouter() // may be null or a NextRouter instance
|
||||
const searchParams = useSearchParams()
|
||||
useEffect(() => {
|
||||
if (router && !router.isReady) {
|
||||
return
|
||||
}
|
||||
// In `app/`, searchParams will be ready immediately with the values, in
|
||||
// `pages/` it will be available after the router is ready.
|
||||
const search = searchParams.get('search')
|
||||
// ...
|
||||
}, [router, searchParams])
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
This component will now work in both `pages` and `app` directories. When the component is no longer used in `pages`, you can remove the references to the compat router:
|
||||
|
||||
```jsx
|
||||
import { useSearchParams } from 'next/navigation'
|
||||
const MyComponent = () => {
|
||||
const searchParams = useSearchParams()
|
||||
// As this component is only used in `app/`, the compat router can be removed.
|
||||
const search = searchParams.get('search')
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### Using `useRouter` outside of Next.js context in pages
|
||||
|
||||
Another specific use case is when rendering components outside of a Next.js application context, such as inside `getServerSideProps` on the `pages` directory. In this case, the compat router can be used to avoid errors:
|
||||
|
||||
```jsx
|
||||
import { renderToString } from 'react-dom/server'
|
||||
import { useRouter } from 'next/compat/router'
|
||||
const MyComponent = () => {
|
||||
const router = useRouter() // may be null or a NextRouter instance
|
||||
// ...
|
||||
}
|
||||
export async function getServerSideProps() {
|
||||
const renderedComponent = renderToString(<MyComponent />)
|
||||
return {
|
||||
props: {
|
||||
renderedComponent,
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Potential ESLint errors
|
||||
|
||||
Certain methods accessible on the `router` object return a Promise. If you have the ESLint rule, [no-floating-promises](https://typescript-eslint.io/rules/no-floating-promises) enabled, consider disabling it either globally, or for the affected line.
|
||||
|
||||
If your application needs this rule, you should either `void` the promise – or use an `async` function, `await` the Promise, then void the function call. **This is not applicable when the method is called from inside an `onClick` handler**.
|
||||
|
||||
The affected methods are:
|
||||
|
||||
- `router.push`
|
||||
- `router.replace`
|
||||
- `router.prefetch`
|
||||
|
||||
### Potential solutions
|
||||
|
||||
```jsx
|
||||
import { useEffect } from 'react'
|
||||
import { useRouter } from 'next/router'
|
||||
|
||||
// Here you would fetch and return the user
|
||||
const useUser = () => ({ user: null, loading: false })
|
||||
|
||||
export default function Page() {
|
||||
const { user, loading } = useUser()
|
||||
const router = useRouter()
|
||||
|
||||
useEffect(() => {
|
||||
// disable the linting on the next line - This is the cleanest solution
|
||||
// eslint-disable-next-line no-floating-promises
|
||||
router.push('/login')
|
||||
|
||||
// void the Promise returned by router.push
|
||||
if (!(user || loading)) {
|
||||
void router.push('/login')
|
||||
}
|
||||
// or use an async function, await the Promise, then void the function call
|
||||
async function handleRouteChange() {
|
||||
if (!(user || loading)) {
|
||||
await router.push('/login')
|
||||
}
|
||||
}
|
||||
void handleRouteChange()
|
||||
}, [user, loading])
|
||||
|
||||
return <p>Redirecting...</p>
|
||||
}
|
||||
```
|
||||
|
||||
## withRouter
|
||||
|
||||
If [`useRouter`](#router-object) is not the best fit for you, `withRouter` can also add the same [`router` object](#router-object) to any component.
|
||||
|
||||
### Usage
|
||||
|
||||
```jsx
|
||||
import { withRouter } from 'next/router'
|
||||
|
||||
function Page({ router }) {
|
||||
return <p>{router.pathname}</p>
|
||||
}
|
||||
|
||||
export default withRouter(Page)
|
||||
```
|
||||
|
||||
### TypeScript
|
||||
|
||||
To use class components with `withRouter`, the component needs to accept a router prop:
|
||||
|
||||
```tsx
|
||||
import React from 'react'
|
||||
import { withRouter, NextRouter } from 'next/router'
|
||||
|
||||
interface WithRouterProps {
|
||||
router: NextRouter
|
||||
}
|
||||
|
||||
interface MyComponentProps extends WithRouterProps {}
|
||||
|
||||
class MyComponent extends React.Component<MyComponentProps> {
|
||||
render() {
|
||||
return <p>{this.props.router.pathname}</p>
|
||||
}
|
||||
}
|
||||
|
||||
export default withRouter(MyComponent)
|
||||
```
|
||||
Generated
Vendored
+318
@@ -0,0 +1,318 @@
|
||||
---
|
||||
title: useSearchParams
|
||||
description: API Reference for the useSearchParams hook in the Pages Router.
|
||||
---
|
||||
|
||||
`useSearchParams` is a hook that lets you read the current URL's **query string**.
|
||||
|
||||
`useSearchParams` returns a **read-only** version of the [`URLSearchParams`](https://developer.mozilla.org/docs/Web/API/URLSearchParams) interface.
|
||||
|
||||
```tsx filename="pages/dashboard.tsx" switcher
|
||||
import { useSearchParams } from 'next/navigation'
|
||||
|
||||
export default function Dashboard() {
|
||||
const searchParams = useSearchParams()
|
||||
|
||||
if (!searchParams) {
|
||||
// Render fallback UI while search params are not yet available
|
||||
return null
|
||||
}
|
||||
|
||||
const search = searchParams.get('search')
|
||||
|
||||
// URL -> `/dashboard?search=my-project`
|
||||
// `search` -> 'my-project'
|
||||
return <>Search: {search}</>
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="pages/dashboard.js" switcher
|
||||
import { useSearchParams } from 'next/navigation'
|
||||
|
||||
export default function Dashboard() {
|
||||
const searchParams = useSearchParams()
|
||||
|
||||
if (!searchParams) {
|
||||
// Render fallback UI while search params are not yet available
|
||||
return null
|
||||
}
|
||||
|
||||
const search = searchParams.get('search')
|
||||
|
||||
// URL -> `/dashboard?search=my-project`
|
||||
// `search` -> 'my-project'
|
||||
return <>Search: {search}</>
|
||||
}
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
```tsx
|
||||
const searchParams = useSearchParams()
|
||||
```
|
||||
|
||||
`useSearchParams` does not take any parameters.
|
||||
|
||||
## Returns
|
||||
|
||||
`useSearchParams` returns a **read-only** version of the [`URLSearchParams`](https://developer.mozilla.org/docs/Web/API/URLSearchParams) interface, or `null` during [prerendering](#behavior-during-prerendering).
|
||||
|
||||
The interface includes utility methods for reading the URL's query string:
|
||||
|
||||
- [`URLSearchParams.get()`](https://developer.mozilla.org/docs/Web/API/URLSearchParams/get): Returns the first value associated with the search parameter. For example:
|
||||
|
||||
| URL | `searchParams.get("a")` |
|
||||
| -------------------- | --------------------------------------------------------------------------------------------------------------- |
|
||||
| `/dashboard?a=1` | `'1'` |
|
||||
| `/dashboard?a=` | `''` |
|
||||
| `/dashboard?b=3` | `null` |
|
||||
| `/dashboard?a=1&a=2` | `'1'` _- use [`getAll()`](https://developer.mozilla.org/docs/Web/API/URLSearchParams/getAll) to get all values_ |
|
||||
|
||||
- [`URLSearchParams.has()`](https://developer.mozilla.org/docs/Web/API/URLSearchParams/has): Returns a boolean value indicating if the given parameter exists. For example:
|
||||
|
||||
| URL | `searchParams.has("a")` |
|
||||
| ---------------- | ----------------------- |
|
||||
| `/dashboard?a=1` | `true` |
|
||||
| `/dashboard?b=3` | `false` |
|
||||
|
||||
- Learn more about other **read-only** methods of [`URLSearchParams`](https://developer.mozilla.org/docs/Web/API/URLSearchParams), including the [`getAll()`](https://developer.mozilla.org/docs/Web/API/URLSearchParams/getAll), [`keys()`](https://developer.mozilla.org/docs/Web/API/URLSearchParams/keys), [`values()`](https://developer.mozilla.org/docs/Web/API/URLSearchParams/values), [`entries()`](https://developer.mozilla.org/docs/Web/API/URLSearchParams/entries), [`forEach()`](https://developer.mozilla.org/docs/Web/API/URLSearchParams/forEach), and [`toString()`](https://developer.mozilla.org/docs/Web/API/URLSearchParams/toString).
|
||||
|
||||
> **Good to know**: `useSearchParams` is a [React Hook](https://react.dev/learn#using-hooks) and cannot be used with classes.
|
||||
|
||||
## Behavior
|
||||
|
||||
### Behavior during prerendering
|
||||
|
||||
For pages that are [statically optimized](/docs/pages/building-your-application/rendering/automatic-static-optimization) (not using `getServerSideProps`), `useSearchParams` will return `null` during prerendering. After hydration, the value will be updated to the actual search params.
|
||||
|
||||
This is because search params cannot be known during static generation as they depend on the request.
|
||||
|
||||
```tsx filename="pages/dashboard.tsx" switcher
|
||||
import { useSearchParams } from 'next/navigation'
|
||||
|
||||
export default function Dashboard() {
|
||||
const searchParams = useSearchParams()
|
||||
|
||||
if (!searchParams) {
|
||||
// Return a fallback UI while search params are loading
|
||||
// This prevents hydration mismatches
|
||||
return <DashboardSkeleton />
|
||||
}
|
||||
|
||||
const search = searchParams.get('search')
|
||||
|
||||
return <>Search: {search}</>
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="pages/dashboard.js" switcher
|
||||
import { useSearchParams } from 'next/navigation'
|
||||
|
||||
export default function Dashboard() {
|
||||
const searchParams = useSearchParams()
|
||||
|
||||
if (!searchParams) {
|
||||
// Return a fallback UI while search params are loading
|
||||
// This prevents hydration mismatches
|
||||
return <DashboardSkeleton />
|
||||
}
|
||||
|
||||
const search = searchParams.get('search')
|
||||
|
||||
return <>Search: {search}</>
|
||||
}
|
||||
```
|
||||
|
||||
### Using with `getServerSideProps`
|
||||
|
||||
When using [`getServerSideProps`](/docs/pages/building-your-application/data-fetching/get-server-side-props), the page is server-rendered on each request and `useSearchParams` will return the actual search params immediately:
|
||||
|
||||
```tsx filename="pages/dashboard.tsx" switcher
|
||||
import { useSearchParams } from 'next/navigation'
|
||||
|
||||
export default function Dashboard() {
|
||||
const searchParams = useSearchParams()
|
||||
|
||||
// With getServerSideProps, this fallback is never rendered because
|
||||
// searchParams is always available on the server. However, keeping
|
||||
// the fallback allows this component to be reused on other pages
|
||||
// that may not use getServerSideProps.
|
||||
if (!searchParams) {
|
||||
return null
|
||||
}
|
||||
|
||||
const search = searchParams.get('search')
|
||||
|
||||
return <>Search: {search}</>
|
||||
}
|
||||
|
||||
export async function getServerSideProps() {
|
||||
return { props: {} }
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="pages/dashboard.js" switcher
|
||||
import { useSearchParams } from 'next/navigation'
|
||||
|
||||
export default function Dashboard() {
|
||||
const searchParams = useSearchParams()
|
||||
|
||||
// With getServerSideProps, this fallback is never rendered because
|
||||
// searchParams is always available on the server. However, keeping
|
||||
// the fallback allows this component to be reused on other pages
|
||||
// that may not use getServerSideProps.
|
||||
if (!searchParams) {
|
||||
return null
|
||||
}
|
||||
|
||||
const search = searchParams.get('search')
|
||||
|
||||
return <>Search: {search}</>
|
||||
}
|
||||
|
||||
export async function getServerSideProps() {
|
||||
return { props: {} }
|
||||
}
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Updating search params
|
||||
|
||||
You can use the [`useRouter`](/docs/pages/api-reference/functions/use-router) hook to update search params:
|
||||
|
||||
```tsx filename="pages/dashboard.tsx" switcher
|
||||
import { useRouter } from 'next/router'
|
||||
import { useSearchParams } from 'next/navigation'
|
||||
import { useCallback } from 'react'
|
||||
|
||||
export default function Dashboard() {
|
||||
const router = useRouter()
|
||||
const searchParams = useSearchParams()
|
||||
|
||||
const createQueryString = useCallback(
|
||||
(name: string, value: string) => {
|
||||
const params = new URLSearchParams(searchParams?.toString())
|
||||
params.set(name, value)
|
||||
return params.toString()
|
||||
},
|
||||
[searchParams]
|
||||
)
|
||||
|
||||
if (!searchParams) {
|
||||
return null
|
||||
}
|
||||
|
||||
return (
|
||||
<>
|
||||
<p>Sort By</p>
|
||||
<button
|
||||
onClick={() => {
|
||||
router.push(router.pathname + '?' + createQueryString('sort', 'asc'))
|
||||
}}
|
||||
>
|
||||
ASC
|
||||
</button>
|
||||
<button
|
||||
onClick={() => {
|
||||
router.push(router.pathname + '?' + createQueryString('sort', 'desc'))
|
||||
}}
|
||||
>
|
||||
DESC
|
||||
</button>
|
||||
</>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="pages/dashboard.js" switcher
|
||||
import { useRouter } from 'next/router'
|
||||
import { useSearchParams } from 'next/navigation'
|
||||
import { useCallback } from 'react'
|
||||
|
||||
export default function Dashboard() {
|
||||
const router = useRouter()
|
||||
const searchParams = useSearchParams()
|
||||
|
||||
const createQueryString = useCallback(
|
||||
(name, value) => {
|
||||
const params = new URLSearchParams(searchParams?.toString())
|
||||
params.set(name, value)
|
||||
return params.toString()
|
||||
},
|
||||
[searchParams]
|
||||
)
|
||||
|
||||
if (!searchParams) {
|
||||
return null
|
||||
}
|
||||
|
||||
return (
|
||||
<>
|
||||
<p>Sort By</p>
|
||||
<button
|
||||
onClick={() => {
|
||||
router.push(router.pathname + '?' + createQueryString('sort', 'asc'))
|
||||
}}
|
||||
>
|
||||
ASC
|
||||
</button>
|
||||
<button
|
||||
onClick={() => {
|
||||
router.push(router.pathname + '?' + createQueryString('sort', 'desc'))
|
||||
}}
|
||||
>
|
||||
DESC
|
||||
</button>
|
||||
</>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Sharing components with App Router
|
||||
|
||||
`useSearchParams` from `next/navigation` works in both the Pages Router and App Router. This allows you to create shared components that work in either context:
|
||||
|
||||
```tsx filename="components/search-bar.tsx" switcher
|
||||
import { useSearchParams } from 'next/navigation'
|
||||
|
||||
// This component works in both pages/ and app/
|
||||
export function SearchBar() {
|
||||
const searchParams = useSearchParams()
|
||||
|
||||
if (!searchParams) {
|
||||
// Fallback for Pages Router during prerendering
|
||||
return <input defaultValue="" placeholder="Search..." />
|
||||
}
|
||||
|
||||
const search = searchParams.get('search') ?? ''
|
||||
|
||||
return <input defaultValue={search} placeholder="Search..." />
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="components/search-bar.js" switcher
|
||||
import { useSearchParams } from 'next/navigation'
|
||||
|
||||
// This component works in both pages/ and app/
|
||||
export function SearchBar() {
|
||||
const searchParams = useSearchParams()
|
||||
|
||||
if (!searchParams) {
|
||||
// Fallback for Pages Router during prerendering
|
||||
return <input defaultValue="" placeholder="Search..." />
|
||||
}
|
||||
|
||||
const search = searchParams.get('search') ?? ''
|
||||
|
||||
return <input defaultValue={search} placeholder="Search..." />
|
||||
}
|
||||
```
|
||||
|
||||
> **Good to know**: When using this component in the App Router, wrap it in a `<Suspense>` boundary for [prerendering](/docs/app/api-reference/functions/use-search-params#prerendering) support.
|
||||
|
||||
## Version History
|
||||
|
||||
| Version | Changes |
|
||||
| --------- | ----------------------------- |
|
||||
| `v13.0.0` | `useSearchParams` introduced. |
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: userAgent
|
||||
description: The userAgent helper extends the Web Request API with additional properties and methods to interact with the user agent object from the request.
|
||||
source: app/api-reference/functions/userAgent
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: adapterPath
|
||||
description: Configure a custom adapter for Next.js to hook into the build process.
|
||||
source: app/api-reference/config/next-config-js/adapterPath
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: allowedDevOrigins
|
||||
description: Use `allowedDevOrigins` to configure additional origins that can request the dev server.
|
||||
source: app/api-reference/config/next-config-js/allowedDevOrigins
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: assetPrefix
|
||||
description: Learn how to use the assetPrefix config option to configure your CDN.
|
||||
source: app/api-reference/config/next-config-js/assetPrefix
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: basePath
|
||||
description: Use `basePath` to deploy a Next.js application under a sub-path of a domain.
|
||||
source: app/api-reference/config/next-config-js/basePath
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+23
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: bundlePagesRouterDependencies
|
||||
description: Enable automatic dependency bundling for Pages Router
|
||||
---
|
||||
|
||||
Enable automatic server-side dependency bundling for Pages Router applications. Matches the automatic dependency bundling in App Router.
|
||||
|
||||
```js filename="next.config.js"
|
||||
/** @type {import('next').NextConfig} */
|
||||
const nextConfig = {
|
||||
bundlePagesRouterDependencies: true,
|
||||
}
|
||||
|
||||
module.exports = nextConfig
|
||||
```
|
||||
|
||||
Explicitly opt-out certain packages from being bundled using the [`serverExternalPackages`](/docs/pages/api-reference/config/next-config-js/serverExternalPackages) option.
|
||||
|
||||
## Version History
|
||||
|
||||
| Version | Changes |
|
||||
| --------- | --------------------------------------------------------------------------------------------------------- |
|
||||
| `v15.0.0` | Moved from experimental to stable. Renamed from `bundlePagesExternals` to `bundlePagesRouterDependencies` |
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: compress
|
||||
description: Next.js provides gzip compression to compress rendered content and static files, it only works with the server target. Learn more about it here.
|
||||
source: app/api-reference/config/next-config-js/compress
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: crossOrigin
|
||||
description: Use the `crossOrigin` option to add a crossOrigin tag on the `script` tags generated by `next/script` and `next/head`.
|
||||
source: app/api-reference/config/next-config-js/crossOrigin
|
||||
---
|
||||
|
||||
{/* The content of this doc is shared between the app and pages router. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: deploymentId
|
||||
description: Configure a deployment identifier used for version skew protection and cache busting.
|
||||
source: app/api-reference/config/next-config-js/deploymentId
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: devIndicators
|
||||
description: Optimized pages include an indicator to let you know if it's being statically optimized. You can opt-out of it here.
|
||||
source: app/api-reference/config/next-config-js/devIndicators
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: distDir
|
||||
description: Set a custom build directory to use instead of the default .next directory.
|
||||
source: app/api-reference/config/next-config-js/distDir
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: env
|
||||
description: Learn to add and access environment variables in your Next.js application at build time.
|
||||
source: app/api-reference/config/next-config-js/env
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: exportPathMap
|
||||
description: Customize the pages that will be exported as HTML files when using `next export`.
|
||||
source: app/api-reference/config/next-config-js/exportPathMap
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: generateBuildId
|
||||
description: Configure the build id, which is used to identify the current build in which your application is being served.
|
||||
source: app/api-reference/config/next-config-js/generateBuildId
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: generateEtags
|
||||
description: Next.js will generate etags for every page by default. Learn more about how to disable etag generation here.
|
||||
source: app/api-reference/config/next-config-js/generateEtags
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: headers
|
||||
description: Add custom HTTP headers to your Next.js app.
|
||||
source: app/api-reference/config/next-config-js/headers
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: httpAgentOptions
|
||||
description: Next.js will automatically use HTTP Keep-Alive by default. Learn more about how to disable HTTP Keep-Alive here.
|
||||
source: app/api-reference/config/next-config-js/httpAgentOptions
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
frontend/node_modules/next/dist/docs/02-pages/04-api-reference/04-config/01-next-config-js/images.md
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: images
|
||||
description: Custom configuration for the next/image loader
|
||||
source: app/api-reference/config/next-config-js/images
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: next.config.js Options
|
||||
description: Learn about the options available in next.config.js for the Pages Router.
|
||||
source: app/api-reference/config/next-config-js
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: logging
|
||||
description: Configure logging behavior in the terminal when running Next.js in development mode.
|
||||
source: app/api-reference/config/next-config-js/logging
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: onDemandEntries
|
||||
description: Configure how Next.js will dispose and keep in memory pages created in development.
|
||||
source: app/api-reference/config/next-config-js/onDemandEntries
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+8
@@ -0,0 +1,8 @@
|
||||
---
|
||||
title: optimizePackageImports
|
||||
description: API Reference for optimizePackageImports Next.js Config Option
|
||||
source: app/api-reference/config/next-config-js/optimizePackageImports
|
||||
version: experimental
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
frontend/node_modules/next/dist/docs/02-pages/04-api-reference/04-config/01-next-config-js/output.md
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: output
|
||||
description: Next.js automatically traces which files are needed by each page to allow for easy deployment of your application. Learn how it works here.
|
||||
source: app/api-reference/config/next-config-js/output
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: pageExtensions
|
||||
description: Extend the default page extensions used by Next.js when resolving pages in the Pages Router.
|
||||
source: app/api-reference/config/next-config-js/pageExtensions
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: poweredByHeader
|
||||
description: Next.js will add the `x-powered-by` header by default. Learn to opt-out of it here.
|
||||
source: app/api-reference/config/next-config-js/poweredByHeader
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: productionBrowserSourceMaps
|
||||
description: Enables browser source map generation during the production build.
|
||||
source: app/api-reference/config/next-config-js/productionBrowserSourceMaps
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: experimental.proxyClientMaxBodySize
|
||||
description: Configure the maximum request body size when using proxy.
|
||||
source: app/api-reference/config/next-config-js/proxyClientMaxBodySize
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: reactStrictMode
|
||||
description: The complete Next.js runtime is now Strict Mode-compliant, learn how to opt-in
|
||||
source: app/api-reference/config/next-config-js/reactStrictMode
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: redirects
|
||||
description: Add redirects to your Next.js app.
|
||||
source: app/api-reference/config/next-config-js/redirects
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: rewrites
|
||||
description: Add rewrites to your Next.js app.
|
||||
source: app/api-reference/config/next-config-js/rewrites
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+99
@@ -0,0 +1,99 @@
|
||||
---
|
||||
title: serverExternalPackages
|
||||
description: Opt-out specific dependencies from the dependency bundling enabled by `bundlePagesRouterDependencies`.
|
||||
---
|
||||
|
||||
Opt-out specific dependencies from being included in the automatic bundling of the [`bundlePagesRouterDependencies`](/docs/pages/api-reference/config/next-config-js/bundlePagesRouterDependencies) option.
|
||||
|
||||
These pages will then use native Node.js `require` to resolve the dependency.
|
||||
|
||||
```js filename="next.config.js"
|
||||
/** @type {import('next').NextConfig} */
|
||||
const nextConfig = {
|
||||
serverExternalPackages: ['@acme/ui'],
|
||||
}
|
||||
|
||||
module.exports = nextConfig
|
||||
```
|
||||
|
||||
Next.js includes a [short list of popular packages](https://github.com/vercel/next.js/blob/canary/packages/next/src/lib/server-external-packages.jsonc) that currently are working on compatibility and automatically opt-ed out:
|
||||
|
||||
- `@alinea/generated`
|
||||
- `@appsignal/nodejs`
|
||||
- `@aws-sdk/client-s3`
|
||||
- `@aws-sdk/s3-presigned-post`
|
||||
- `@blockfrost/blockfrost-js`
|
||||
- `@highlight-run/node`
|
||||
- `@huggingface/transformers`
|
||||
- `@jpg-store/lucid-cardano`
|
||||
- `@libsql/client`
|
||||
- `@mikro-orm/core`
|
||||
- `@mikro-orm/knex`
|
||||
- `@node-rs/argon2`
|
||||
- `@node-rs/bcrypt`
|
||||
- `@prisma/client`
|
||||
- `@react-pdf/renderer`
|
||||
- `@sentry/profiling-node`
|
||||
- `@sparticuz/chromium`
|
||||
- `@sparticuz/chromium-min`
|
||||
- `@statsig/statsig-node-core`
|
||||
- `@swc/core`
|
||||
- `@xenova/transformers`
|
||||
- `@zenstackhq/runtime`
|
||||
- `argon2`
|
||||
- `autoprefixer`
|
||||
- `aws-crt`
|
||||
- `bcrypt`
|
||||
- `better-sqlite3`
|
||||
- `canvas`
|
||||
- `chromadb-default-embed`
|
||||
- `config`
|
||||
- `cpu-features`
|
||||
- `cypress`
|
||||
- `dd-trace`
|
||||
- `eslint`
|
||||
- `express`
|
||||
- `firebase-admin`
|
||||
- `htmlrewriter`
|
||||
- `import-in-the-middle`
|
||||
- `isolated-vm`
|
||||
- `jest`
|
||||
- `jsdom`
|
||||
- `keyv`
|
||||
- `libsql`
|
||||
- `mdx-bundler`
|
||||
- `mongodb`
|
||||
- `mongoose`
|
||||
- `newrelic`
|
||||
- `next-mdx-remote`
|
||||
- `next-seo`
|
||||
- `node-cron`
|
||||
- `node-pty`
|
||||
- `node-web-audio-api`
|
||||
- `onnxruntime-node`
|
||||
- `oslo`
|
||||
- `pg`
|
||||
- `pino`
|
||||
- `pino-pretty`
|
||||
- `pino-roll`
|
||||
- `playwright`
|
||||
- `playwright-core`
|
||||
- `postcss`
|
||||
- `prettier`
|
||||
- `prisma`
|
||||
- `puppeteer-core`
|
||||
- `puppeteer`
|
||||
- `ravendb`
|
||||
- `require-in-the-middle`
|
||||
- `rimraf`
|
||||
- `sharp`
|
||||
- `shiki`
|
||||
- `sqlite3`
|
||||
- `thread-stream`
|
||||
- `ts-morph`
|
||||
- `ts-node`
|
||||
- `typescript`
|
||||
- `vscode-oniguruma`
|
||||
- `webpack`
|
||||
- `websocket`
|
||||
- `zeromq`
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: trailingSlash
|
||||
description: Configure Next.js pages to resolve with or without a trailing slash.
|
||||
source: app/api-reference/config/next-config-js/trailingSlash
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: transpilePackages
|
||||
description: Automatically transpile and bundle dependencies from local packages (like monorepos) or from external dependencies (`node_modules`).
|
||||
source: app/api-reference/config/next-config-js/transpilePackages
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+8
@@ -0,0 +1,8 @@
|
||||
---
|
||||
title: turbopack
|
||||
description: Configure Next.js with Turbopack-specific options
|
||||
version: experimental
|
||||
source: app/api-reference/config/next-config-js/turbopack
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: typescript
|
||||
description: Next.js reports TypeScript errors by default. Learn to opt-out of this behavior here.
|
||||
source: app/api-reference/config/next-config-js/typescript
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+8
@@ -0,0 +1,8 @@
|
||||
---
|
||||
title: urlImports
|
||||
description: Configure Next.js to allow importing modules from external URLs.
|
||||
version: experimental
|
||||
source: app/api-reference/config/next-config-js/urlImports
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+8
@@ -0,0 +1,8 @@
|
||||
---
|
||||
title: useLightningcss
|
||||
description: Enable experimental support for Lightning CSS.
|
||||
version: experimental
|
||||
source: app/api-reference/config/next-config-js/useLightningcss
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: webVitalsAttribution
|
||||
description: Learn how to use the webVitalsAttribution option to pinpoint the source of Web Vitals issues.
|
||||
source: app/api-reference/config/next-config-js/webVitalsAttribution
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+8
@@ -0,0 +1,8 @@
|
||||
---
|
||||
title: Custom Webpack Config
|
||||
nav_title: webpack
|
||||
description: Learn how to customize the webpack config used by Next.js
|
||||
source: app/api-reference/config/next-config-js/webpack
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: TypeScript
|
||||
description: Next.js provides a TypeScript-first development experience for building your React application.
|
||||
source: app/api-reference/config/typescript
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: ESLint
|
||||
description: Next.js reports ESLint errors and warnings during builds by default. Learn how to opt-out of this behavior here.
|
||||
source: app/api-reference/config/eslint
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+4
@@ -0,0 +1,4 @@
|
||||
---
|
||||
title: Configuration
|
||||
description: Learn how to configure your Next.js application.
|
||||
---
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: create-next-app CLI
|
||||
description: Create Next.js apps using one command with the create-next-app CLI.
|
||||
source: app/api-reference/cli/create-next-app
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: CLI
|
||||
description: API Reference for the Next.js Command Line Interface (CLI) tools.
|
||||
source: app/api-reference/cli
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: next CLI
|
||||
description: Learn how to run and build your application with the Next.js CLI.
|
||||
source: app/api-reference/cli/next
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Configuration
|
||||
description: Configure `adapterPath` or `NEXT_ADAPTER_PATH` to use a custom deployment adapter.
|
||||
source: app/api-reference/adapters/configuration
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the <PagesOnly>Content</PagesOnly> component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
frontend/node_modules/next/dist/docs/02-pages/04-api-reference/06-adapters/02-creating-an-adapter.md
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Creating an Adapter
|
||||
description: Create an adapter module that implements the `NextAdapter` interface.
|
||||
source: app/api-reference/adapters/creating-an-adapter
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the <PagesOnly>Content</PagesOnly> component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: API Reference
|
||||
description: Reference for `modifyConfig` and `onBuildComplete` in the `NextAdapter` interface.
|
||||
source: app/api-reference/adapters/api-reference
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the <PagesOnly>Content</PagesOnly> component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Testing Adapters
|
||||
description: Validate adapters with the Next.js compatibility test harness and custom lifecycle scripts.
|
||||
source: app/api-reference/adapters/testing-adapters
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the <PagesOnly>Content</PagesOnly> component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Routing with @next/routing
|
||||
description: Use `@next/routing` to apply Next.js route matching behavior in adapters.
|
||||
source: app/api-reference/adapters/routing-with-next-routing
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the <PagesOnly>Content</PagesOnly> component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Implementing PPR in an Adapter
|
||||
description: Implement Partial Prerendering support in an adapter using fallback output and cache hooks.
|
||||
source: app/api-reference/adapters/implementing-ppr-in-an-adapter
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the <PagesOnly>Content</PagesOnly> component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
frontend/node_modules/next/dist/docs/02-pages/04-api-reference/06-adapters/07-runtime-integration.md
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Runtime Integration
|
||||
description: Understand how build-time adapters and runtime cache interfaces work together.
|
||||
source: app/api-reference/adapters/runtime-integration
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the <PagesOnly>Content</PagesOnly> component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Invoking Entrypoints
|
||||
description: Invoke Node.js and Edge build entrypoints with adapter runtime context.
|
||||
source: app/api-reference/adapters/invoking-entrypoints
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the <PagesOnly>Content</PagesOnly> component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Output Types
|
||||
description: Reference for all build output types exposed to adapters.
|
||||
source: app/api-reference/adapters/output-types
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the <PagesOnly>Content</PagesOnly> component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
frontend/node_modules/next/dist/docs/02-pages/04-api-reference/06-adapters/10-routing-information.md
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Routing Information
|
||||
description: Reference for routing phases and route fields exposed in `onBuildComplete`.
|
||||
source: app/api-reference/adapters/routing-information
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the <PagesOnly>Content</PagesOnly> component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Use Cases
|
||||
description: Common patterns and examples for deployment adapter implementations.
|
||||
source: app/api-reference/adapters/use-cases
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the <PagesOnly>Content</PagesOnly> component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
Generated
Vendored
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Adapters
|
||||
description: Build deployment adapters for Next.js platforms and infrastructure.
|
||||
source: app/api-reference/adapters
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the <PagesOnly>Content</PagesOnly> component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
+7
@@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Edge Runtime
|
||||
description: API Reference for the Edge Runtime.
|
||||
source: app/api-reference/edge
|
||||
---
|
||||
|
||||
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
|
||||
+5
@@ -0,0 +1,5 @@
|
||||
---
|
||||
title: Turbopack
|
||||
description: Turbopack is an incremental bundler optimized for JavaScript and TypeScript, written in Rust, and built into Next.js.
|
||||
source: app/api-reference/turbopack
|
||||
---
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
---
|
||||
title: API Reference
|
||||
description: Next.js API Reference for the Pages Router.
|
||||
---
|
||||
Reference in New Issue
Block a user