Netlify’s Image CDN is actually a powerful image optimization and transformation service that operates at the edge, meaning it processes your images right where your users are, not on your origin server.
Let’s see it in action. Imagine you have an image at https://your-site.netlify.app/images/hero.jpg. Without any transformations, it’s just there. But with the Image CDN, you can request a transformed version directly in the URL.
For example, to resize it to a width of 800 pixels and convert it to WebP format, you’d use:
https://your-site.netlify.app/images/hero.jpg?nf_resize=fit&w=800&fm=webp
This URL doesn’t just request a transformed image; it causes the transformation to happen on Netlify’s edge servers the first time it’s requested. Subsequent requests for the exact same URL will serve the cached, transformed image, making it incredibly fast.
The core problem this solves is the trade-off between image quality and file size. High-quality images are large, slowing down page loads. Small, compressed images often look terrible. The Image CDN allows you to serve visually identical or near-identical images that are significantly smaller, and it does this automatically based on your requests.
Internally, Netlify’s Image CDN leverages a network of edge servers. When you make a request with transformation parameters, the edge server checks if it has a processed version of that image matching your request. If not, it fetches the original image from your site’s origin (your Netlify deploy), performs the requested transformations (resizing, cropping, format conversion, quality adjustments), caches the result on the edge server, and then serves it to you.
The exact levers you control are the query parameters appended to your image URLs. Here are some of the most common ones:
nf_resize: This is the primary parameter to trigger resizing.fit: Resizes the image to fit within the specified dimensions without distorting the aspect ratio.cover: Resizes the image to cover the specified dimensions, cropping if necessary to maintain aspect ratio.crop: Resizes the image to fill the specified dimensions, cropping aggressively to ensure no empty space.
w: Specifies the desired width in pixels.h: Specifies the desired height in pixels.fm: Specifies the desired output format. Common values includewebp,jpg,png,gif,avif.q: Sets the quality for lossy formats like JPEG and WebP. A value of75is often a good balance.dpr: Device pixel ratio. Use2for high-density displays.
For instance, to create a thumbnail that covers a 200x200 area, optimized for a Retina display, and in WebP format:
https://your-site.netlify.app/images/photo.png?nf_resize=cover&w=200&h=200&dpr=2&fm=webp
This request tells the edge server to take photo.png, resize it so that it at least covers a 200x200 pixel area, ensuring no empty space by cropping if needed, then render it at a device pixel ratio of 2 (effectively making it 400x400 pixels internally for sharp display on high-DPI screens), and finally convert it to WebP for efficient compression.
The system is designed to be intelligent about caching. If you update hero.jpg on your origin, Netlify’s CDN will eventually detect the change and invalidate the cache for all transformed versions of that image, ensuring your users see the latest content. However, it’s important to understand that the transformation itself is on-demand. If a specific URL with transformations has never been requested, it won’t exist on the edge until that first request comes in. This means the very first user to see a newly transformed image might experience a slight delay as the image is processed.
When generating responsive image sets using the <picture> element or srcset attribute, you’ll often want to generate multiple versions of your image for different screen sizes and resolutions. The Image CDN makes this straightforward by allowing you to create URLs with varying w and dpr parameters. For example, you might have URLs like:
images/hero.jpg?w=400
images/hero.jpg?w=800
images/hero.jpg?w=1200
images/hero.jpg?w=800&dpr=2
images/hero.jpg?w=1200&dpr=2
Your HTML would then use these URLs in srcset to let the browser pick the most appropriate image.
The most surprising thing about Netlify’s Image CDN is that it doesn’t require any special Netlify build plugins or configurations to enable the transformation functionality itself. As long as your image is deployed and publicly accessible via your Netlify site’s URL, you can simply start appending the transformation parameters to the image URL, and the edge servers will handle the rest. The optimization is truly on-demand and requires no upfront processing or configuration beyond deploying your assets.
The next concept to explore is how to leverage this for dynamic image generation based on content, such as dynamically overlaying text or applying watermarks.