docs: add example for enabling both AVIF and WebP image formats for better image optimization #86191
Conversation
… WebP formats. Added configuration examples and clarified caching behavior for multiple formats.
ijjk
added
Documentation
|
Allow CI Workflow Run
Note: this should only be enabled once the PR is ready to go and can only be enabled by a maintainer |
| ```js filename="next.config.js" | ||
| module.exports = { | ||
| images: { | ||
| formats: ['image/avif', 'image/webp'], |
There was a problem hiding this comment.
Does this introduce more cache overhead though? I don't mean as in, don't do it cuz of the overhead, but as in, we should probably mention this somewhere
There was a problem hiding this comment.
Thanks for the feedback! I've added a note about cache overhead in the "Good to know" section. The documentation now mentions that when using multiple formats, Next.js will cache each format separately, which 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.
This should help developers make an informed decision when choosing between single vs. multiple formats.
| > | ||
| > - 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. |
There was a problem hiding this comment.
Do you think this necessary? we do mention this in 755.
There was a problem hiding this comment.
Good catch! You're right - we already mention that "the array order matters" earlier in the documentation (line 743). I've removed the redundant bullet point about order mattering from the "Good to know" section to avoid duplication.
The earlier explanation at line 743 already covers this: "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."
- 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.
…om/KaziMahbuburRahman/next.js into docs/add-avif-webp-formats-example
…om/KaziMahbuburRahman/next.js into docs/add-avif-webp-formats-example
3 participants
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 theimage-componentexample to demonstrate this configuration.Why?
Currently, the documentation only shows examples for:
formats: ['image/webp']formats: ['image/avif']However, many developers want to enable both formats together to:
This configuration is a best practice but wasn't clearly documented with an example.
How?
formats: ['image/avif', 'image/webp']to App Router image component documentationexamples/image-component/next.config.jsto demonstrate the configurationChanges Made
docs/01-app/03-api-reference/02-components/image.mdx- Added AVIF + WebP exampledocs/02-pages/04-api-reference/01-components/image-legacy.mdx- Added AVIF + WebP exampleexamples/image-component/next.config.js- Added formats configurationTesting
Checklist
pnpm prettier-fixto fix formatting issues (if applicable)