Unverified Commit 779e73eb authored by Joseph's avatar Joseph Committed by GitHub

docs: papercuts in image API reference (#99256)

- The `sizes` section didn't explain what happens to `fill` images
without `sizes`. Only images with a `width` get the limited `1x`/`2x`
`srcset`
   - `fill` images get one built from `deviceSizes`.
- Updated `deviceSizes` to match: it's also used for `fill` images
without `sizes`.

- "Forever" isn't an accurate description of static image import
caching. The built-in image optimizer serves these with `public,
max-age=315360000, immutable`, which is 10 years
([source](https://github.com/vercel/next.js/blob/aea417ab0c490ec3e07112ed48ba20236fdfad18/packages/next/src/server/image-optimizer.ts#L305-L309),
[header](https://github.com/vercel/next.js/blob/aea417ab0c490ec3e07112ed48ba20236fdfad18/packages/next/src/server/image-optimizer.ts#L831)).
- Changed to "long-lived `immutable`" in the image and `legacy` image
references.
parent 2f3842dd
...@@ -225,7 +225,8 @@ If `sizes` is missing, the browser assumes the image will be as wide as the view ...@@ -225,7 +225,8 @@ If `sizes` is missing, the browser assumes the image will be as wide as the view
In addition, `sizes` affects how `srcset` is generated: In addition, `sizes` affects how `srcset` is generated:
- Without `sizes`: Next.js generates a limited `srcset` (e.g. 1x, 2x), suitable for fixed-size images. - Without `sizes`, on an image with a `width`: Next.js generates a limited `srcset` (e.g. 1x, 2x), suitable for fixed-size images.
- Without `sizes`, on a `fill` image: Next.js generates a `srcset` from [`deviceSizes`](#devicesizes) only, as if the image spans the full viewport.
- With `sizes`: Next.js generates a full `srcset` (e.g. 640w, 750w, etc.), optimized for responsive layouts. - With `sizes`: Next.js generates a full `srcset` (e.g. 640w, 750w, etc.), optimized for responsive layouts.
> Learn more about `srcset` and `sizes` on [web.dev](https://web.dev/learn/design/responsive-images/#sizes) and [mdn](https://developer.mozilla.org/docs/Web/HTML/Element/img#sizes). > Learn more about `srcset` and `sizes` on [web.dev](https://web.dev/learn/design/responsive-images/#sizes) and [mdn](https://developer.mozilla.org/docs/Web/HTML/Element/img#sizes).
...@@ -667,7 +668,7 @@ module.exports = { ...@@ -667,7 +668,7 @@ module.exports = {
#### `deviceSizes` #### `deviceSizes`
`deviceSizes` allows you to specify a list of device width breakpoints. These widths are used when the `next/image` component uses [`sizes`](#sizes) prop to ensure the correct image is served for the user's device. `deviceSizes` allows you to specify a list of device width breakpoints. These widths are used when the `next/image` component uses the [`sizes`](#sizes) prop, or the [`fill`](#fill) prop without `sizes`, to ensure the correct image is served for the user's device.
If no configuration is provided, the default below is used: If no configuration is provided, the default below is used:
...@@ -773,7 +774,7 @@ module.exports = { ...@@ -773,7 +774,7 @@ module.exports = {
#### `minimumCacheTTL` #### `minimumCacheTTL`
`minimumCacheTTL` allows you to 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/app/getting-started/images#local-images) which will automatically hash the file contents and cache the image forever with a `Cache-Control` header of `immutable`. `minimumCacheTTL` allows you to 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/app/getting-started/images#local-images) which will automatically hash the file contents and cache the image with a long-lived `immutable` `Cache-Control` header.
If no configuration is provided, the default below is used. If no configuration is provided, the default below is used.
......
...@@ -565,7 +565,7 @@ The expiration (or rather Max Age) is defined by either the [`minimumCacheTTL`]( ...@@ -565,7 +565,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/api-reference/components/image#src) 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 with a long-lived `immutable` `Cache-Control` header.
If no configuration is provided, the default below is used. If no configuration is provided, the default below is used.
......
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