Unverified Commit 1dd580da authored by Kazi Mahbubur Rahman's avatar Kazi Mahbubur Rahman Committed by GitHub

docs: add example for enabling both AVIF and WebP image formats for better image…

docs: add example for enabling both AVIF and WebP image formats for better image optimization (#86191)

## Title
docs: add example for enabling both AVIF and WebP image formats

## Description

### What?
This PR enhances the image component documentation by adding examples
showing how to enable both AVIF and WebP image formats together in
`next.config.js`. It also updates the `image-component` example to
demonstrate this configuration.

### Why?
Currently, the documentation only shows examples for:
- WebP only (default): `formats: ['image/webp']`
- AVIF only: `formats: ['image/avif']`

However, many developers want to enable both formats together to:
- Prefer AVIF for browsers that support it (better compression, ~20%
smaller files)
- Fall back to WebP for broader browser compatibility
- Maximize image optimization across different browsers

This configuration is a best practice but wasn't clearly documented with
an example.

### How?
- Added example configuration `formats: ['image/avif', 'image/webp']` to
App Router image component documentation
- Added the same example to Pages Router (legacy) image component
documentation for consistency
- Updated `examples/image-component/next.config.js` to demonstrate the
configuration
- Added clarification that the order matters - Next.js uses the first
format in the array that the browser supports

### Changes Made
- `docs/01-app/03-api-reference/02-components/image.mdx` - Added AVIF +
WebP example
- `docs/02-pages/04-api-reference/01-components/image-legacy.mdx` -
Added AVIF + WebP example
- `examples/image-component/next.config.js` - Added formats
configuration

### Testing
- [x] Documentation changes only - no code changes
- [x] Verified examples are syntactically correct
- [x] Checked that formatting follows Next.js documentation guidelines

### Checklist
- [x] Run `pnpm prettier-fix` to fix formatting issues (if applicable)
- [x] Documentation follows the docs guidelines
- [x] Changes are clear and helpful for developers

---------
Co-authored-by: 's avatarJoseph <joseph.chamochumbi@vercel.com>
parent f7b7f3c1
...@@ -752,10 +752,21 @@ module.exports = { ...@@ -752,10 +752,21 @@ module.exports = {
} }
``` ```
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**: > **Good to know**:
> >
> - We still recommend using WebP for most use cases. > - 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, but subsequent requests that are cached will be faster. > - 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, but 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. > - If you self-host with a Proxy/CDN in front of Next.js, you must configure the Proxy to forward the `Accept` header.
#### `minimumCacheTTL` #### `minimumCacheTTL`
......
...@@ -528,10 +528,21 @@ module.exports = { ...@@ -528,10 +528,21 @@ module.exports = {
} }
``` ```
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**: > **Good to know**:
> >
> - We still recommend using WebP for most use cases. > - 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. > - 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. > - If you self-host with a Proxy/CDN in front of Next.js, you must configure the Proxy to forward the `Accept` header.
## Caching Behavior ## Caching Behavior
......
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