Rename iconSizes to imageSizes, remove size limitation (#18294)

This does two things:

- Rename `iconSizes` to `imageSizes`.
- Give priority to `imageSizes` regardless of `deviceSizes` as a means to opt-out of the srcset behavior.

docs/basic-features/image-optimization.md

@@ -62,14 +62,14 @@ module.exports = {
 }
 ```
 
-### Icon Sizes
+### Image Sizes
 
-You can specify a list of icon image widths using the `iconSizes` property. These widths should be smaller than the smallest value in `deviceSizes`. The purpose is for images that don't scale with the browser window, such as icons or badges. If `iconSizes` is not defined, then `deviceSizes` will be used.
+You can specify a list of exact image widths using the `imageSizes` property. These widths should be different than the widths defined in `deviceSizes`. The purpose is for images that don't scale with the browser window, such as icons, badges, or profile images. If the `width` property of a [`next/image`](/docs/api-reference/next/image.md) component matches a value in `imageSizes`, the image will be rendered at that exact width.
 
 ```js
 module.exports = {
   images: {
-    iconSizes: [16, 32, 64],
+    imageSizes: [16, 32, 64],
   },
 }
 ```

packages/next/build/index.ts

@@ -1111,8 +1111,8 @@ export default async function build(
   }
 
   const images = { ...config.images }
-  const { deviceSizes, iconSizes } = images
-  images.sizes = [...deviceSizes, ...iconSizes]
+  const { deviceSizes, imageSizes } = images
+  images.sizes = [...deviceSizes, ...imageSizes]
 
   await promises.writeFile(
     path.join(distDir, IMAGES_MANIFEST),

packages/next/build/webpack-config.ts

@@ -992,7 +992,7 @@ export default async function getBaseWebpackConfig(
         ),
         'process.env.__NEXT_IMAGE_OPTS': JSON.stringify({
           deviceSizes: config.images.deviceSizes,
-          iconSizes: config.images.iconSizes,
+          imageSizes: config.images.imageSizes,
           path: config.images.path,
           loader: config.images.loader,
           ...(dev

packages/next/client/image.tsx

@@ -15,7 +15,7 @@ type LoaderKey = 'imgix' | 'cloudinary' | 'akamai' | 'default'
 
 type ImageData = {
   deviceSizes: number[]
-  iconSizes: number[]
+  imageSizes: number[]
   loader: LoaderKey
   path: string
   domains?: string[]
@@ -38,14 +38,14 @@ type ImageProps = Omit<
 const imageData: ImageData = process.env.__NEXT_IMAGE_OPTS as any
 const {
   deviceSizes: configDeviceSizes,
-  iconSizes: configIconSizes,
+  imageSizes: configImageSizes,
   loader: configLoader,
   path: configPath,
   domains: configDomains,
 } = imageData
 // sort smallest to largest
 configDeviceSizes.sort((a, b) => a - b)
-configIconSizes.sort((a, b) => a - b)
+configImageSizes.sort((a, b) => a - b)
 
 let cachedObserver: IntersectionObserver
 const IntersectionObserver =
@@ -87,8 +87,7 @@ function getDeviceSizes(width: number | undefined): number[] {
   if (typeof width !== 'number') {
     return configDeviceSizes
   }
-  const smallest = configDeviceSizes[0]
-  if (width < smallest && configIconSizes.includes(width)) {
+  if (configImageSizes.includes(width)) {
     return [width]
   }
   const widths: number[] = []

packages/next/next-server/server/config.ts

@@ -26,7 +26,7 @@ const defaultConfig: { [key: string]: any } = {
   analyticsId: process.env.VERCEL_ANALYTICS_ID || '',
   images: {
     deviceSizes: [320, 420, 768, 1024, 1200],
-    iconSizes: [],
+    imageSizes: [],
     domains: [],
     path: '/_next/image',
     loader: 'default',
@@ -280,27 +280,27 @@ function assignDefaults(userConfig: { [key: string]: any }) {
         )
       }
     }
-    if (images.iconSizes) {
-      const { iconSizes } = images
-      if (!Array.isArray(iconSizes)) {
+    if (images.imageSizes) {
+      const { imageSizes } = images
+      if (!Array.isArray(imageSizes)) {
         throw new Error(
-          `Specified images.iconSizes should be an Array received ${typeof iconSizes}`
+          `Specified images.imageSizes should be an Array received ${typeof imageSizes}`
         )
       }
 
-      if (iconSizes.length > 25) {
+      if (imageSizes.length > 25) {
         throw new Error(
-          `Specified images.iconSizes exceeds length of 25, received length (${iconSizes.length}), please reduce the length of the array to continue`
+          `Specified images.imageSizes exceeds length of 25, received length (${imageSizes.length}), please reduce the length of the array to continue`
         )
       }
 
-      const invalid = iconSizes.filter((d: unknown) => {
+      const invalid = imageSizes.filter((d: unknown) => {
         return typeof d !== 'number' || d < 1 || d > 10000
       })
 
       if (invalid.length > 0) {
         throw new Error(
-          `Specified images.iconSizes should be an Array of numbers that are between 1 and 10000, received invalid values (${invalid.join(
+          `Specified images.imageSizes should be an Array of numbers that are between 1 and 10000, received invalid values (${invalid.join(
             ', '
           )})`
         )

packages/next/next-server/server/image-optimizer.ts

@@ -25,7 +25,7 @@ const VECTOR_TYPES = [SVG]
 
 type ImageData = {
   deviceSizes: number[]
-  iconSizes: number[]
+  imageSizes: number[]
   loader: string
   path: string
   domains?: string[]
@@ -39,8 +39,8 @@ export async function imageOptimizer(
 ) {
   const { nextConfig, distDir } = server
   const imageData: ImageData = nextConfig.images
-  const { deviceSizes = [], iconSizes = [], domains = [], loader } = imageData
-  const sizes = [...deviceSizes, ...iconSizes]
+  const { deviceSizes = [], imageSizes = [], domains = [], loader } = imageData
+  const sizes = [...deviceSizes, ...imageSizes]
 
   if (loader !== 'default') {
     await server.render404(req, res, parsedUrl)

test/integration/image-component/basic/next.config.js

@@ -1,7 +1,7 @@
 module.exports = {
   images: {
     deviceSizes: [480, 1024, 1600, 2000],
-    iconSizes: [16, 64],
+    imageSizes: [16, 64],
     path: 'https://example.com/myaccount/',
     loader: 'imgix',
   },

test/integration/image-component/basic/test/index.test.js

@@ -51,7 +51,7 @@ function runTests() {
       await browser.elementById('preceding-slash-image').getAttribute('srcset')
     ).toBe('https://example.com/myaccount/fooslash.jpg?auto=format&w=480 480w')
   })
-  it('should use iconSizes when width matches, not deviceSizes from next.config.js', async () => {
+  it('should use imageSizes when width matches, not deviceSizes from next.config.js', async () => {
     expect(await browser.elementById('icon-image-16').getAttribute('src')).toBe(
       'https://example.com/myaccount/icon.png?auto=format&w=16'
     )

test/integration/image-optimizer/test/index.test.js

@@ -398,12 +398,12 @@ describe('Image Optimizer', () => {
       )
     })
 
-    it('should error when iconSizes contains invalid widths', async () => {
+    it('should error when imageSizes contains invalid widths', async () => {
       await nextConfig.replace(
         '{ /* replaceme */ }',
         JSON.stringify({
           images: {
-            iconSizes: [0, 16, 64, 12000],
+            imageSizes: [0, 16, 64, 12000],
           },
         })
       )
@@ -419,7 +419,7 @@ describe('Image Optimizer', () => {
       await nextConfig.restore()
 
       expect(stderr).toContain(
-        'Specified images.iconSizes should be an Array of numbers that are between 1 and 10000, received invalid values (0, 12000)'
+        'Specified images.imageSizes should be an Array of numbers that are between 1 and 10000, received invalid values (0, 12000)'
       )
     })
   })
@@ -447,7 +447,7 @@ describe('Image Optimizer', () => {
       const json = JSON.stringify({
         images: {
           deviceSizes: [largeSize],
-          iconSizes: [size],
+          imageSizes: [size],
           domains,
         },
       })