Unverified Commit 3bf570d8 authored by Delba de Oliveira's avatar Delba de Oliveira Committed by GitHub

Docs IA 2.0: Images (#78769)

Closes:
- https://linear.app/vercel/issue/DOC-4626/images
- https://linear.app/vercel/issue/DOC-4610/split-image-and-font-pages

Redirects: https://github.com/vercel/next.js/pull/78769

**Housekeeping:** 
- Deletes BYA images page
- Creates relevant getting started docs in `/pages`
- Splits "Images and Fonts" into "Images" and "Fonts" pages to allow us
to add more context to each page in the future

**API reference**: 
- Improves image API reference to follow more of a consistent format and
language
- Adds examples

**Follow-up:** https://github.com/vercel/next.js/pull/78857
- Create a Deep Dive Guide on how image optimization works

---------
Co-authored-by: 's avatarRich Haines <hello@richardhaines.dev>
parent 5d85a444
---
title: How to optimize images
nav_title: Images
description: Learn how to optimize images in Next.js
related:
title: API Reference
description: See the API Reference for the full feature set of Next.js Image
links:
- app/api-reference/components/image
---
The Next.js [`<Image>`](/docs/app/api-reference/components/image) component extends the HTML `<img>` element to provide:
- **Size optimization:** Automatically serving correctly sized images for each device, using modern image formats like WebP.
- **Visual stability:** Preventing [layout shift](https://web.dev/articles/cls) automatically when images are loading.
- **Faster page loads:** Only loading images when they enter the viewport using native browser lazy loading, with optional blur-up placeholders.
- **Asset flexibility:** Resizing images on-demand, even images stored on remote servers.
To start using `<Image>`, import it from `next/image` and render it within your component.
```tsx filename="app/page.tsx" switcher
import Image from 'next/image'
export default function Page() {
return <Image src="" alt="" />
}
```
```jsx filename="app/page.js" switcher
import Image from 'next/image'
export default function Page() {
return <Image src="" alt="" />
}
```
The `src` property can be a [local](#local-images) or [remote](#remote-images) image.
> **🎥 Watch:** Learn more about how to use `next/image` → [YouTube (9 minutes)](https://youtu.be/IU_qq_c_lKA).
### Local images
You can store static files, like images and fonts, under a folder called [`public`](/docs/app/api-reference/file-conventions/public-folder) in the root directory. Files inside `public` can then be referenced by your code starting from the base URL (`/`).
<Image
alt="Folder structure showing app and public folders"
srcLight="/docs/light/public-folder.png"
srcDark="/docs/dark/public-folder.png"
width="1600"
height="282"
/>
```tsx filename="app/page.tsx" switcher
import Image from 'next/image'
export default function Page() {
return (
<Image
src="/profile.png"
alt="Picture of the author"
// width={500} automatically provided
// height={500} automatically provided
// blurDataURL="data:..." automatically provided
// placeholder="blur" // Optional blur-up while loading
/>
)
}
```
```jsx filename="app/page.js" switcher
import Image from 'next/image'
export default function Page() {
return (
<Image
src="/profile.png"
alt="Picture of the author"
// width={500} automatically provided
// height={500} automatically provided
// blurDataURL="data:..." automatically provided
// placeholder="blur" // Optional blur-up while loading
/>
)
}
```
When using local images, Next.js will automatically determine the intrinsic [`width`](/docs/app/api-reference/components/image#width-and-height) and [`height`](/docs/app/api-reference/components/image#width-and-height) of your image based on the imported file. These values are used to determine the image ratio and prevent [Cumulative Layout Shift](https://web.dev/articles/cls) while your image is loading.
### Remote images
To use a remote image, you can provide a URL string for the `src` property.
```tsx filename="app/page.tsx" switcher
import Image from 'next/image'
export default function Page() {
return (
<Image
src="https://s3.amazonaws.com/my-bucket/profile.png"
alt="Picture of the author"
width={500}
height={500}
/>
)
}
```
```jsx filename="app/page.js" switcher
import Image from 'next/image'
export default function Page() {
return (
<Image
src="https://s3.amazonaws.com/my-bucket/profile.png"
alt="Picture of the author"
width={500}
height={500}
/>
)
}
```
Since Next.js does not have access to remote files during the build process, you'll need to provide the [`width`](/docs/app/api-reference/components/image#width-and-height), [`height`](/docs/app/api-reference/components/image#width-and-height) and optional [`blurDataURL`](/docs/app/api-reference/components/image#blurdataurl) props manually. The `width` and `height` are used to infer the correct aspect ratio of image and avoid layout shift from the image loading in.
To safely allow images from remote servers, you need to define a list of supported URL patterns in [`next.config.js`](/docs/app/api-reference/config/next-config-js). Be as specific as possible to prevent malicious usage. For example, the following configuration will only allow images from a specific AWS S3 bucket:
```ts filename="next.config.ts" switcher
import { NextConfig } from 'next'
const config: NextConfig = {
images: {
remotePatterns: [
{
protocol: 'https',
hostname: 's3.amazonaws.com',
port: '',
pathname: '/my-bucket/**',
search: '',
},
],
},
}
export default config
```
```js filename="next.config.js" switcher
module.exports = {
images: {
remotePatterns: [
{
protocol: 'https',
hostname: 's3.amazonaws.com',
port: '',
pathname: '/my-bucket/**',
search: '',
},
],
},
}
```
--- ---
title: How to optimize images and fonts title: How to use fonts
nav_title: Images and Fonts nav_title: Fonts
description: Learn how to optimize images and fonts. description: Learn how to use fonts in Next.js
related: related:
title: API Reference title: API Reference
description: Learn more about the features mentioned in this page by reading the API Reference. description: See the API Reference for the full feature set of Next.js Font
links: links:
- app/api-reference/components/font - app/api-reference/components/font
- app/api-reference/components/image
--- ---
Next.js comes with automatic image and font optimization. This page will guide you through how to start using them.
## Optimizing images
The Next.js [`<Image>`](/docs/app/building-your-application/optimizing/images) component extends the HTML `<img>` element to provide:
- **Size optimization:** Automatically serving correctly sized images for each device, using modern image formats like WebP.
- **Visual stability:** Preventing [layout shift](https://web.dev/articles/cls) automatically when images are loading.
- **Faster page loads:** Only loading images when they enter the viewport using native browser lazy loading, with optional blur-up placeholders.
- **Asset flexibility:** Resizing images on-demand, even images stored on remote servers.
To start using `<Image>`, import it from `next/image` and render it within your component.
```tsx filename="app/page.tsx" switcher
import Image from 'next/image'
export default function Page() {
return <Image src="" alt="" />
}
```
```jsx filename="app/page.js" switcher
import Image from 'next/image'
export default function Page() {
return <Image src="" alt="" />
}
```
The `src` property can be a [local](#local-images) or [remote](#remote-images) image.
### Local images
You can store static files, like images and fonts, under a folder called `public` in the root directory. Files inside `public` can then be referenced by your code starting from the base URL (`/`).
<Image
alt="Folder structure showing app and public folders"
srcLight="/docs/light/public-folder.png"
srcDark="/docs/dark/public-folder.png"
width="1600"
height="282"
/>
```tsx filename="app/page.tsx" switcher
import Image from 'next/image'
import profilePic from './me.png'
export default function Page() {
return (
<Image
src={profilePic}
alt="Picture of the author"
// width={500} automatically provided
// height={500} automatically provided
// blurDataURL="data:..." automatically provided
// placeholder="blur" // Optional blur-up while loading
/>
)
}
```
```jsx filename="app/page.js" switcher
import Image from 'next/image'
import profilePic from './me.png'
export default function Page() {
return (
<Image
src={profilePic}
alt="Picture of the author"
// width={500} automatically provided
// height={500} automatically provided
// blurDataURL="data:..." automatically provided
// placeholder="blur" // Optional blur-up while loading
/>
)
}
```
Next.js will automatically determine the intrinsic [`width`](/docs/app/api-reference/components/image#width) and [`height`](/docs/app/api-reference/components/image#height) of your image based on the imported file. These values are used to determine the image ratio and prevent [Cumulative Layout Shift](https://web.dev/articles/cls) while your image is loading.
### Remote images
To use a remote image, you can provide a URL string for the `src` property.
```tsx filename="app/page.tsx" switcher
import Image from 'next/image'
export default function Page() {
return (
<Image
src="https://s3.amazonaws.com/my-bucket/profile.png"
alt="Picture of the author"
width={500}
height={500}
/>
)
}
```
```jsx filename="app/page.js" switcher
import Image from 'next/image'
export default function Page() {
return (
<Image
src="https://s3.amazonaws.com/my-bucket/profile.png"
alt="Picture of the author"
width={500}
height={500}
/>
)
}
```
Since Next.js does not have access to remote files during the build process, you'll need to provide the [`width`](/docs/app/api-reference/components/image#width), [`height`](/docs/app/api-reference/components/image#height) and optional [`blurDataURL`](/docs/app/api-reference/components/image#blurdataurl) props manually. The `width` and `height` are used to infer the correct aspect ratio of image and avoid layout shift from the image loading in.
To safely allow images from remote servers, you need to define a list of supported URL patterns in [`next.config.js`](/docs/app/api-reference/config/next-config-js). Be as specific as possible to prevent malicious usage. For example, the following configuration will only allow images from a specific AWS S3 bucket:
```ts filename="next.config.ts" switcher
import { NextConfig } from 'next'
const config: NextConfig = {
images: {
remotePatterns: [
{
protocol: 'https',
hostname: 's3.amazonaws.com',
port: '',
pathname: '/my-bucket/**',
search: '',
},
],
},
}
export default config
```
```js filename="next.config.js" switcher
module.exports = {
images: {
remotePatterns: [
{
protocol: 'https',
hostname: 's3.amazonaws.com',
port: '',
pathname: '/my-bucket/**',
search: '',
},
],
},
}
```
## Optimizing fonts
The [`next/font`](/docs/app/api-reference/components/font) module automatically optimizes your fonts and removes external network requests for improved privacy and performance. The [`next/font`](/docs/app/api-reference/components/font) module automatically optimizes your fonts and removes external network requests for improved privacy and performance.
It includes **built-in self-hosting** for any font file. This means you can optimally load web fonts with no layout shift. It includes **built-in self-hosting** for any font file. This means you can optimally load web fonts with no layout shift.
...@@ -205,9 +47,11 @@ export default function Layout({ children }) { ...@@ -205,9 +47,11 @@ export default function Layout({ children }) {
} }
``` ```
Fonts are scoped to the component they're used in. To apply a font to your entire application, add it to the [Root Layout](/docs/app/api-reference/file-conventions/layout#root-layouts).
### Google fonts ### Google fonts
You can automatically self-host any Google Font. Fonts are included in the deployment and served from the same domain as your deployment, meaning no requests are sent to Google by the browser when the user visits your site. You can automatically self-host any Google Font. Fonts are included stored as static assets and served from the same domain as your deployment, meaning no requests are sent to Google by the browser when the user visits your site.
To start using a Google Font, import your chosen font from `next/font/google`: To start using a Google Font, import your chosen font from `next/font/google`:
...@@ -289,7 +133,7 @@ export default function RootLayout({ children }) { ...@@ -289,7 +133,7 @@ export default function RootLayout({ children }) {
### Local fonts ### Local fonts
To use a local font, import your font from `next/font/local` and specify the [`src`](/docs/app/api-reference/components/font#src) of your local font file. To use a local font, import your font from `next/font/local` and specify the [`src`](/docs/app/api-reference/components/font#src) of your local font file. Fonts can be stored in the [`public`](/docs/app/api-reference/file-conventions/public-folder) folder. For example:
```tsx filename="app/layout.tsx" switcher ```tsx filename="app/layout.tsx" switcher
import localFont from 'next/font/local' import localFont from 'next/font/local'
......
...@@ -43,7 +43,7 @@ Depending on your needs, Next.js allows you to choose your data fetching strateg ...@@ -43,7 +43,7 @@ Depending on your needs, Next.js allows you to choose your data fetching strateg
### Built-in Optimizations ### Built-in Optimizations
[Images](/docs/app/building-your-application/optimizing/images), [fonts](/docs/app/api-reference/components/font), and [third-party scripts](/docs/app/guides/scripts) often have a large impact on an application’s performance. Next.js includes specialized components and APIs that automatically optimize them for you. [Images](/docs/app/api-reference/components/image), [fonts](/docs/app/api-reference/components/font), and [third-party scripts](/docs/app/guides/scripts) often have a large impact on an application’s performance. Next.js includes specialized components and APIs that automatically optimize them for you.
## Migration Steps ## Migration Steps
...@@ -414,9 +414,9 @@ export default function App() { ...@@ -414,9 +414,9 @@ export default function App() {
With Next.js, static image imports return an object. The object can then be used directly with the Next.js [`<Image>` component](/docs/app/api-reference/components/image), or you can use the object's `src` property with your existing `<img>` tag. With Next.js, static image imports return an object. The object can then be used directly with the Next.js [`<Image>` component](/docs/app/api-reference/components/image), or you can use the object's `src` property with your existing `<img>` tag.
The `<Image>` component has the added benefits of [automatic image optimization](/docs/app/building-your-application/optimizing/images). The `<Image>` component automatically sets the `width` and `height` attributes of the resulting `<img>` based on the image's dimensions. This prevents layout shifts when the image loads. However, this can cause issues if your app contains images with only one of their dimensions being styled without the other styled to `auto`. When not styled to `auto`, the dimension will default to the `<img>` dimension attribute's value, which can cause the image to appear distorted. The `<Image>` component has the added benefits of [automatic image optimization](/docs/app/api-reference/components/image). The `<Image>` component automatically sets the `width` and `height` attributes of the resulting `<img>` based on the image's dimensions. This prevents layout shifts when the image loads. However, this can cause issues if your app contains images with only one of their dimensions being styled without the other styled to `auto`. When not styled to `auto`, the dimension will default to the `<img>` dimension attribute's value, which can cause the image to appear distorted.
Keeping the `<img>` tag will reduce the amount of changes in your application and prevent the above issues. You can then optionally later migrate to the `<Image>` component to take advantage of optimizing images by [configuring a loader](/docs/app/building-your-application/optimizing/images#loaders), or moving to the default Next.js server which has automatic image optimization. Keeping the `<img>` tag will reduce the amount of changes in your application and prevent the above issues. You can then optionally later migrate to the `<Image>` component to take advantage of optimizing images by [configuring a loader](/docs/app/api-reference/components/image#loader), or moving to the default Next.js server which has automatic image optimization.
**Convert absolute import paths for images imported from `/public` into relative imports:** **Convert absolute import paths for images imported from `/public` into relative imports:**
...@@ -573,7 +573,7 @@ If everything worked, you now have a functioning Next.js application running as ...@@ -573,7 +573,7 @@ If everything worked, you now have a functioning Next.js application running as
- Automatic code splitting - Automatic code splitting
- [Streaming server rendering](/docs/app/building-your-application/routing/loading-ui-and-streaming) - [Streaming server rendering](/docs/app/building-your-application/routing/loading-ui-and-streaming)
- [React Server Components](/docs/app/building-your-application/rendering/server-components) - [React Server Components](/docs/app/building-your-application/rendering/server-components)
- **Optimize images** with the [`<Image>` component](/docs/app/building-your-application/optimizing/images) - **Optimize images** with the [`<Image>` component](/docs/app/api-reference/components/image)
- **Optimize fonts** with [`next/font`](/docs/app/api-reference/components/font) - **Optimize fonts** with [`next/font`](/docs/app/api-reference/components/font)
- **Optimize third-party scripts** with the [`<Script>` component](/docs/app/guides/scripts) - **Optimize third-party scripts** with the [`<Script>` component](/docs/app/guides/scripts)
- **Enable ESLint** with Next.js recommended rules by running `npx next lint` and configuring it to match your project’s needs - **Enable ESLint** with Next.js recommended rules by running `npx next lint` and configuring it to match your project’s needs
......
...@@ -43,7 +43,7 @@ Depending on your needs, Next.js allows you to choose your data fetching strateg ...@@ -43,7 +43,7 @@ Depending on your needs, Next.js allows you to choose your data fetching strateg
### Built-in Optimizations ### Built-in Optimizations
[Images](/docs/app/building-your-application/optimizing/images), [fonts](/docs/app/api-reference/components/font), and [third-party scripts](/docs/app/guides/scripts) often have significant impact on an application's performance. Next.js comes with built-in components that automatically optimize those for you. [Images](/docs/app/api-reference/components/image), [fonts](/docs/app/api-reference/components/font), and [third-party scripts](/docs/app/guides/scripts) often have significant impact on an application's performance. Next.js comes with built-in components that automatically optimize those for you.
## Migration Steps ## Migration Steps
...@@ -469,7 +469,7 @@ Next.js [`<Image>` component](/docs/app/api-reference/components/image), or you ...@@ -469,7 +469,7 @@ Next.js [`<Image>` component](/docs/app/api-reference/components/image), or you
`src` property with your existing `<img>` tag. `src` property with your existing `<img>` tag.
The `<Image>` component has the added benefits of The `<Image>` component has the added benefits of
[automatic image optimization](/docs/app/building-your-application/optimizing/images). The `<Image>` [automatic image optimization](/docs/app/api-reference/components/image). The `<Image>`
component automatically sets the `width` and `height` attributes of the resulting `<img>` based on component automatically sets the `width` and `height` attributes of the resulting `<img>` based on
the image's dimensions. This prevents layout shifts when the image loads. However, this can cause the image's dimensions. This prevents layout shifts when the image loads. However, this can cause
issues if your app contains images with only one of their dimensions being styled without the other issues if your app contains images with only one of their dimensions being styled without the other
...@@ -477,7 +477,7 @@ styled to `auto`. When not styled to `auto`, the dimension will default to the ` ...@@ -477,7 +477,7 @@ styled to `auto`. When not styled to `auto`, the dimension will default to the `
attribute's value, which can cause the image to appear distorted. attribute's value, which can cause the image to appear distorted.
Keeping the `<img>` tag will reduce the amount of changes in your application and prevent the above Keeping the `<img>` tag will reduce the amount of changes in your application and prevent the above
issues. You can then optionally later migrate to the `<Image>` component to take advantage of optimizing images by [configuring a loader](/docs/app/building-your-application/optimizing/images#loaders), or moving to the default Next.js server which has automatic image optimization. issues. You can then optionally later migrate to the `<Image>` component to take advantage of optimizing images by [configuring a loader](/docs/app/api-reference/components/image#loader), or moving to the default Next.js server which has automatic image optimization.
1. **Convert absolute import paths for images imported from `/public` into relative imports:** 1. **Convert absolute import paths for images imported from `/public` into relative imports:**
...@@ -596,7 +596,7 @@ do next: ...@@ -596,7 +596,7 @@ do next:
- Automatic code splitting - Automatic code splitting
- [Streaming Server-Rendering](/docs/app/building-your-application/routing/loading-ui-and-streaming) - [Streaming Server-Rendering](/docs/app/building-your-application/routing/loading-ui-and-streaming)
- [React Server Components](/docs/app/building-your-application/rendering/server-components) - [React Server Components](/docs/app/building-your-application/rendering/server-components)
- [Optimize images with the `<Image>` component](/docs/app/building-your-application/optimizing/images) - [Optimize images with the `<Image>` component](/docs/app/api-reference/components/image)
- [Optimize fonts with `next/font`](/docs/app/api-reference/components/font) - [Optimize fonts with `next/font`](/docs/app/api-reference/components/font)
- [Optimize third-party scripts with the `<Script>` component](/docs/app/guides/scripts) - [Optimize third-party scripts with the `<Script>` component](/docs/app/guides/scripts)
- [Update your ESLint configuration to support Next.js rules](/docs/app/api-reference/config/eslint) - [Update your ESLint configuration to support Next.js rules](/docs/app/api-reference/config/eslint)
...@@ -88,7 +88,7 @@ While building your application, we recommend using the following features to en ...@@ -88,7 +88,7 @@ While building your application, we recommend using the following features to en
</AppOnly> </AppOnly>
- **[Font Module](/docs/app/api-reference/components/font):** Optimize fonts by using the Font Module, which automatically hosts your font files with other static assets, removes external network requests, and reduces [layout shift](https://web.dev/articles/cls). - **[Font Module](/docs/app/api-reference/components/font):** Optimize fonts by using the Font Module, which automatically hosts your font files with other static assets, removes external network requests, and reduces [layout shift](https://web.dev/articles/cls).
- **[`<Image>` Component](/docs/app/building-your-application/optimizing/images):** Optimize images by using the Image Component, which automatically optimizes images, prevents layout shift, and serves them in modern formats like WebP. - **[`<Image>` Component](/docs/app/api-reference/components/image):** Optimize images by using the Image Component, which automatically optimizes images, prevents layout shift, and serves them in modern formats like WebP.
- **[`<Script>` Component](/docs/app/guides/scripts):** Optimize third-party scripts by using the Script Component, which automatically defers scripts and prevents them from blocking the main thread. - **[`<Script>` Component](/docs/app/guides/scripts):** Optimize third-party scripts by using the Script Component, which automatically defers scripts and prevents them from blocking the main thread.
- **[ESLint](/docs/architecture/accessibility#linting):** Use the built-in `eslint-plugin-jsx-a11y` plugin to catch accessibility issues early. - **[ESLint](/docs/architecture/accessibility#linting):** Use the built-in `eslint-plugin-jsx-a11y` plugin to catch accessibility issues early.
......
...@@ -12,14 +12,14 @@ When [deploying](docs/app/getting-started/deploying) your Next.js app, you may w ...@@ -12,14 +12,14 @@ When [deploying](docs/app/getting-started/deploying) your Next.js app, you may w
## Image Optimization ## Image Optimization
[Image Optimization](/docs/app/building-your-application/optimizing/images) through `next/image` works self-hosted with zero configuration when deploying using `next start`. If you would prefer to have a separate service to optimize images, you can [configure an image loader](/docs/app/building-your-application/optimizing/images#loaders). [Image Optimization](/docs/app/api-reference/components/image) through `next/image` works self-hosted with zero configuration when deploying using `next start`. If you would prefer to have a separate service to optimize images, you can [configure an image loader](/docs/app/api-reference/components/image#loader).
Image Optimization can be used with a [static export](/docs/app/guides/static-exports#image-optimization) by defining a custom image loader in `next.config.js`. Note that images are optimized at runtime, not during the build. Image Optimization can be used with a [static export](/docs/app/guides/static-exports#image-optimization) by defining a custom image loader in `next.config.js`. Note that images are optimized at runtime, not during the build.
> **Good to know:** > **Good to know:**
> >
> - On glibc-based Linux systems, Image Optimization may require [additional configuration](https://sharp.pixelplumbing.com/install#linux-memory-allocator) to prevent excessive memory usage. > - On glibc-based Linux systems, Image Optimization may require [additional configuration](https://sharp.pixelplumbing.com/install#linux-memory-allocator) to prevent excessive memory usage.
> - Learn more about the [caching behavior of optimized images](/docs/app/api-reference/components/image#caching-behavior) and how to configure the TTL. > - Learn more about the [caching behavior of optimized images](/docs/app/api-reference/components/image#minimumcachettl) and how to configure the TTL.
> - You can also [disable Image Optimization](/docs/app/api-reference/components/image#unoptimized) and still retain other benefits of using `next/image` if you prefer. For example, if you are optimizing images yourself separately. > - You can also [disable Image Optimization](/docs/app/api-reference/components/image#unoptimized) and still retain other benefits of using `next/image` if you prefer. For example, if you are optimizing images yourself separately.
## Middleware ## Middleware
...@@ -91,7 +91,7 @@ You can configure the Next.js cache location if you want to persist cached pages ...@@ -91,7 +91,7 @@ You can configure the Next.js cache location if you want to persist cached pages
### Automatic Caching ### Automatic Caching
- Next.js sets the `Cache-Control` header of `public, max-age=31536000, immutable` to truly immutable assets. It cannot be overridden. These immutable files contain a SHA-hash in the file name, so they can be safely cached indefinitely. For example, [Static Image Imports](/docs/app/building-your-application/optimizing/images#local-images). You can [configure the TTL](/docs/app/api-reference/components/image#caching-behavior) for images. - Next.js sets the `Cache-Control` header of `public, max-age=31536000, immutable` to truly immutable assets. It cannot be overridden. These immutable files contain a SHA-hash in the file name, so they can be safely cached indefinitely. For example, [Static Image Imports](/docs/app/getting-started/images#local-images). You can [configure the TTL](/docs/app/api-reference/components/image#minimumcachettl) for images.
- Incremental Static Regeneration (ISR) sets the `Cache-Control` header of `s-maxage: <revalidate in getStaticProps>, stale-while-revalidate`. This revalidation time is defined in your [`getStaticProps` function](/docs/pages/building-your-application/data-fetching/get-static-props) in seconds. If you set `revalidate: false`, it will default to a one-year cache duration. - Incremental Static Regeneration (ISR) sets the `Cache-Control` header of `s-maxage: <revalidate in getStaticProps>, stale-while-revalidate`. This revalidation time is defined in your [`getStaticProps` function](/docs/pages/building-your-application/data-fetching/get-static-props) in seconds. If you set `revalidate: false`, it will default to a one-year cache duration.
- Dynamically rendered pages set a `Cache-Control` header of `private, no-cache, no-store, max-age=0, must-revalidate` to prevent user-specific data from being cached. This applies to both the App Router and Pages Router. This also includes [Draft Mode](/docs/app/guides/draft-mode). - Dynamically rendered pages set a `Cache-Control` header of `private, no-cache, no-store, max-age=0, must-revalidate` to prevent user-specific data from being cached. This applies to both the App Router and Pages Router. This also includes [Draft Mode](/docs/app/guides/draft-mode).
......
...@@ -167,7 +167,7 @@ The majority of core Next.js features needed to build a static site are supporte ...@@ -167,7 +167,7 @@ The majority of core Next.js features needed to build a static site are supporte
### Image Optimization ### Image Optimization
[Image Optimization](/docs/app/building-your-application/optimizing/images) through `next/image` can be used with a static export by defining a custom image loader in `next.config.js`. For example, you can optimize images with a service like Cloudinary: [Image Optimization](/docs/app/api-reference/components/image) through `next/image` can be used with a static export by defining a custom image loader in `next.config.js`. For example, you can optimize images with a service like Cloudinary:
```js filename="next.config.js" ```js filename="next.config.js"
/** @type {import('next').NextConfig} */ /** @type {import('next').NextConfig} */
...@@ -286,7 +286,7 @@ Features that require a Node.js server, or dynamic logic that cannot be computed ...@@ -286,7 +286,7 @@ Features that require a Node.js server, or dynamic logic that cannot be computed
- [Headers](/docs/app/api-reference/config/next-config-js/headers) - [Headers](/docs/app/api-reference/config/next-config-js/headers)
- [Middleware](/docs/app/building-your-application/routing/middleware) - [Middleware](/docs/app/building-your-application/routing/middleware)
- [Incremental Static Regeneration](/docs/app/building-your-application/data-fetching/incremental-static-regeneration) - [Incremental Static Regeneration](/docs/app/building-your-application/data-fetching/incremental-static-regeneration)
- [Image Optimization](/docs/app/building-your-application/optimizing/images) with the default `loader` - [Image Optimization](/docs/app/api-reference/components/image) with the default `loader`
- [Draft Mode](/docs/app/guides/draft-mode) - [Draft Mode](/docs/app/guides/draft-mode)
- [Server Actions](/docs/app/building-your-application/data-fetching/server-actions-and-mutations) - [Server Actions](/docs/app/building-your-application/data-fetching/server-actions-and-mutations)
- [Intercepting Routes](/docs/app/building-your-application/routing/intercepting-routes) - [Intercepting Routes](/docs/app/building-your-application/routing/intercepting-routes)
...@@ -308,7 +308,7 @@ export const dynamic = 'error' ...@@ -308,7 +308,7 @@ export const dynamic = 'error'
- [Headers](/docs/pages/api-reference/config/next-config-js/headers) - [Headers](/docs/pages/api-reference/config/next-config-js/headers)
- [Middleware](/docs/pages/building-your-application/routing/middleware) - [Middleware](/docs/pages/building-your-application/routing/middleware)
- [Incremental Static Regeneration](/docs/pages/building-your-application/data-fetching/incremental-static-regeneration) - [Incremental Static Regeneration](/docs/pages/building-your-application/data-fetching/incremental-static-regeneration)
- [Image Optimization](/docs/pages/building-your-application/optimizing/images) with the default `loader` - [Image Optimization](/docs/pages/api-reference/components/image) with the default `loader`
- [Draft Mode](/docs/pages/guides/draft-mode) - [Draft Mode](/docs/pages/guides/draft-mode)
- [`getStaticPaths` with `fallback: true`](/docs/pages/api-reference/functions/get-static-paths#fallback-true) - [`getStaticPaths` with `fallback: true`](/docs/pages/api-reference/functions/get-static-paths#fallback-true)
- [`getStaticPaths` with `fallback: 'blocking'`](/docs/pages/api-reference/functions/get-static-paths#fallback-blocking) - [`getStaticPaths` with `fallback: 'blocking'`](/docs/pages/api-reference/functions/get-static-paths#fallback-blocking)
......
...@@ -388,7 +388,7 @@ module.exports = { ...@@ -388,7 +388,7 @@ module.exports = {
## Cache-Control ## Cache-Control
Next.js sets the `Cache-Control` header of `public, max-age=31536000, immutable` for truly immutable assets. It cannot be overridden. These immutable files contain a SHA-hash in the file name, so they can be safely cached indefinitely. For example, [Static Image Imports](/docs/app/building-your-application/optimizing/images#local-images). You cannot set `Cache-Control` headers in `next.config.js` for these assets. Next.js sets the `Cache-Control` header of `public, max-age=31536000, immutable` for truly immutable assets. It cannot be overridden. These immutable files contain a SHA-hash in the file name, so they can be safely cached indefinitely. For example, [Static Image Imports](/docs/app/getting-started/images#local-images). You cannot set `Cache-Control` headers in `next.config.js` for these assets.
However, you can set `Cache-Control` headers for other responses or data. However, you can set `Cache-Control` headers for other responses or data.
......
...@@ -32,7 +32,7 @@ Alternatively, you can use the [`loader` prop](/docs/app/api-reference/component ...@@ -32,7 +32,7 @@ Alternatively, you can use the [`loader` prop](/docs/app/api-reference/component
> **Good to know**: Customizing the image loader file, which accepts a function, requires using [Client Components](/docs/app/building-your-application/rendering/client-components) to serialize the provided function. > **Good to know**: Customizing the image loader file, which accepts a function, requires using [Client Components](/docs/app/building-your-application/rendering/client-components) to serialize the provided function.
To learn more about configuring the behavior of the built-in [Image Optimization API](/docs/app/building-your-application/optimizing/images) and the [Image Component](/docs/app/api-reference/components/image), see [Image Configuration Options](/docs/app/api-reference/components/image#configuration-options) for available options. To learn more about configuring the behavior of the built-in [Image Optimization API](/docs/app/api-reference/components/image) and the [Image Component](/docs/app/api-reference/components/image), see [Image Configuration Options](/docs/app/api-reference/components/image#configuration-options) for available options.
</AppOnly> </AppOnly>
...@@ -46,7 +46,7 @@ export default function myImageLoader({ src, width, quality }) { ...@@ -46,7 +46,7 @@ export default function myImageLoader({ src, width, quality }) {
Alternatively, you can use the [`loader` prop](/docs/pages/api-reference/components/image#loader) to pass the function to each instance of `next/image`. Alternatively, you can use the [`loader` prop](/docs/pages/api-reference/components/image#loader) to pass the function to each instance of `next/image`.
To learn more about configuring the behavior of the built-in [Image Optimization API](/docs/pages/building-your-application/optimizing/images) and the [Image Component](/docs/pages/api-reference/components/image), see [Image Configuration Options](/docs/pages/api-reference/components/image#configuration-options) for available options. To learn more about configuring the behavior of the built-in [Image Optimization API](/docs/pages/api-reference/components/image) and the [Image Component](/docs/pages/api-reference/components/image), see [Image Configuration Options](/docs/pages/api-reference/components/image#configuration-options) for available options.
</PagesOnly> </PagesOnly>
......
...@@ -2,7 +2,12 @@ ...@@ -2,7 +2,12 @@
title: Image Optimization title: Image Optimization
nav_title: Images nav_title: Images
description: Optimize your images with the built-in `next/image` component. description: Optimize your images with the built-in `next/image` component.
source: app/building-your-application/optimizing/images related:
title: API Reference
description: See the API Reference for the full feature set of Next.js Image
links:
- pages/api-reference/components/image
source: app/getting-started/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. */} {/* 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. */}
---
title: How to use fonts
nav_title: Fonts
description: Learn how to use fonts in Next.js
related:
title: API Reference
description: See the API Reference for the full feature set of Next.js Font
links:
- pages/api-reference/components/font
source: app/getting-started/fonts
---
{/* 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. */}
...@@ -88,7 +88,7 @@ If your application has specific CSS targeting the `next/image` `<div>` tag, for ...@@ -88,7 +88,7 @@ If your application has specific CSS targeting the `next/image` `<div>` tag, for
The `className` prop is unchanged and will still be passed to the underlying `<img>` element. The `className` prop is unchanged and will still be passed to the underlying `<img>` element.
See the [documentation](/docs/pages/building-your-application/optimizing/images#styling) for more info. See the [documentation](/docs/pages/api-reference/components/image#styling-images) for more info.
#### HMR connection now uses a WebSocket #### HMR connection now uses a WebSocket
......
...@@ -32,7 +32,7 @@ The `<Image />` component requires the following properties. ...@@ -32,7 +32,7 @@ The `<Image />` component requires the following properties.
Must be one of the following: Must be one of the following:
- A [statically imported](/docs/pages/building-your-application/optimizing/images#local-images) image file - 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). - 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 using the default [loader](#loader), also consider the following for source images:
...@@ -49,7 +49,7 @@ When using `layout="intrinsic"` or `layout="fixed"` the `width` property represe ...@@ -49,7 +49,7 @@ When using `layout="intrinsic"` or `layout="fixed"` the `width` property represe
When using `layout="responsive"`, `layout="fill"`, the `width` property represents the _original_ width in pixels, so it will only affect the aspect ratio. 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/building-your-application/optimizing/images#local-images), or those with `layout="fill"`. The `width` property is required, except for [statically imported images](/docs/pages/api-reference/components/image#src), or those with `layout="fill"`.
### height ### height
...@@ -59,7 +59,7 @@ When using `layout="intrinsic"` or `layout="fixed"` the `height` property repres ...@@ -59,7 +59,7 @@ When using `layout="intrinsic"` or `layout="fixed"` the `height` property repres
When using `layout="responsive"`, `layout="fill"`, the `height` property represents the _original_ height in pixels, so it will only affect the aspect ratio. 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/building-your-application/optimizing/images#local-images), or those with `layout="fill"`. The `height` property is required, except for [statically imported images](/docs/pages/api-reference/components/image#src), or those with `layout="fill"`.
## Optional Props ## Optional Props
...@@ -172,7 +172,7 @@ Should only be used when the image is visible above the fold. Defaults to `false ...@@ -172,7 +172,7 @@ Should only be used when the image is visible above the fold. Defaults to `false
A placeholder to use while the image is loading. Possible values are `blur` or `empty`. Defaults to `empty`. 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/building-your-application/optimizing/images#local-images) and the imported image is `.jpg`, `.png`, `.webp`, or `.avif`, then `blurDataURL` will be automatically populated. 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. 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.
...@@ -542,7 +542,7 @@ The expiration (or rather Max Age) is defined by either the [`minimumCacheTTL`]( ...@@ -542,7 +542,7 @@ The expiration (or rather Max Age) is defined by either the [`minimumCacheTTL`](
### Minimum Cache TTL ### 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/building-your-application/optimizing/images#local-images) which will automatically hash the file contents and cache the image forever with a `Cache-Control` header of `immutable`. 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. If no configuration is provided, the default below is used.
......
...@@ -20,7 +20,7 @@ This is because Next.js optimizes images on-demand, as users request them (not a ...@@ -20,7 +20,7 @@ This is because Next.js optimizes images on-demand, as users request them (not a
## Useful Links ## Useful Links
- [Deployment Documentation](/docs/pages/getting-started/deploying) - [Deployment Documentation](/docs/pages/getting-started/deploying)
- [Image Optimization Documentation](/docs/pages/building-your-application/optimizing/images) - [Image Optimization Documentation](/docs/pages/api-reference/components/image)
- [`output: 'export'` Documentation](/docs/pages/guides/static-exports) - [`output: 'export'` Documentation](/docs/pages/guides/static-exports)
- [`next/image` Documentation](/docs/pages/api-reference/components/image) - [`next/image` Documentation](/docs/pages/api-reference/components/image)
- [Vercel Documentation](https://vercel.com/docs/concepts/next.js/image-optimization) - [Vercel Documentation](https://vercel.com/docs/concepts/next.js/image-optimization)
...@@ -4,7 +4,7 @@ title: 'Install `sharp` to Use Built-In Image Optimization' ...@@ -4,7 +4,7 @@ title: 'Install `sharp` to Use Built-In Image Optimization'
## Why This Error Occurred ## Why This Error Occurred
Using Next.js' built-in [Image Optimization](/docs/pages/building-your-application/optimizing/images) requires [sharp](https://www.npmjs.com/package/sharp) as a dependency. Using Next.js' built-in [Image Optimization](/docs/pages/api-reference/components/image) requires [sharp](https://www.npmjs.com/package/sharp) as a dependency.
You are seeing this error because your OS was unable to [install sharp](https://sharp.pixelplumbing.com/install) properly, either using pre-built binaries or building from source. You are seeing this error because your OS was unable to [install sharp](https://sharp.pixelplumbing.com/install) properly, either using pre-built binaries or building from source.
......
...@@ -51,5 +51,5 @@ module.exports = { ...@@ -51,5 +51,5 @@ module.exports = {
## Useful Links ## Useful Links
- [Image Optimization Documentation](/docs/pages/building-your-application/optimizing/images) - [Image Optimization Documentation](/docs/pages/api-reference/components/image)
- [`next/image` Documentation](/docs/pages/api-reference/components/image) - [`next/image` Documentation](/docs/pages/api-reference/components/image)
...@@ -15,5 +15,5 @@ This error occurred because the provided `loader()` function did not use `width` ...@@ -15,5 +15,5 @@ This error occurred because the provided `loader()` function did not use `width`
## Useful Links ## Useful Links
- [Image Optimization Documentation](/docs/pages/building-your-application/optimizing/images) - [Image Optimization Documentation](/docs/pages/api-reference/components/image)
- [`next/image` Documentation](/docs/pages/api-reference/components/image) - [`next/image` Documentation](/docs/pages/api-reference/components/image)
...@@ -13,5 +13,5 @@ When using the `next/image` component with [`loader="custom"`](/docs/app/api-ref ...@@ -13,5 +13,5 @@ When using the `next/image` component with [`loader="custom"`](/docs/app/api-ref
## Useful Links ## Useful Links
- [Image Optimization Documentation](/docs/pages/building-your-application/optimizing/images) - [Image Optimization Documentation](/docs/pages/api-reference/components/image)
- [`next/image` Documentation](/docs/pages/api-reference/components/image) - [`next/image` Documentation](/docs/pages/api-reference/components/image)
...@@ -60,5 +60,5 @@ module.exports = { ...@@ -60,5 +60,5 @@ module.exports = {
## Useful Links ## Useful Links
- [Image Optimization Documentation](/docs/pages/building-your-application/optimizing/images) - [Image Optimization Documentation](/docs/pages/api-reference/components/image)
- [Remote Patterns Documentation](/docs/pages/api-reference/components/image#remotepatterns) - [Remote Patterns Documentation](/docs/pages/api-reference/components/image#remotepatterns)
...@@ -25,5 +25,5 @@ module.exports = { ...@@ -25,5 +25,5 @@ module.exports = {
## Useful Links ## Useful Links
- [Image Optimization Documentation](/docs/pages/building-your-application/optimizing/images) - [Image Optimization Documentation](/docs/pages/api-reference/components/image)
- [Local Patterns Documentation](/docs/pages/api-reference/components/image#localpatterns) - [Local Patterns Documentation](/docs/pages/api-reference/components/image#localpatterns)
...@@ -20,5 +20,5 @@ module.exports = { ...@@ -20,5 +20,5 @@ module.exports = {
## Useful Links ## Useful Links
- [Image Optimization Documentation](/docs/pages/building-your-application/optimizing/images) - [Image Optimization Documentation](/docs/pages/api-reference/components/image)
- [Qualities Config Documentation](/docs/pages/api-reference/components/image#qualities) - [Qualities Config Documentation](/docs/pages/api-reference/components/image#qualities)
...@@ -10,7 +10,7 @@ An `<img>` element was used to display an image instead of `<Image />` from `nex ...@@ -10,7 +10,7 @@ An `<img>` element was used to display an image instead of `<Image />` from `nex
## Possible Ways to Fix It ## Possible Ways to Fix It
1. Use [`next/image`](/docs/pages/api-reference/components/image) to improve performance with automatic [Image Optimization](/docs/pages/building-your-application/optimizing/images). 1. Use [`next/image`](/docs/pages/api-reference/components/image) to improve performance with automatic [Image Optimization](/docs/pages/api-reference/components/image).
> **Note**: If deploying to a [managed hosting provider](/docs/pages/getting-started/deploying), remember to check provider pricing since optimized images might be charged differently than the original images. > **Note**: If deploying to a [managed hosting provider](/docs/pages/getting-started/deploying), remember to check provider pricing since optimized images might be charged differently than the original images.
> >
...@@ -68,7 +68,7 @@ function Home() { ...@@ -68,7 +68,7 @@ function Home() {
} }
``` ```
4. You can use a [custom image loader](/docs/pages/building-your-application/optimizing/images#loaders) to optimize images. Set [loaderFile](/docs/pages/api-reference/components/image#loaderfile) to the path of your custom loader. 4. You can use a [custom image loader](/docs/pages/api-reference/components/image#loader) to optimize images. Set [loaderFile](/docs/pages/api-reference/components/image#loaderfile) to the path of your custom loader.
```js filename="next.config.js" ```js filename="next.config.js"
module.exports = { module.exports = {
...@@ -81,7 +81,7 @@ module.exports = { ...@@ -81,7 +81,7 @@ module.exports = {
## Useful Links ## Useful Links
- [Image Component and Image Optimization](/docs/pages/building-your-application/optimizing/images) - [Image Component and Image Optimization](/docs/pages/api-reference/components/image)
- [next/image API Reference](/docs/pages/api-reference/components/image) - [next/image API Reference](/docs/pages/api-reference/components/image)
- [Largest Contentful Paint (LCP)](/learn/seo/web-performance/lcp) - [Largest Contentful Paint (LCP)](/learn/seo/web-performance/lcp)
- [Next.js config loaderFile option](/docs/pages/api-reference/components/image#loaderfile) - [Next.js config loaderFile option](/docs/pages/api-reference/components/image#loaderfile)
...@@ -42,6 +42,6 @@ Then, build your project with `next build`. Finally, restart the server with eit ...@@ -42,6 +42,6 @@ Then, build your project with `next build`. Finally, restart the server with eit
## Useful Links ## Useful Links
- [Image Optimization Documentation](/docs/pages/building-your-application/optimizing/images) - [Image Optimization Documentation](/docs/pages/api-reference/components/image)
- [`next/image` Documentation](/docs/pages/api-reference/components/image) - [`next/image` Documentation](/docs/pages/api-reference/components/image)
- [Output File Tracing](/docs/pages/api-reference/config/next-config-js/output) - [Output File Tracing](/docs/pages/api-reference/config/next-config-js/output)
...@@ -22,5 +22,5 @@ After choosing an option above, reboot the server by running either `next dev` o ...@@ -22,5 +22,5 @@ After choosing an option above, reboot the server by running either `next dev` o
## Useful Links ## Useful Links
- [Image Optimization Documentation](/docs/pages/building-your-application/optimizing/images) - [Image Optimization Documentation](/docs/pages/api-reference/components/image)
- [`next/image` Documentation](/docs/pages/api-reference/components/image) - [`next/image` Documentation](/docs/pages/api-reference/components/image)
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment