Image CDN configuration

What an image CDN does

An image CDN (also called a cut-image service) is a content delivery network that adds image transformation and delivery, normally in front of your origin image store (your server, S3, R2). Instead of serving a fixed file, the edge resizes, crops, converts to WebP/AVIF and strips metadata on the fly, computes a cache key from the requested transform, and serves repeat requests from the edge cache.

This is the difference that matters for the image optimisation workflow: the source set of originals is small, and every variant a page needs is derived on demand from the same original, so you stop maintaining 12 manually-cropped copies per photo.

The transform URL

Image CDNs use a URL pattern to declare the transformation:

https://img.example.com/{preset}/{path}
https://img.example.com/cdn-cgi/image/width=800,format=auto/{path}

Each provider has its own parameter grammar (?width=, &format=webp, &quality=, &fit=, &crop=) and a preset/variant system. The two useful patterns for a website:

1. A one-url-per-size service that quietly converts format (format=auto picks WebP/AVIF for browsers that support them).
2. A variant preset (thumbnail, hero, og) defined once in the CDN panel, so the template only ever emits hero.webp.

Use the ones that map to how your srcset sizes are authored: a width parameter that matches the w descriptors in your srcset means the browser's pick algorithm keeps choosing the right size.

Caching and the immutable rule

Transform variants are cached responses, and the cache rules for images follow the http caching guide exactly:

• A preset/URL that never changes (an exact ?width=) can be cached public, max-age=31536000, immutable, because the URL describes the (final) result.
• A same URL that changes (a re-upload overwriting the original path with a new photo) kills the immutable guarantee; either use a content-hashed path (/2026/photo-q7x9.jpg changes when the photo changes) or accept a short max-age with a purge.

The cache-busting rule for images is therefore the same as for CSS/JS: never reuse a URL that means two different files over time if you need the cache to be correct.

The purge workflow

When an original changes and you regenerated with the same URL:

1. Purge the specific variant URLs (one per width/format used).
2. Or bump the content-hash in the path and redeploy (image-optimisation-guide shows the versioned-filename pattern).
3. Verify the edge shows the new render, not the stale cached one (request from a different region or with a cache-busting query).

Most CDNs expose purge-by-URL and purge-by-prefix, and a Webhook/API to automate it (the purge cloudflare cache article shows the Cloudflare shape, which generalizes to other vendors).

When an image CDN is and is not the answer

• Yes: a media-heavy site (ecommerce, galleries, blogs) that would otherwise maintain dozens of crops; responsive images need 3-6 sizes per photo and the CDN produces them for free.
• No: a small static brochure site with a handful of hand-optimized files already; adding a CDN transform layer for 20 images adds a dependency without a win. The compress images guide covers the pure-storage alternative.

Config checklist

• Pick one transformation model (preset or params) and use it across every image component.
• Set quality (say 75 for photo, 80-90 for logos) and format conversion (WebP/AVIF).
• Confirm the CDN keeps widths and content-hash align, and that originals are not exposed (the CDN's origin should be private if possible).
• Purge-test one image end to end before rolling it across a template.

The CDN static assets guide has the general CDN caching behavior, and the web image formats guide explains the format choices the config expresses.