images (next.config.js loader)

Core Idea

Configure next.config.js images.loader: 'custom' with a loaderFile to route next/image optimization through a third-party image CDN instead of the built-in Image Optimization API.

Key Concepts

• images.loader: 'custom': opts out of the built-in optimizer.
• images.loaderFile: path (relative to project root) to a file exporting a default function ({ src, width, quality }) => string (the resolved image URL).
• Per-instance loader prop: alternative to global config — pass the loader function directly to a next/image instance.
• 'use client' requirement: the loader file needs Client Components to serialize the provided function.

Code Examples

module.exports = {
  images: {
    loader: 'custom',
    loaderFile: './my/image/loader.js',
  },
}

• O que demonstra: apontar pro arquivo de loader customizado.

'use client'

export default function myImageLoader({ src, width, quality }) {
  return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}

• O que demonstra: assinatura mínima de um loader customizado.

// Cloudflare
export default function cloudflareLoader({ src, width, quality }) {
  const params = [`width=${width}`, `quality=${quality || 75}`, 'format=auto']
  return `https://example.com/cdn-cgi/image/${params.join(',')}/${src}`
}

// Supabase
export default function supabaseLoader({ src, width, quality }) {
  const url = new URL(`https://example.com${src}`)
  url.searchParams.set('width', width.toString())
  url.searchParams.set('quality', (quality || 75).toString())
  return url.href
}

• O que demonstra: dois padrões comuns de loader (query params via URLSearchParams vs. path segments), reutilizáveis pra outros provedores de imagem.

Reference Tables

Provedor com exemplo pronto na doc
Akamai, AWS CloudFront, Cloudinary, Cloudflare, Contentful, Fastly, Gumlet, ImageEngine, Imgix, PixelBin, Sanity, Sirv, Supabase, Thumbor, ImageKit.io, Nitrogen AIO

Anti-patterns

• Esquecer 'use client' no arquivo de loader: a função precisa ser serializável para Client Components.
• Assumir que loaderFile aceita caminho absoluto fora do projeto: deve ser relativo à raiz do app Next.js.

Key Takeaways

1. Loader customizado é necessário só se você quer que um CDN de terceiros faça a otimização em vez da API built-in do Next.js.
2. Cada provedor tem uma convenção própria de query params (w/width, q/quality) — copie o exemplo do provedor específico em vez de generalizar.
3. Para overrides pontuais (não globais), use a prop loader direto no componente <Image> em vez de mexer no config.

Connects To

• next/image (Image component): componente que consome este loader; "Image Configuration Options" cobre demais opções (domains, sizes, formats).
• Image Optimization API: comportamento built-in que este config substitui.