feat(next/image): add images.localPatterns config (#70529)

This adds support for `images.localPatterns` config to allow specific
local images to be optimized and (more importantly) block anything that
doesn't match a pattern.

Author: styfle

docs/02-app/01-building-your-application/06-optimizing/01-images.mdx

@@ -89,6 +89,21 @@ export default function Page() {
 
 > **Warning:** Dynamic `await import()` or `require()` are _not_ supported. The `import` must be static so it can be analyzed at build time.
 
+You can optionally configure `localPatterns` in your `next.config.js` file in order to allow specific images and block all others.
+
+```js filename="next.config.js"
+module.exports = {
+  images: {
+    localPatterns: [
+      {
+        pathname: '/assets/images/**',
+        search: '',
+      },
+    ],
+  },
+}
+```
+
 ### Remote Images
 
 To use a remote image, the `src` property should be a URL string.

docs/02-app/02-api-reference/01-components/image.mdx

@@ -400,6 +400,25 @@ Other properties on the `<Image />` component will be passed to the underlying
 
 In addition to props, you can configure the Image Component in `next.config.js`. The following options are available:
 
+## `localPatterns`
+
+You can optionally configure `localPatterns` in your `next.config.js` file in order to allow specific paths to be optimized and block all others paths.
+
+```js filename="next.config.js"
+module.exports = {
+  images: {
+    localPatterns: [
+      {
+        pathname: '/assets/images/**',
+        search: '',
+      },
+    ],
+  },
+}
+```
+
+> **Good to know**: The example above will ensure the `src` property of `next/image` must start with `/assets/images/` and must not have a query string. Attempting to optimize any other path will respond with 400 Bad Request.
+
 ### `remotePatterns`
 
 To protect your application from malicious users, configuration is required in order to use external images. This ensures that only external images from your account can be served from the Next.js Image Optimization API. These external images can be configured with the `remotePatterns` property in your `next.config.js` file, as shown below:

errors/invalid-images-config.mdx

@@ -37,6 +37,8 @@ module.exports = {
     contentSecurityPolicy: "default-src 'self'; script-src 'none'; sandbox;",
     // sets the Content-Disposition header (inline or attachment)
     contentDispositionType: 'inline',
+    // limit of 25 objects
+    localPatterns: [],
     // limit of 50 objects
     remotePatterns: [],
     // when true, every image will be unoptimized

errors/next-image-unconfigured-localpatterns.mdx

@@ -0,0 +1,29 @@
+---
+title: '`next/image` Un-configured localPatterns'
+---
+
+## Why This Error Occurred
+
+One of your pages that leverages the `next/image` component, passed a `src` value that uses a URL that isn't defined in the `images.localPatterns` property in `next.config.js`.
+
+## Possible Ways to Fix It
+
+Add an entry to `images.localPatterns` array in `next.config.js` with the expected URL pattern. For example:
+
+```js filename="next.config.js"
+module.exports = {
+  images: {
+    localPatterns: [
+      {
+        pathname: '/assets/**',
+        search: '',
+      },
+    ],
+  },
+}
+```
+
+## Useful Links
+
+- [Image Optimization Documentation](/docs/pages/building-your-application/optimizing/images)
+- [Local Patterns Documentation](/docs/pages/api-reference/components/image#localpatterns)

packages/next/src/build/index.ts

@@ -444,6 +444,11 @@ async function writeImagesManifest(
     port: p.port,
     pathname: makeRe(p.pathname ?? '**').source,
   }))
+  images.localPatterns = (config?.images?.localPatterns || []).map((p) => ({
+    // Modifying the manifest should also modify matchLocalPattern()
+    pathname: makeRe(p.pathname ?? '**', { dot: true }).source,
+    search: p.search,
+  }))
 
   await writeManifest(path.join(distDir, IMAGES_MANIFEST), {
     version: 1,
@@ -1653,18 +1658,18 @@ export default async function build(
           config.experimental.gzipSize
         )
 
-        const middlewareManifest: MiddlewareManifest = require(path.join(
-          distDir,
-          SERVER_DIRECTORY,
-          MIDDLEWARE_MANIFEST
-        ))
+        const middlewareManifest: MiddlewareManifest = require(
+          path.join(distDir, SERVER_DIRECTORY, MIDDLEWARE_MANIFEST)
+        )
 
         const actionManifest = appDir
-          ? (require(path.join(
-              distDir,
-              SERVER_DIRECTORY,
-              SERVER_REFERENCE_MANIFEST + '.json'
-            )) as ActionManifest)
+          ? (require(
+              path.join(
+                distDir,
+                SERVER_DIRECTORY,
+                SERVER_REFERENCE_MANIFEST + '.json'
+              )
+            ) as ActionManifest)
           : null
         const entriesWithAction = actionManifest ? new Set() : null
         if (actionManifest && entriesWithAction) {
@@ -3023,8 +3028,8 @@ export default async function build(
             fallback: ssgBlockingFallbackPages.has(tbdRoute)
               ? null
               : ssgStaticFallbackPages.has(tbdRoute)
-              ? `${normalizedRoute}.html`
-              : false,
+                ? `${normalizedRoute}.html`
+                : false,
             dataRouteRegex: normalizeRouteRegex(
               getNamedRouteRegex(
                 dataRoute.replace(/\.json$/, ''),

packages/next/src/build/webpack/plugins/define-env-plugin.ts

@@ -175,6 +175,7 @@ export function getDefineEnv({
             // pass domains in development to allow validating on the client
             domains: config.images.domains,
             remotePatterns: config.images?.remotePatterns,
+            localPatterns: config.images?.localPatterns,
             output: config.output,
           }
         : {}),

packages/next/src/client/legacy/image.tsx

@@ -139,6 +139,25 @@ function defaultLoader({
       )
     }
 
+    if (src.startsWith('/') && config.localPatterns) {
+      if (
+        process.env.NODE_ENV !== 'test' &&
+        // micromatch isn't compatible with edge runtime
+        process.env.NEXT_RUNTIME !== 'edge'
+      ) {
+        // We use dynamic require because this should only error in development
+        const {
+          hasLocalMatch,
+        } = require('../../shared/lib/match-local-pattern')
+        if (!hasLocalMatch(config.localPatterns, src)) {
+          throw new Error(
+            `Invalid src prop (${src}) on \`next/image\` does not match \`images.localPatterns\` configured in your \`next.config.js\`\n` +
+              `See more info: https://nextjs.org/docs/messages/next-image-unconfigured-localpatterns`
+          )
+        }
+      }
+    }
+
     if (!src.startsWith('/') && (config.domains || config.remotePatterns)) {
       let parsedSrc: URL
       try {
@@ -156,8 +175,10 @@ function defaultLoader({
         process.env.NEXT_RUNTIME !== 'edge'
       ) {
         // We use dynamic require because this should only error in development
-        const { hasMatch } = require('../../shared/lib/match-remote-pattern')
-        if (!hasMatch(config.domains, config.remotePatterns, parsedSrc)) {
+        const {
+          hasRemoteMatch,
+        } = require('../../shared/lib/match-remote-pattern')
+        if (!hasRemoteMatch(config.domains, config.remotePatterns, parsedSrc)) {
           throw new Error(
             `Invalid src prop (${src}) on \`next/image\`, hostname "${parsedSrc.hostname}" is not configured under images in your \`next.config.js\`\n` +
               `See more info: https://nextjs.org/docs/messages/next-image-unconfigured-host`

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

@@ -425,6 +425,15 @@ export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>
       .optional(),
     images: z
       .strictObject({
+        localPatterns: z
+          .array(
+            z.strictObject({
+              pathname: z.string().optional(),
+              search: z.string().optional(),
+            })
+          )
+          .max(25)
+          .optional(),
         remotePatterns: z
           .array(
             z.strictObject({

packages/next/src/server/config.ts

@@ -368,6 +368,19 @@ function assignDefaults(
       )
     }
 
+    if (images.localPatterns) {
+      if (!Array.isArray(images.localPatterns)) {
+        throw new Error(
+          `Specified images.localPatterns should be an Array received ${typeof images.localPatterns}.\nSee more info here: https://nextjs.org/docs/messages/invalid-images-config`
+        )
+      }
+      // static import images are automatically allowed
+      images.localPatterns.push({
+        pathname: '/_next/static/media/**',
+        search: '',
+      })
+    }
+
     if (images.remotePatterns) {
       if (!Array.isArray(images.remotePatterns)) {
         throw new Error(

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

@@ -12,7 +12,8 @@ import nodeUrl, { type UrlWithParsedQuery } from 'url'
 
 import { getImageBlurSvg } from '../shared/lib/image-blur-svg'
 import type { ImageConfigComplete } from '../shared/lib/image-config'
-import { hasMatch } from '../shared/lib/match-remote-pattern'
+import { hasLocalMatch } from '../shared/lib/match-local-pattern'
+import { hasRemoteMatch } from '../shared/lib/match-remote-pattern'
 import type { NextConfigComplete } from './config-shared'
 import { createRequestResponseMocks } from './lib/mock-request'
 // Do not import anything other than types from this module
@@ -172,6 +173,7 @@ export class ImageOptimizerCache {
       formats = ['image/webp'],
     } = imageData
     const remotePatterns = nextConfig.images?.remotePatterns || []
+    const localPatterns = nextConfig.images?.localPatterns
     const { url, w, q } = query
     let href: string
 
@@ -192,6 +194,9 @@ export class ImageOptimizerCache {
     if (url.startsWith('/')) {
       href = url
       isAbsolute = false
+      if (!hasLocalMatch(localPatterns, url)) {
+        return { errorMessage: '"url" parameter is not allowed' }
+      }
     } else {
       let hrefParsed: URL
 
@@ -207,7 +212,7 @@ export class ImageOptimizerCache {
         return { errorMessage: '"url" parameter is invalid' }
       }
 
-      if (!hasMatch(domains, remotePatterns, hrefParsed)) {
+      if (!hasRemoteMatch(domains, remotePatterns, hrefParsed)) {
         return { errorMessage: '"url" parameter is not allowed' }
       }
     }