From f7b0866727e55da00ffe0ee3d0882a86a0ccc103 Mon Sep 17 00:00:00 2001 From: KaziMahbuburRahman Date: Mon, 17 Nov 2025 01:49:45 +0600 Subject: [PATCH 1/3] Enhance image component documentation to include support for AVIF and WebP formats. Added configuration examples and clarified caching behavior for multiple formats. --- docs/01-app/03-api-reference/02-components/image.mdx | 11 +++++++++++ .../04-api-reference/01-components/image-legacy.mdx | 11 +++++++++++ examples/image-component/next.config.js | 1 + 3 files changed, 23 insertions(+) diff --git a/docs/01-app/03-api-reference/02-components/image.mdx b/docs/01-app/03-api-reference/02-components/image.mdx index e25a531a76a33..69623fae4f80b 100644 --- a/docs/01-app/03-api-reference/02-components/image.mdx +++ b/docs/01-app/03-api-reference/02-components/image.mdx @@ -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**: > > - 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. +> - When using multiple formats, the order matters. Next.js will use the first format in the array that the browser supports. > - If you self-host with a Proxy/CDN in front of Next.js, you must configure the Proxy to forward the `Accept` header. #### `minimumCacheTTL` diff --git a/docs/02-pages/04-api-reference/01-components/image-legacy.mdx b/docs/02-pages/04-api-reference/01-components/image-legacy.mdx index ba921c214eaa8..26e8f50719e57 100644 --- a/docs/02-pages/04-api-reference/01-components/image-legacy.mdx +++ b/docs/02-pages/04-api-reference/01-components/image-legacy.mdx @@ -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**: > > - 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, the order matters. Next.js will use the first format in the array that the browser supports. > - 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 diff --git a/examples/image-component/next.config.js b/examples/image-component/next.config.js index 450c646e2520c..5b1853fe7bf7e 100644 --- a/examples/image-component/next.config.js +++ b/examples/image-component/next.config.js @@ -1,6 +1,7 @@ /** @type {import('next').NextConfig} */ module.exports = { images: { + formats: ['image/avif', 'image/webp'], remotePatterns: [ { protocol: "https", From 3709cfe1278707c2d675aa216ad1da582f9c2371 Mon Sep 17 00:00:00 2001 From: KaziMahbuburRahman Date: Mon, 17 Nov 2025 23:51:12 +0600 Subject: [PATCH 2/3] docs: address reviewer feedback on AVIF/WebP formats example - Add note about cache overhead when using multiple formats - Remove redundant note about array order (already mentioned earlier) Addresses feedback about documenting increased storage requirements when enabling both AVIF and WebP formats, and removes duplicate information about format order. --- docs/01-app/03-api-reference/02-components/image.mdx | 2 +- docs/02-pages/04-api-reference/01-components/image-legacy.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/01-app/03-api-reference/02-components/image.mdx b/docs/01-app/03-api-reference/02-components/image.mdx index 69623fae4f80b..bc0e096b2cdab 100644 --- a/docs/01-app/03-api-reference/02-components/image.mdx +++ b/docs/01-app/03-api-reference/02-components/image.mdx @@ -766,7 +766,7 @@ module.exports = { > > - 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. -> - When using multiple formats, the order matters. Next.js will use the first format in the array that the browser supports. +> - 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. #### `minimumCacheTTL` diff --git a/docs/02-pages/04-api-reference/01-components/image-legacy.mdx b/docs/02-pages/04-api-reference/01-components/image-legacy.mdx index 26e8f50719e57..c1b754af5216d 100644 --- a/docs/02-pages/04-api-reference/01-components/image-legacy.mdx +++ b/docs/02-pages/04-api-reference/01-components/image-legacy.mdx @@ -542,7 +542,7 @@ module.exports = { > > - 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, the order matters. Next.js will use the first format in the array that the browser supports. +> - 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 From a8790e2ce102419c1d0d4e0f7c7bbf6bba9d1f26 Mon Sep 17 00:00:00 2001 From: KaziMahbuburRahman Date: Thu, 20 Nov 2025 11:06:37 +0600 Subject: [PATCH 3/3] Remove AVIF and WebP formats from image configuration in next.config.js --- examples/image-component/next.config.js | 1 - 1 file changed, 1 deletion(-) diff --git a/examples/image-component/next.config.js b/examples/image-component/next.config.js index 5b1853fe7bf7e..450c646e2520c 100644 --- a/examples/image-component/next.config.js +++ b/examples/image-component/next.config.js @@ -1,7 +1,6 @@ /** @type {import('next').NextConfig} */ module.exports = { images: { - formats: ['image/avif', 'image/webp'], remotePatterns: [ { protocol: "https",