feat(next/image): support new URL() for images.remotePatterns (#77692)

Configuring `remotePatterns` can be a hassle because you have to define
each of the parts. And if you forget a part, its a wildcard meaning it
will match anything. This is usually not desirable since most remote
images don't allow query strings.

This PR adds support for using an array of `URL` objects when defining
`images.remotePatterns`.

```js
module.exports = {
  images: {
    remotePatterns: [
      new URL('https://res.cloudinary.com/my-account/**'),
      new URL('https://s3.my-account.*.amazonaws.com/**'),
    ],
  },
}
```

Note that wildcards must be explicit and anything missing is assumed to
no longer match.

Author: styfle

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

@@ -520,6 +520,16 @@ module.exports = {
 
 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:
 
+```js filename="next.config.js"
+module.exports = {
+  images: {
+    remotePatterns: [new URL('https://example.com/account123/**')],
+  },
+}
+```
+
+Versions of Next.js prior to 15.3.0 can configure `remotePatterns` using the object:
+
 ```js filename="next.config.js"
 module.exports = {
   images: {
@@ -1106,6 +1116,7 @@ This `next/image` component uses browser native [lazy loading](https://caniuse.c
 
 | Version    | Changes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `v15.3.0`  | `remotePatterns` added support for array of `URL` objects.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `v15.0.0`  | `contentDispositionType` configuration default changed to `attachment`.                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `v14.2.23` | `qualities` configuration added.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `v14.2.15` | `decoding` prop added and `localPatterns` configuration added.                                                                                                                                                                                                                                                                                                                                                                                                                                                |

errors/next-image-unconfigured-host.mdx

@@ -10,6 +10,21 @@ One of your pages that leverages the `next/image` component, passed a `src` valu
 
 Add the protocol, hostname, port, and pathname to the `images.remotePatterns` config in `next.config.js`:
 
+```js filename="next.config.js"
+module.exports = {
+  images: {
+    remotePatterns: [new URL('https://assets.example.com/account123/**')],
+  },
+}
+```
+
+### Fixing older versions of Next.js
+
+<details>
+  <summary>Using Next.js prior to 15.3.0?</summary>
+  
+Older versions of Next.js can configure `images.remotePatterns` using the object:
+
 ```js filename="next.config.js"
 module.exports = {
   images: {
@@ -26,7 +41,7 @@ module.exports = {
 }
 ```
 
-### Fixing older versions of Next.js
+</details>
 
 <details>
   <summary>Using Next.js prior to 12.3.0?</summary>

packages/next/errors.json

@@ -668,5 +668,6 @@
   "667": "receiveExpiredTags is deprecated, and not expected to be called.",
   "668": "Internal Next.js error: Router action dispatched before initialization.",
   "669": "Invariant: --turbopack is set but the build used Webpack",
-  "670": "Invariant: --turbopack is not set but the build used Turbopack. Add --turbopack to \"next start\"."
+  "670": "Invariant: --turbopack is not set but the build used Turbopack. Add --turbopack to \"next start\".",
+  "671": "Specified images.remotePatterns must have protocol \"http\" or \"https\" received \"%s\"."
 }

packages/next/src/build/index.ts

@@ -582,7 +582,7 @@ async function writeImagesManifest(
   // By default, remotePatterns will allow no remote images ([])
   images.remotePatterns = (config?.images?.remotePatterns || []).map((p) => ({
     // Modifying the manifest should also modify matchRemotePattern()
-    protocol: p.protocol,
+    protocol: p.protocol?.replace(/:$/, '') as 'http' | 'https' | undefined,
     hostname: makeRe(p.hostname).source,
     port: p.port,
     pathname: makeRe(p.pathname ?? '**', { dot: true }).source,

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

@@ -525,13 +525,16 @@ export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>
           .optional(),
         remotePatterns: z
           .array(
-            z.strictObject({
-              hostname: z.string(),
-              pathname: z.string().optional(),
-              port: z.string().max(5).optional(),
-              protocol: z.enum(['http', 'https']).optional(),
-              search: z.string().optional(),
-            })
+            z.union([
+              z.instanceof(URL),
+              z.strictObject({
+                hostname: z.string(),
+                pathname: z.string().optional(),
+                port: z.string().max(5).optional(),
+                protocol: z.enum(['http', 'https']).optional(),
+                search: z.string().optional(),
+              }),
+            ])
           )
           .max(50)
           .optional(),

packages/next/src/server/config.ts

@@ -364,6 +364,27 @@ function assignDefaults(
         )
       }
 
+      // We must convert URL to RemotePattern since URL has a colon in the protocol
+      // and also has additional properties we want to filter out. Also, new URL()
+      // accepts any protocol so we need manual validation here.
+      images.remotePatterns = images.remotePatterns.map(
+        ({ protocol, hostname, port, pathname, search }) => {
+          const proto = protocol?.replace(/:$/, '')
+          if (!['http', 'https', undefined].includes(proto)) {
+            throw new Error(
+              `Specified images.remotePatterns must have protocol "http" or "https" received "${proto}".`
+            )
+          }
+          return {
+            protocol: proto as 'http' | 'https' | undefined,
+            hostname,
+            port,
+            pathname,
+            search,
+          }
+        }
+      )
+
       // static images are automatically prefixed with assetPrefix
       // so we need to ensure _next/image allows downloading from
       // this resource

packages/next/src/shared/lib/image-config.ts

@@ -113,7 +113,7 @@ export type ImageConfigComplete = {
   contentDispositionType: 'inline' | 'attachment'
 
   /** @see [Remote Patterns](https://nextjs.org/docs/api-reference/next/image#remotepatterns) */
-  remotePatterns: RemotePattern[]
+  remotePatterns: Array<URL | RemotePattern>
 
   /** @see [Remote Patterns](https://nextjs.org/docs/api-reference/next/image#localPatterns) */
   localPatterns: LocalPattern[] | undefined

packages/next/src/shared/lib/match-remote-pattern.ts

@@ -2,10 +2,12 @@ import type { RemotePattern } from './image-config'
 import { makeRe } from 'next/dist/compiled/picomatch'
 
 // Modifying this function should also modify writeImagesManifest()
-export function matchRemotePattern(pattern: RemotePattern, url: URL): boolean {
+export function matchRemotePattern(
+  pattern: RemotePattern | URL,
+  url: URL
+): boolean {
   if (pattern.protocol !== undefined) {
-    const actualProto = url.protocol.slice(0, -1)
-    if (pattern.protocol !== actualProto) {
+    if (pattern.protocol.replace(/:$/, '') !== url.protocol.replace(/:$/, '')) {
       return false
     }
   }
@@ -41,7 +43,7 @@ export function matchRemotePattern(pattern: RemotePattern, url: URL): boolean {
 
 export function hasRemoteMatch(
   domains: string[],
-  remotePatterns: RemotePattern[],
+  remotePatterns: Array<RemotePattern | URL>,
   url: URL
 ): boolean {
   return (

test/e2e/app-dir/next-image/next.config.js

@@ -0,0 +1,9 @@
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {
+  images: {
+    remotePatterns: [new URL('https://image-optimization-test.vercel.app/**')],
+  },
+}
+
+export default nextConfig

test/e2e/app-dir/next-image/next.config.ts

@@ -567,6 +567,27 @@ describe('Image Optimizer', () => {
       )
     })
 
+    it('should error when images.remotePatterns URL has invalid protocol', async () => {
+      await nextConfig.replace(
+        '{ /* replaceme */ }',
+        `{ images: { remotePatterns: [new URL('file://example.com/**')] } }`
+      )
+      let stderr = ''
+
+      app = await launchApp(appDir, await findPort(), {
+        onStderr(msg) {
+          stderr += msg || ''
+        },
+      })
+      await waitFor(1000)
+      await killApp(app).catch(() => {})
+      await nextConfig.restore()
+
+      expect(stderr).toContain(
+        `Specified images.remotePatterns must have protocol "http" or "https" received "file"`
+      )
+    })
+
     it('should error when images.contentDispositionType is not valid', async () => {
       await nextConfig.replace(
         '{ /* replaceme */ }',

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

@@ -1,5 +1,5 @@
 module.exports = {
   images: {
-    remotePatterns: [{ hostname: 'image-optimization-test.vercel.app' }],
+    remotePatterns: [new URL('https://image-optimization-test.vercel.app/**')],
   },
 }

test/integration/next-image-new/unicode/next.config.js

@@ -2,6 +2,7 @@
 
 import {
   findPort,
+  getImagesManifest,
   killApp,
   launchApp,
   nextBuild,
@@ -17,7 +18,7 @@ let appPort
 let app
 let browser
 
-function runTests() {
+function runTests(mode: 'server' | 'dev') {
   it('should load static unicode image', async () => {
     const src = await browser.elementById('static').getAttribute('src')
     expect(src).toMatch(
@@ -65,6 +66,45 @@ function runTests() {
     const res = await fetch(fullSrc)
     expect(res.status).toBe(200)
   })
+  if (mode === 'server') {
+    it('should build correct images-manifest.json', async () => {
+      const manifest = getImagesManifest(appDir)
+      expect(manifest).toEqual({
+        version: 1,
+        images: {
+          contentDispositionType: 'attachment',
+          contentSecurityPolicy:
+            "script-src 'none'; frame-src 'none'; sandbox;",
+          dangerouslyAllowSVG: false,
+          deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
+          disableStaticImages: false,
+          domains: [],
+          formats: ['image/webp'],
+          imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
+          loader: 'default',
+          loaderFile: '',
+          remotePatterns: [
+            {
+              protocol: 'https',
+              hostname:
+                '^(?:^(?:image\\-optimization\\-test\\.vercel\\.app)$)$',
+              port: '',
+              pathname:
+                '^(?:\\/(?!\\.{1,2}(?:\\/|$))(?:(?:(?!(?:^|\\/)\\.{1,2}(?:\\/|$)).)*?))$',
+              search: '',
+            },
+          ],
+          minimumCacheTTL: 60,
+          path: '/_next/image',
+          sizes: [
+            640, 750, 828, 1080, 1200, 1920, 2048, 3840, 16, 32, 48, 64, 96,
+            128, 256, 384,
+          ],
+          unoptimized: false,
+        },
+      })
+    })
+  }
 }
 
 describe('Image Component Unicode Image URL', () => {
@@ -82,7 +122,7 @@ describe('Image Component Unicode Image URL', () => {
           browser.close()
         }
       })
-      runTests()
+      runTests('dev')
     }
   )
   ;(process.env.TURBOPACK_DEV ? describe.skip : describe)(
@@ -100,7 +140,7 @@ describe('Image Component Unicode Image URL', () => {
           browser.close()
         }
       })
-      runTests()
+      runTests('server')
     }
   )
 })