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

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

@@ -666,5 +666,6 @@
   "665": "Failed to find Server Action \"%s\". This request might be from an older or newer deployment.\\nRead more: https://nextjs.org/docs/messages/failed-to-find-server-action",
   "666": "Turbopack builds are only available in canary builds of Next.js.",
   "667": "receiveExpiredTags is deprecated, and not expected to be called.",
-  "668": "Internal Next.js error: Router action dispatched before initialization."
+  "668": "Internal Next.js error: Router action dispatched before initialization.",
+  "669": "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,30 @@ function assignDefaults(
         )
       }
 
+      // Convert URL to RemotePattern
+      images.remotePatterns = images.remotePatterns.map(
+        ({ protocol, hostname, port, pathname, search }) => {
+          if (
+            protocol &&
+            !['http', 'https', 'http:', 'https:'].includes(protocol)
+          ) {
+            throw new Error(
+              `Specified images.remotePatterns must have protocol "http" or "https" received "${protocol}".`
+            )
+          }
+          return {
+            protocol: protocol?.replace(/:$/, '') 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

@@ -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')
     }
   )
 })