Netlify Image Cdn

What Is This?

Overview

Netlify Image CDN is a built-in image optimization and transformation service available on every Netlify site. It operates through the /.netlify/images endpoint and allows developers to resize, reformat, and optimize images on demand without managing a separate image processing infrastructure. The service handles format conversion, quality adjustments, and dimension changes at the CDN edge, reducing the burden on origin servers and improving delivery speed.

The system works by accepting query parameters appended to the /.netlify/images endpoint. These parameters instruct the CDN how to transform the source image before delivering it to the client. Because transformations happen at the edge, end users receive optimized images with minimal latency, and the results are cached automatically for subsequent requests.

Netlify Image CDN also supports remote image sources through an allowlisting mechanism, enabling teams to proxy and optimize images hosted on external domains. Combined with Netlify Functions and Blobs, it forms a complete pipeline for handling user-uploaded images from ingestion through delivery.

Who Should Use This

• Frontend developers building responsive layouts who need multiple image sizes without manual resizing workflows
• Full-stack developers creating user upload features who want a managed transformation pipeline
• Performance engineers focused on reducing page weight through modern image formats like WebP and AVIF
• Content teams managing media-heavy sites where consistent image dimensions and quality matter
• DevOps engineers looking to eliminate third-party image CDN services and consolidate tooling within Netlify
• Jamstack architects designing scalable static or hybrid sites that require dynamic image handling

Why Use It?

Problems It Solves

• Serving oversized images that slow down page load times and hurt Core Web Vitals scores
• Maintaining multiple manually resized image variants for different breakpoints and device densities
• Managing external image CDN subscriptions and their associated configuration complexity
• Handling user-uploaded images without a dedicated processing backend
• Proxying and optimizing images from third-party sources without building a custom middleware layer

Core Highlights

• Built into every Netlify site with no additional setup or third-party accounts required
• Transforms images via simple URL query parameters for width, height, format, and quality
• Automatically converts images to modern formats including WebP and AVIF based on browser support
• Supports remote image sources through a configurable allowlist in netlify.toml
• Integrates with Netlify Blobs for storing and serving user-uploaded images
• Edge caching ensures transformed images are delivered quickly on repeat requests
• Clean URL rewrites allow hiding the /.netlify/images path from public-facing URLs
• Works alongside Netlify Functions to build complete upload and transformation pipelines

How to Use It?

Basic Usage

To request a transformed image, append query parameters to the /.netlify/images endpoint with the url parameter pointing to your source image.

/.netlify/images?url=/images/hero.jpg&w=800&h=400&fit=cover&fm=webp&q=80

This request resizes the image to 800 by 400 pixels, crops it to cover the area, converts it to WebP format, and sets quality to 80.

Specific Scenarios

Responsive image markup: Use the srcset attribute to serve different sizes based on viewport width.

<img
  src="/.netlify/images?url=/images/photo.jpg&w=800"
  srcset="
    /.netlify/images?url=/images/photo.jpg&w=400 400w,
    /.netlify/images?url=/images/photo.jpg&w=800 800w,
    /.netlify/images?url=/images/photo.jpg&w=1200 1200w
  "
  sizes="(max-width: 600px) 400px, (max-width: 900px) 800px, 1200px"
  alt="Responsive photo"
/>

Remote image allowlisting: Add permitted external domains to netlify.toml before proxying remote images.

[images]
  remote_images = ["https://images.example.com/.*", "https://cdn.partner.com/.*"]

Then reference the remote image directly through the endpoint.

/.netlify/images?url=https://images.example.com/product.jpg&w=600&fm=avif

Real-World Examples

An e-commerce site uses the CDN to serve product thumbnails at 300 by 300 pixels and full-size images at 1200 pixels wide from a single source file, eliminating the need to store multiple variants.

A media platform accepts user photo uploads via a Netlify Function, stores them in Netlify Blobs, and serves them through the image CDN with consistent cropping and quality settings applied at request time.

When to Use It?

Use Cases

• Building responsive image components in React, Vue, or plain HTML
• Optimizing hero images and banners for faster Largest Contentful Paint scores
• Creating thumbnail grids for portfolios, product catalogs, or media libraries
• Processing and serving user-uploaded profile photos or document previews
• Proxying and optimizing images from a headless CMS or external asset storage
• Replacing a paid image CDN service with a native Netlify solution
• Generating social preview images with consistent dimensions and format

Important Notes

Requirements

• A deployed Netlify site is required; the image CDN is not available in local development without the Netlify CLI
• Remote image sources must be explicitly allowlisted in netlify.toml before they can be proxied
• Source images must be accessible to the Netlify CDN, either as site assets or via allowed remote URLs