Remote Images

Remote Images

Remote Images, Loaders, and Image Configuration

The optimizer will fetch any URL you hand it, which makes it a server-side request forgery engine unless you constrain it. Next.js 10,514 therefore refuses a remote src until its host appears in remotePatterns, where * matches one path segment or subdomain and ** any number of them. Fields you omit default to **, so spell out protocol, pathname and search.

next.config.ts — locking down and tuning the optimizerTSX

images: {
  remotePatterns: [
    { protocol: "https", hostname: "images.example.com", pathname: "/photos/**", search: "" },
  ],
  formats: ["image/avif", "image/webp"],
  qualities: [50, 75],
  minimumCacheTTL: 2678400,
}

Those knobs are enforced per request, and an out-of-range value is rejected rather than clamped, so a hand-edited URL cannot make the server encode an expensive variant:

Output of 75

$ curl -s "$APP/_next/image?url=%2Fhero.jpg&w=640&q=90" -w " [%{http_code}]"
"q" parameter (quality) of 90 is not allowed [400]
Vary: Accept
Cache-Control: public, max-age=2678400, must-revalidate

minimumCacheTTL defaults to four hours in Next.js 16 and is the max age of the optimized copy; the effective value is the larger of it and the upstream Cache-Control. There is no invalidation API, so a long TTL means changing the src when the picture changes. Optimized files land in <distDir>/cache/images under an LRU capped by maximumDiskCacheSize, half the free disk by default. maximumResponseBody is 50 MB and dangerouslyAllowLocalIP is off, so a private-network host returns 400 until you opt in.

When a CDN already resizes images, running them through /_next/image is wasted work. A loader — per component, or globally through loaderFile — replaces the URL construction with a function of your own returning ` https://cdn.example.com/${src}?w=${width}&q=${quality || 75} , and Next.js keeps building the srcset around it. On a static export, images: { unoptimized: true } degrades next/image to a plain <img> that still enforces alt` and reserves the aspect ratio — the minimum worth keeping, since that layout guarantee costs nothing.

MENU