Add errors for invalid placeholder=blur usage (#25953)

There are strict conditions for using `placeholder=blur` documented in #25949 but this will give the user a better understanding during `next dev` and links to the error.

- Error when `placeholder=blur` and no `blurDataURL`
- The Error for small images with `placeholder=blur` has been changed to a warning
- Added support for blurring a webp image
- Added error page linking to relevant docs

Author: styfle

errors/placeholder-blur-data-url.md

@@ -0,0 +1,15 @@
+# `placeholder=blur` without `blurDataURL`
+
+#### Why This Error Occurred
+
+You are attempting use the `next/image` component with `placeholder=blur` property but no `blurDataURL` property.
+
+The `blurDataURL` might be missing because your using a string for `src` instead of a static import.
+
+Or `blurDataURL` might be missing because the static import is an unsupported image format. Only jpg, png, and webp are supported at this time.
+
+#### Possible Ways to Fix It
+
+- Add a [`blurDataURL`](https://nextjs.org/docs/api-reference/next/image#blurdataurl) property, the contents should be a small Data URL to represent the image
+- Change the [`src`](https://nextjs.org/docs/api-reference/next/image#src) property to a static import with one of the supported file types: jpg, png, or webp
+- Remove the [`placeholder`](https://nextjs.org/docs/api-reference/next/image#placeholder) property, effectively no blur effect

packages/next/build/webpack/loaders/next-image-loader.js

@@ -2,7 +2,9 @@ import loaderUtils from 'next/dist/compiled/loader-utils'
 import sizeOf from 'image-size'
 import { processBuffer } from '../../../next-server/server/lib/squoosh/main'
 
-const PLACEHOLDER_SIZE = 8
+const BLUR_IMG_SIZE = 8
+const BLUR_QUALITY = 70
+const VALID_BLUR_EXT = ['jpeg', 'png', 'webp']
 
 async function nextImageLoader(content) {
   const context = this.rootContext
@@ -19,20 +21,20 @@ async function nextImageLoader(content) {
   }
 
   const imageSize = sizeOf(content)
-  let placeholder
-  if (extension === 'jpeg' || extension === 'png') {
-    // Shrink the image's largest dimension to 6 pixels
+  let blurDataURL
+  if (VALID_BLUR_EXT.includes(extension)) {
+    // Shrink the image's largest dimension
     const resizeOperationOpts =
       imageSize.width >= imageSize.height
-        ? { type: 'resize', width: PLACEHOLDER_SIZE }
-        : { type: 'resize', height: PLACEHOLDER_SIZE }
+        ? { type: 'resize', width: BLUR_IMG_SIZE }
+        : { type: 'resize', height: BLUR_IMG_SIZE }
     const resizedImage = await processBuffer(
       content,
       [resizeOperationOpts],
       extension,
-      70
+      BLUR_QUALITY
     )
-    placeholder = `data:image/${extension};base64,${resizedImage.toString(
+    blurDataURL = `data:image/${extension};base64,${resizedImage.toString(
       'base64'
     )}`
   }
@@ -41,7 +43,7 @@ async function nextImageLoader(content) {
     src: '/_next' + interpolatedName,
     height: imageSize.height,
     width: imageSize.width,
-    placeholder,
+    blurDataURL,
   })
 
   this.emitFile(interpolatedName, content, null)

packages/next/client/image.tsx

@@ -53,7 +53,7 @@ interface StaticImageData {
   src: string
   height: number
   width: number
-  placeholder?: string
+  blurDataURL?: string
 }
 
 interface StaticRequire {
@@ -329,9 +329,7 @@ export default function Image({
         )}`
       )
     }
-    if (staticImageData.placeholder) {
-      blurDataURL = staticImageData.placeholder
-    }
+    blurDataURL = blurDataURL || staticImageData.blurDataURL
     staticSrc = staticImageData.src
     if (!layout || layout !== 'fill') {
       height = height || staticImageData.height
@@ -347,6 +345,10 @@ export default function Image({
   }
   src = typeof src === 'string' ? src : staticSrc
 
+  const widthInt = getInt(width)
+  const heightInt = getInt(height)
+  const qualityInt = getInt(quality)
+
   if (process.env.NODE_ENV !== 'production') {
     if (!src) {
       throw new Error(
@@ -374,6 +376,27 @@ export default function Image({
         `Image with src "${src}" has both "priority" and "loading='lazy'" properties. Only one should be used.`
       )
     }
+    if (placeholder === 'blur') {
+      if ((widthInt || 0) * (heightInt || 0) < 1600) {
+        console.warn(
+          `Image with src "${src}" is smaller than 40x40. Consider removing the "placeholder='blur'" property to improve performance.`
+        )
+      }
+      if (!blurDataURL) {
+        const VALID_BLUR_EXT = ['jpeg', 'png', 'webp'] // should match next-image-loader
+
+        throw new Error(
+          `Image with src "${src}" has "placeholder='blur'" property but is missing the "blurDataURL" property.
+          Possible solutions:
+            - Add a "blurDataURL" property, the contents should be a small Data URL to represent the image
+            - Change the "src" property to a static import with one of the supported file types: ${VALID_BLUR_EXT.join(
+              ','
+            )}
+            - Remove the "placeholder" property, effectively no blur effect
+          Read more: https://nextjs.org/docs/messages/placeholder-blur-data-url`
+        )
+      }
+    }
   }
   let isLazy =
     !priority && (loading === 'lazy' || typeof loading === 'undefined')
@@ -389,14 +412,6 @@ export default function Image({
   })
   const isVisible = !isLazy || isIntersected
 
-  const widthInt = getInt(width)
-  const heightInt = getInt(height)
-  const qualityInt = getInt(quality)
-
-  // Show blur if larger than 5000px such as 100 x 50
-  const showBlurPlaceholder =
-    placeholder === 'blur' && (widthInt || 0) * (heightInt || 0) > 5000
-
   let wrapperStyle: JSX.IntrinsicElements['div']['style'] | undefined
   let sizerStyle: JSX.IntrinsicElements['div']['style'] | undefined
   let sizerSvg: string | undefined
@@ -423,7 +438,7 @@ export default function Image({
     objectFit,
     objectPosition,
 
-    ...(showBlurPlaceholder
+    ...(placeholder === 'blur'
       ? {
           filter: 'blur(20px)',
           backgroundSize: 'cover',

test/integration/image-component/default/pages/blurry-placeholder.js

@@ -8,7 +8,7 @@ export default function Page() {
       <Image
         priority
         id="blurry-placeholder"
-        src="/test.jpg"
+        src="/test.ico"
         width="400"
         height="400"
         placeholder="blur"
@@ -19,7 +19,7 @@ export default function Page() {
 
       <Image
         id="blurry-placeholder-with-lazy"
-        src="/test.jpg"
+        src="/test.bmp"
         width="400"
         height="400"
         placeholder="blur"

test/integration/image-component/default/pages/invalid-placeholder-blur-static.js

@@ -0,0 +1,17 @@
+import React from 'react'
+import Image from 'next/image'
+import testBMP from '../public/test.bmp'
+
+const Page = () => {
+  return (
+    <div>
+      <Image
+        id="invalid-placeholder-blur-static"
+        src={testBMP}
+        placeholder="blur"
+      />
+    </div>
+  )
+}
+
+export default Page

test/integration/image-component/default/pages/invalid-placeholder-blur.js

@@ -0,0 +1,12 @@
+import React from 'react'
+import Image from 'next/image'
+
+const Page = () => {
+  return (
+    <div>
+      <Image id="invalid-placeholder-blur" src="/test.png" placeholder="blur" />
+    </div>
+  )
+}
+
+export default Page

test/integration/image-component/default/pages/small-img-import.js

@@ -0,0 +1,13 @@
+import React from 'react'
+import Image from 'next/image'
+import Small from '../public/small.jpg'
+
+const Page = () => {
+  return (
+    <div>
+      <Image id="small-img-import" src={Small} placeholder="blur" />
+    </div>
+  )
+}
+
+export default Page

test/integration/image-component/default/pages/static.js

@@ -4,23 +4,13 @@ import Image from 'next/image'
 
 import testJPG from '../public/test.jpg'
 import testPNG from '../public/test.png'
+import testWEBP from '../public/test.webp'
 import testSVG from '../public/test.svg'
 import testGIF from '../public/test.gif'
 import testBMP from '../public/test.bmp'
 import testICO from '../public/test.ico'
-import testWEBP from '../public/test.webp'
 
 import TallImage from '../components/TallImage'
-const testFiles = [
-  testJPG,
-  testPNG,
-  testSVG,
-  testGIF,
-  testBMP,
-  testICO,
-  testWEBP,
-]
-
 const Page = () => {
   return (
     <div>
@@ -46,9 +36,14 @@ const Page = () => {
         width="400"
         height="300"
       />
-      {testFiles.map((f, i) => (
-        <Image id={`format-test-${i}`} key={i} src={f} placeholder="blur" />
-      ))}
+      <br />
+      <Image id="blur-png" src={testPNG} placeholder="blur" />
+      <Image id="blur-jpg" src={testJPG} placeholder="blur" />
+      <Image id="blur-webp" src={testWEBP} placeholder="blur" />
+      <Image id="static-svg" src={testSVG} />
+      <Image id="static-gif" src={testGIF} />
+      <Image id="static-bmp" src={testBMP} />
+      <Image id="static-ico" src={testICO} />
     </div>
   )
 }

test/integration/image-component/default/public/small.jpg

@@ -484,6 +484,39 @@ function runTests(mode) {
         'Failed to parse src "//assets.example.com/img.jpg" on `next/image`, protocol-relative URL (//) must be changed to an absolute URL (http:// or https://)'
       )
     })
+
+    it('should show error when string src and placeholder=blur and blurDataURL is missing', async () => {
+      const browser = await webdriver(appPort, '/invalid-placeholder-blur')
+
+      expect(await hasRedbox(browser)).toBe(true)
+      expect(await getRedboxHeader(browser)).toContain(
+        `Image with src "/test.png" has "placeholder='blur'" property but is missing the "blurDataURL" property.`
+      )
+    })
+
+    it('should show error when static import and placeholder=blur and blurDataUrl is missing', async () => {
+      const browser = await webdriver(
+        appPort,
+        '/invalid-placeholder-blur-static'
+      )
+
+      expect(await hasRedbox(browser)).toBe(true)
+      expect(await getRedboxHeader(browser)).toMatch(
+        /Image with src "(.*)bmp" has "placeholder='blur'" property but is missing the "blurDataURL" property/
+      )
+    })
+
+    it('should warn when using a very small image with placeholder=blur', async () => {
+      const browser = await webdriver(appPort, '/small-img-import')
+
+      const warnings = (await browser.log('browser'))
+        .map((log) => log.message)
+        .join('\n')
+      expect(await hasRedbox(browser)).toBe(false)
+      expect(warnings).toMatch(
+        /Image with src (.*)jpg(.*) is smaller than 40x40. Consider removing(.*)/gm
+      )
+    })
   }
 
   it('should correctly ignore prose styles', async () => {