Rename next/image dangerously-unoptimized to custom and warn when…

… applicable (vercel#26998)

Since we are no longer accepting new built-in loaders, users may wish to use a different cloud provider.

So this PR renames `dangerously-unoptimized` to `custom` to handle this case as well as the intention of `next export`.

If the user doesn't add a `loader` prop, we throw an error.
If the user adds a `loader` prop but it doesn't return the width, we print a warning.

- Follow up to vercel#26847 
- Fixes vercel#21079 
- Fixes vercel#19612 
- Related to vercel#26850

docs/basic-features/image-optimization.md

@@ -121,7 +121,7 @@ The following Image Optimization cloud providers are included:
 - [Imgix](https://www.imgix.com): `loader: 'imgix'`
 - [Cloudinary](https://cloudinary.com): `loader: 'cloudinary'`
 - [Akamai](https://www.akamai.com): `loader: 'akamai'`
-- dangerously-unoptimized: uses image directly from `src` prop without optimization (only needed with `next export` or when the built-in `_next/image` optimizer can not be leveraged) `loader: 'dangerously-unoptimized'`
+- Custom: `loader: 'custom'` use a custom cloud provider by implementing the [`loader`](/docs/api-reference/next/image.md#loader) prop on the `next/image` component
 - Default: Works automatically with `next dev`, `next start`, or a custom server
 
 If you need a different provider, you can use the [`loader`](/docs/api-reference/next/image.md#loader) prop with `next/image`.

errors/manifest.json

@@ -249,6 +249,14 @@
           "title": "next-head-count-missing",
           "path": "/errors/next-head-count-missing.md"
         },
+        {
+          "title": "next-image-missing-loader",
+          "path": "/errors/next-image-missing-loader.md"
+        },
+        {
+          "title": "next-image-missing-loader-width",
+          "path": "/errors/next-image-missing-loader-width.md"
+        },
         {
           "title": "next-image-unconfigured-host",
           "path": "/errors/next-image-unconfigured-host.md"

errors/next-image-missing-loader-width.md

@@ -0,0 +1,17 @@
+# Missing `width` in the URL Returned by the Loader Prop on `next/image`
+
+#### Why This Error Occurred
+
+The [`loader`](https://nextjs.org/docs/api-reference/next/image#loader) prop on the `next/image` component allows you to override the built-in URL resolution with a custom implementation in order to support any 3rd party cloud provider that can perform Image Optimization.
+
+This error occurred because the provided `loader()` function did not use `width` in the returned URL string. This means that the image will likely not be resized and therefore degrade performance.
+
+#### Possible Ways to Fix It
+
+- Ensure your Image Optimization provider can resize images. Then use the `width` parameter from the [`loader()`](https://nextjs.org/docs/api-reference/next/image#loader) function to construct the correct URL string.
+- Add the [`unoptimized`](https://nextjs.org/docs/api-reference/next/image#unoptimized) prop.
+
+### Useful Links
+
+- [Image Optimization Documentation](https://nextjs.org/docs/basic-features/image-optimization)
+- [`next/image` Documentation](https://nextjs.org/docs/api-reference/next/image)

errors/next-image-missing-loader.md

@@ -0,0 +1,15 @@
+# Missing `loader` Prop on `next/image`
+
+#### Why This Error Occurred
+
+When using the `next/image` component with [`loader="custom"`](https://nextjs.org/docs/basic-features/image-optimization#loader) in `next.config.js`, you must provide the [`loader`](https://nextjs.org/docs/api-reference/next/image#loader) prop to the component with your custom implementation.
+
+#### Possible Ways to Fix It
+
+- Add the [`loader`](https://nextjs.org/docs/api-reference/next/image#loader) prop to all usages of the `next/image` component.
+- Change the [`loader`](https://nextjs.org/docs/basic-features/image-optimization#loader) configuration in `next.config.js`.
+
+### Useful Links
+
+- [Image Optimization Documentation](https://nextjs.org/docs/basic-features/image-optimization)
+- [`next/image` Documentation](https://nextjs.org/docs/api-reference/next/image)

packages/next/client/image.tsx

@@ -32,11 +32,11 @@ const loaders = new Map<
   LoaderValue,
   (props: DefaultImageLoaderProps) => string
 >([
+  ['default', defaultLoader],
   ['imgix', imgixLoader],
   ['cloudinary', cloudinaryLoader],
   ['akamai', akamaiLoader],
-  ['default', defaultLoader],
-  ['dangerously-unoptimized', unoptimizedLoader],
+  ['custom', customLoader],
 ])
 
 const VALID_LAYOUT_VALUES = [
@@ -338,6 +338,17 @@ export default function Image({
   const heightInt = getInt(height)
   const qualityInt = getInt(quality)
 
+  let isLazy =
+    !priority && (loading === 'lazy' || typeof loading === 'undefined')
+  if (src.startsWith('data:')) {
+    // https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs
+    unoptimized = true
+    isLazy = false
+  }
+  if (typeof window !== 'undefined' && loadedImageURLs.has(src)) {
+    isLazy = false
+  }
+
   if (process.env.NODE_ENV !== 'production') {
     if (!src) {
       throw new Error(
@@ -404,16 +415,16 @@ export default function Image({
         `Image with src "${src}" is using unsupported "ref" property. Consider using the "onLoadingComplete" property instead.`
       )
     }
-  }
-  let isLazy =
-    !priority && (loading === 'lazy' || typeof loading === 'undefined')
-  if (src && src.startsWith('data:')) {
-    // https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs
-    unoptimized = true
-    isLazy = false
-  }
-  if (src && typeof window !== 'undefined' && loadedImageURLs.has(src)) {
-    isLazy = false
+    const rand = Math.floor(Math.random() * 1000) + 100
+    if (
+      !unoptimized &&
+      !loader({ src, width: rand, quality: 75 }).includes(rand.toString())
+    ) {
+      console.warn(
+        `Image with src "${src}" has a "loader" property that does not implement width. Please implement it or use the "unoptimized" property instead.` +
+          `\nRead more: https://nextjs.org/docs/messages/next-image-missing-loader-width`
+      )
+    }
   }
 
   const [setRef, isIntersected] = useIntersection<HTMLImageElement>({
@@ -626,8 +637,6 @@ export default function Image({
   )
 }
 
-//BUILT IN LOADERS
-
 function normalizeSrc(src: string): string {
   return src[0] === '/' ? src.slice(1) : src
 }
@@ -669,8 +678,11 @@ function cloudinaryLoader({
   return `${root}${paramsString}${normalizeSrc(src)}`
 }
 
-function unoptimizedLoader({ src }: DefaultImageLoaderProps): string {
-  return src
+function customLoader({ src }: DefaultImageLoaderProps): string {
+  throw new Error(
+    `Image with src "${src}" is missing "loader" prop.` +
+      `\nRead more: https://nextjs.org/docs/messages/next-image-missing-loader`
+  )
 }
 
 function defaultLoader({

packages/next/server/image-config.ts

@@ -3,7 +3,7 @@ export const VALID_LOADERS = [
   'imgix',
   'cloudinary',
   'akamai',
-  'dangerously-unoptimized',
+  'custom',
 ] as const
 
 export type LoaderValue = typeof VALID_LOADERS[number]

test/integration/export-image-loader/pages/index.js

@@ -1,8 +1,10 @@
 import Image from 'next/image'
 
+const loader = undefined
+
 export default () => (
   <div>
     <p>Should succeed during export</p>
-    <Image alt="icon" src="/i.png" width="10" height="10" />
+    <Image alt="icon" src="/i.png" width="10" height="10" loader={loader} />
   </div>
 )

test/integration/export-image-loader/test/index.test.js

@@ -9,6 +9,7 @@ jest.setTimeout(1000 * 60 * 5)
 const appDir = join(__dirname, '../')
 const outdir = join(appDir, 'out')
 const nextConfig = new File(join(appDir, 'next.config.js'))
+const pagesIndexJs = new File(join(appDir, 'pages', 'index.js'))
 
 describe('Export with cloudinary loader next/image component', () => {
   beforeAll(async () => {
@@ -44,16 +45,20 @@ describe('Export with cloudinary loader next/image component', () => {
   })
 })
 
-describe('Export with dangerously-unoptimized loader next/image component', () => {
+describe('Export with custom loader next/image component', () => {
   beforeAll(async () => {
     await nextConfig.replace(
       '{ /* replaceme */ }',
       JSON.stringify({
         images: {
-          loader: 'dangerously-unoptimized',
+          loader: 'custom',
         },
       })
     )
+    await pagesIndexJs.replace(
+      'loader = undefined',
+      'loader = ({src}) => "/custom" + src'
+    )
   })
   it('should build successfully', async () => {
     await fs.remove(join(appDir, '.next'))
@@ -69,10 +74,11 @@ describe('Export with dangerously-unoptimized loader next/image component', () =
   it('should contain img element with same src in html output', async () => {
     const html = await fs.readFile(join(outdir, 'index.html'))
     const $ = cheerio.load(html)
-    expect($('img[alt="icon"]').attr('src')).toBe('/i.png')
+    expect($('img[alt="icon"]').attr('src')).toBe('/custom/i.png')
   })
 
   afterAll(async () => {
     await nextConfig.restore()
+    await pagesIndexJs.restore()
   })
 })

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

@@ -9,6 +9,7 @@ import {
   launchApp,
   nextBuild,
   nextStart,
+  renderViaHTTP,
   waitFor,
 } from 'next-test-utils'
 import isAnimated from 'next/dist/compiled/is-animated'
@@ -730,7 +731,34 @@ describe('Image Optimizer', () => {
       await nextConfig.restore()
 
       expect(stderr).toContain(
-        'Specified images.loader should be one of (default, imgix, cloudinary, akamai, dangerously-unoptimized), received invalid value (notreal)'
+        'Specified images.loader should be one of (default, imgix, cloudinary, akamai, custom), received invalid value (notreal)'
+      )
+    })
+
+    it('should error when loader=custom but loader prop is undefined', async () => {
+      await nextConfig.replace(
+        '{ /* replaceme */ }',
+        JSON.stringify({
+          images: {
+            loader: 'custom',
+          },
+        })
+      )
+      let output = ''
+      const appPort = await findPort()
+      app = await launchApp(appDir, appPort, {
+        onStderr(msg) {
+          output += msg || ''
+        },
+        onStdout(msg) {
+          output += msg || ''
+        },
+      })
+      await renderViaHTTP(appPort, '/', {})
+      await killApp(app).catch(() => {})
+      await nextConfig.restore()
+      expect(output).toMatch(
+        /Error: Image with src "(.+)" is missing "loader" prop/
       )
     })
   })