Netlify Image CDN and Fallback URL Patterns for Developers

Netlify Image CDN overview

What Netlify Image CDN does and how to use it

Netlify Image CDN is available through the /.netlify/images?url= transformation URL or through framework-specific integrations. You pass a source image URL or a Netlify blob path, along with width, height, format, and quality parameters. Netlify fetches and transforms the image on the first request and caches the result at the edge.

Format conversion works the same way as Vercel's: based on the browser's Accept header, Netlify serves WebP or AVIF when supported. The original image can be any publicly reachable URL or a blob stored in Netlify's object storage.

The transformation URL pattern is: /.netlify/images?url=ORIGINAL_URL&w=WIDTH&h=HEIGHT&fit=cover. The url parameter must be URL-encoded. Width and height control the dimensions. fit controls how the image is cropped.

<!-- Netlify Image CDN transformation URL -->
<img
  src="/.netlify/images?url=%2Fimages%2Fproduct.jpg&w=400&h=300&fit=cover"
  width="400"
  height="300"
  loading="lazy"
  alt="Product image"
/>

<!-- With JavaScript encoding for dynamic URLs -->
<img
  src={`/.netlify/images?url=${encodeURIComponent(imageUrl)}&w=400&h=300&fit=cover`}
  width="400"
  height="300"
  loading="lazy"
  alt="Product image"
  onError={(e) => {
    e.currentTarget.src =
      'https://fallback.pics/api/v1/400x300/7C3AED/FFFFFF?text=Product';
  }}
/>

Missing source handling

What happens when the Netlify CDN source URL returns a 404

When the source image URL passed to Netlify Image CDN returns a 404 or an error, Netlify Image CDN itself returns an error response. The browser renders a broken image. There is no automatic fallback to a placeholder.

This means error handling must happen at the application layer, not the CDN layer. An onerror handler on the img element can catch the broken image and replace the src with a fallback.pics URL. For server-rendered frameworks, you can check image existence at render time and use a placeholder URL from the start.

Astro integration

Astro Image component with fallback.pics on Netlify

Astro's Image component with the @astrojs/netlify adapter automatically routes images through Netlify Image CDN. If the src is a local asset, Astro optimizes it at build time. If the src is a remote URL, the first request at runtime triggers the transformation.

For optional image fields in Astro content collections, use a conditional in the component: if the image field is defined, use the Astro Image component; if it is undefined or null, render a raw img tag with a fallback.pics URL. This keeps Astro's optimization active for real assets.

---
// Astro component: optimized image with fallback
import { Image } from 'astro:assets';

interface Props {
  src?: string;
  alt: string;
  width: number;
  height: number;
}
const { src, alt, width, height } = Astro.props;
const fallbackSrc = `https://fallback.pics/api/v1/${width}x${height}/7C3AED/FFFFFF?text=Image`;
---

{src ? (
  <Image src={src} alt={alt} width={width} height={height} />
) : (
  <img src={fallbackSrc} alt={alt} width={width} height={height} loading="lazy" />
)}

SvelteKit and Nuxt

Using fallback URLs in SvelteKit and Nuxt on Netlify

SvelteKit does not have a built-in image optimization component. When deployed to Netlify, you can construct Netlify Image CDN transformation URLs manually. Pair those with an onerror handler pointing to a fallback.pics URL for missing sources.

Nuxt Image supports Netlify Image CDN as a provider via the @nuxt/image-edge package. Configure the provider in nuxt.config.ts, then use the NuxtImg component. For missing images, pass a fallback URL through the component's error-handling props or use a wrapper pattern similar to the Next.js example above.

<!-- SvelteKit: Netlify Image CDN with fallback placeholder -->
<script lang="ts">
  let src: string = `/.netlify/images?url=${encodeURIComponent(imageSrc)}&w=400&h=300`;
  const fallback = 'https://fallback.pics/api/v1/400x300/7C3AED/FFFFFF?text=Product';
  function onError() { src = fallback; }
</script>

<img {src} {alt} width="400" height="300" on:error={onError} loading="lazy" />

Cache headers

Netlify CDN cache behavior for transformed and fallback images

Netlify Image CDN sets its own Cache-Control headers on transformed images. The default TTL is one year for transformed assets, which is appropriate. You do not need to configure headers for Netlify-transformed images.

For fallback.pics URLs requested directly by the browser (not through Netlify Image CDN), the CDN cache headers from fallback.pics apply. These are served with immutable Cache-Control headers, so browsers and any CDN in front will cache them for up to a year.

# API docs
https://fallback.pics/docs/
https://fallback.pics/placeholder-image-api/

# Related posts
https://fallback.pics/blog/vercel-image-optimization-vs-placeholders/
https://fallback.pics/blog/cache-control-placeholder-images-cdn-browser/