Netlify 09 ๐ Image CDN & Asset Optimization โ Transforming images on demand with automatic content negotiation and zero build-time cost
Images are usually the heaviest payload a site ships, and the classic solutions to that problem all cost something. Committing five resized variants per photo bloats the repository. Running a build step that generates every size delays every deploy. Handing the work to a third-party image service adds another vendor, another bill, and another cache to invalidate.
Netlify’s Image CDN takes a different position: the original image is stored once, and the transformations happen on demand at the edge, the first time someone requests them. A request for a 400px WebP version of a photo is served by a URL that describes the transformation in query parameters, and the transform result is cached on Netlify’s CDN so the second request is as fast as a static file. Nothing is generated at build time, and nothing extra is stored in Git.
This chapter covers the /.netlify/images endpoint and its parameters, the content negotiation mechanism that picks a format from the browser’s Accept header, the allowlist that must be configured for remote images, and the framework adapters that wire the CDN into next/image and similar components. The sections that follow walk through the endpoint, the negotiation rules, and the integration path.
Key point: The Netlify Image CDN is a request-time image transformer: the URL /.netlify/images?url=/photo.jpg&w=800&fm=webp asks Netlify’s edge to decode, resize, and re-encode the source image, cache the result, and serve it on subsequent requests โ so image variants never enter your repository or your build.
Why X exists
The build-time cost problem. The standard approach to responsive images is a build plugin that generates every width and format combination ahead of time. It works, but it scales badly: ten images across six widths and two formats is a hundred and twenty files to generate, name, hash, and commit or upload on every deploy. The Image CDN removes the generation step entirely by moving the work to the request that needs it.
The format fragmentation problem. AVIF compresses better than WebP, WebP compresses better than JPEG, and support differs by browser and version. Serving one format means either over-serving bytes to modern browsers or under-serving quality to old ones. A request-time transform can inspect the Accept header and choose per-request, without maintaining parallel asset directories.
The responsive image problem. A correct srcset needs several distinct widths of the same picture, each with correct width and height attributes to avoid layout shift. Writing those by hand is tedious and error-prone, and every new breakpoint means a new asset. When the URL itself describes the transformation, the srcset is just a list of URLs that differ in one parameter.
The cache invalidation problem. Pre-generated variants are keyed by filename, so replacing a source image means either busting every derived filename or living with stale variants. When the transformation is a URL parameter, replacing the source under the same path plus changing a cache-busting query parameter invalidates the whole derived set at once.
The trade-off. The trade-off is that the first request for a given transformation is slower than the rest โ the edge has to fetch the source, decode it, and encode the output before it can respond. Transformations are also bounded by memory and time limits, so an enormous source image, or a wildly upscaled target, will fail rather than succeed slowly. For a fixed set of one or two sizes used everywhere, a build step is still competitive; the CDN wins once the number of variants grows or the source images change.
a. The endpoint and its parameters
Every transform goes through a single path: /.netlify/images. The url parameter is required and names the source image, either as a site-relative path or as an absolute remote URL that has been allowlisted. The remaining parameters describe the output.
<!-- A site-relative source, resized to 400px wide, no format change -->
<img src="/.netlify/images?url=/photos/beach.jpg&w=400" alt="Beach">
<!-- Absolute width and height with cover cropping -->
<img
src="/.netlify/images?url=/photos/beach.jpg&w=800&h=600&fit=cover&position=center"
alt="Beach">
The w and h parameters are pixel dimensions. With only w, the height is derived from the aspect ratio. The fit parameter decides what happens when both are given: contain fits the whole image inside the box, cover fills the box and crops the overflow, and fill stretches. When fit=cover crops, position decides which part survives โ center by default, or top, bottom, left, right, and combinations such as left top.
<!-- Preserve the whole frame inside a 300x300 box -->
<img src="/.netlify/images?url=/photos/beach.jpg&w=300&h=300&fit=contain" alt="">
<!-- Crop to a square, keeping the upper part of the frame -->
<img src="/.netlify/images?url=/photos/beach.jpg&w=300&h=300&fit=cover&position=top" alt="">
The fm parameter sets the output format โ avif, webp, jpg, png, gif โ and q sets quality on a 1โ100 scale. Omitting fm is the interesting case, and it is the subject of the next section. SVG sources are an exception: they are vector files and are not run through the raster pipeline, so there is no resize benefit to requesting one through the endpoint.
b. Automatic content negotiation
When fm is absent, the endpoint consults the request’s Accept header. A browser that advertises image/avif gets AVIF; one that advertises only image/webp gets WebP; one that advertises neither gets the source format. The response carries a Vary: Accept header so that intermediary caches keep the variants separate instead of serving a WebP to a client that cannot decode it.
<!-- No fm: format chosen from Accept, quality fixed at 80 -->
<img src="/.netlify/images?url=/photos/beach.jpg&w=1200&q=80" alt="Beach">
<!-- fm pinned: every client gets WebP, negotiation disabled -->
<img src="/.netlify/images?url=/photos/beach.jpg&w=1200&fm=webp" alt="Beach">
Pinning fm is occasionally right โ an Open Graph image, a download link, an email asset โ but for <img> elements the negotiated form is almost always preferable, because it lets a new format reach supporting browsers the moment Netlify’s pipeline supports it, without touching your markup.
The caching behaviour is what makes the design viable. The first request for a given combination of URL, w, h, fit, position, fm, and q performs the transform; the result is then stored at the edge. Because the query string is part of the cache key, each distinct transformation is its own object, and there is no ambiguity about what is being cached. The consequence is that an unbounded set of parameters is also an unbounded set of cache objects: a srcset with five widths produces five objects per image, which is fine, while a client that appends random w values produces garbage entries.
<!-- Five widths -> five cached variants of the same source -->
<img
src="/.netlify/images?url=/photos/beach.jpg&w=800"
srcset="/.netlify/images?url=/photos/beach.jpg&w=400 400w,
/.netlify/images?url=/photos/beach.jpg&w=800 800w,
/.netlify/images?url=/photos/beach.jpg&w=1200 1200w,
/.netlify/images?url=/photos/beach.jpg&w=1600 1600w,
/.netlify/images?url=/photos/beach.jpg&w=2400 2400w"
sizes="(max-width: 600px) 400px, 800px"
alt="Beach">
Note the deliberate conjunction of srcset widths with the sizes attribute: the browser picks one candidate, so only the widths actually used in practice get transformed and cached. A srcset with no sizes statement, or with a sizes value that resolves to one width on every device, wastes cache entries without improving delivery.
c. Remote images and framework integration
Site-relative sources work without configuration. Remote sources are blocked unless the host is listed in the [images] section of netlify.toml, as a regular expression matched against the full URL. This is a security boundary: without it, the endpoint would be an open proxy that anyone could point at arbitrary URLs.
# netlify.toml
[images]
# Allow transforms of images hosted on these remote origins
remote_images = ["https://images\\.example\\.com/.*", "https://cdn\\.example\\.net/.*"]
The rule is matched as a regex against the complete URL, so the anchors and escaped dots matter. An unanchored pattern such as https://images.example.com still needs the trailing .* to match a path, and a pattern written too loosely โ .*example.com.* โ reopens the proxy problem for any host containing that string.
Frameworks integrate through their Netlify adapters rather than through hand-written URLs. With the Next.js adapter, next/image resolves to the Image CDN, and remote hosts still have to be declared in netlify.toml as remote_images for the edge to accept them, in addition to the images.remotePatterns setting that next/image itself validates against.
// next.config.js โ next/image allowlist for the build-time component
module.exports = {
images: {
remotePatterns: [{ protocol: "https", hostname: "images.example.com" }],
},
};
// netlify.toml โ the same host must also be allowlisted for the edge transform
// [images]
// remote_images = ["https://images\\.example\\.com/.*"]
Both lists are required and they serve different purposes: the framework list keeps the component from generating URLs for arbitrary hosts, and the netlify.toml list keeps the edge from accepting transforms for arbitrary hosts. Configuring only one of them produces the confusing failure mode where the URL is generated correctly but returns a 403 or an untransformed image.
Astro’s Netlify adapter and the netlify provider for @nuxt/image follow the same pattern โ the adapter rewrites the component’s output to /.netlify/images and the allowlist lives in netlify.toml. For local development, netlify dev proxies transform requests to the deployed site’s Image CDN, which means the feature must be enabled on the site before it works locally.
Complete Example Session
// ============================================
// PART 1: THE SMALLEST POSSIBLE TRANSFORM
// ============================================
<!-- Only url: the image is processed, dimensions unchanged -->
<img src="/.netlify/images?url=/photos/beach.jpg" alt="Beach">
// ============================================
// PART 2: RESIZE BY WIDTH
// ============================================
<!-- Height follows from the aspect ratio -->
<img src="/.netlify/images?url=/photos/beach.jpg&w=640" alt="Beach">
// ============================================
// PART 3: CROP TO A FIXED BOX
// ============================================
<!-- cover fills the box, position chooses the surviving area -->
<img
src="/.netlify/images?url=/photos/beach.jpg&w=400&h=400&fit=cover&position=center"
alt="Beach thumbnail">
// ============================================
// PART 4: LET NEGOTIATION PICK THE FORMAT
// ============================================
<!-- No fm: AVIF or WebP depending on the Accept header -->
<img src="/.netlify/images?url=/photos/beach.jpg&w=1200&q=80" alt="Beach">
// ============================================
// PART 5: PIN THE FORMAT WHEN IT MUST BE FIXED
// ============================================
<!-- Social cards generally want a predictable type -->
<meta property="og:image"
content="/.netlify/images?url=/photos/beach.jpg&w=1200&h=630&fit=cover&fm=jpg&q=85">
// ============================================
// PART 6: RESPONSIVE SRCSET
// ============================================
<img
src="/.netlify/images?url=/photos/beach.jpg&w=800"
srcset="/.netlify/images?url=/photos/beach.jpg&w=400 400w,
/.netlify/images?url=/photos/beach.jpg&w=800 800w,
/.netlify/images?url=/photos/beach.jpg&w=1600 1600w"
sizes="(max-width: 600px) 400px, 800px"
width="800" height="533"
alt="Beach">
// ============================================
// PART 7: ALLOWLIST A REMOTE ORIGIN
// ============================================
<!-- netlify.toml -->
<!--
[images]
remote_images = ["https://images\\.example\\.com/.*"]
-->
// ============================================
// PART 8: TRANSFORM A REMOTE IMAGE
// ============================================
<img src="/.netlify/images?url=https://images.example.com/hero.jpg&w=1600&q=75" alt="Hero">
// ============================================
// PART 9: FRAMEWORK COMPONENT OUTPUT
// ============================================
<!-- The Next.js adapter emits this shape on your behalf -->
<!-- <Image src="/hero.jpg" width={800} height={500} alt="Hero" /> -->
<!-- becomes /.netlify/images?url=%2Fhero.jpg&w=800&q=75 -->
// ============================================
// PART 10: VERIFY THE CACHE
// ============================================
<!-- curl -sI "https://site.netlify.app/.netlify/images?url=/photos/beach.jpg&w=400" -->
<!-- First request: transform. Second request: cache hit. -->
<!-- Compare with curl -sI -H "Accept: image/avif" to see a different cache entry. -->
The ten parts covered the minimal request, width-based resizing, box cropping, negotiated and pinned formats, a responsive srcset, the remote allowlist, framework-generated URLs, and cache verification.
Quick Reference
Transform Parameters
| Parameter | Values | Meaning |
|---|---|---|
url | Path or allowlisted URL | Source image (required) |
w | Pixels | Target width |
h | Pixels | Target height |
fit | contain, cover, fill | Resize strategy |
position | center, top, left top, โฆ | Crop anchor when cover |
fm | avif, webp, jpg, png, gif | Output format |
q | 1โ100 | Output quality |
Fit Strategies
| Value | Behaviour |
|---|---|
contain | Whole image fits inside the box |
cover | Box is filled, overflow cropped |
fill | Image stretched to the box |
Format Behaviour
fm State | Result |
|---|---|
| Absent | Chosen from Accept, Vary: Accept set |
| Present | Forced for every client |
| SVG source | Served untransformed |
Remote Image Configuration
| Location | Purpose |
|---|---|
netlify.toml โ [images].remote_images | Edge accepts the transform |
next.config.js โ images.remotePatterns | Component emits the URL |
Best Practices
โ Do This:
<!-- Use the negotiated format for <img> elements --> <!-- โ
-->
<img src="/.netlify/images?url=/a.jpg&w=800&q=75" alt="">
<!-- Pair srcset with a real sizes attribute --> <!-- โ
-->
<img srcset="/.netlify/images?url=/a.jpg&w=400 400w, ..." sizes="50vw" alt="">
<!-- Set width and height to avoid layout shift --> <!-- โ
-->
<img src="/.netlify/images?url=/a.jpg&w=800" width="800" height="533" alt="">
<!-- Anchor the remote_images regex tightly --> <!-- โ
-->
remote_images = ["https://images\\.example\\.com/.*"]
<!-- Pin fm only where the consumer needs a fixed type --> <!-- โ
-->
<meta property="og:image" content="...&fm=jpg">
โ Don’t Do This:
<!-- Upscale beyond the source dimensions --> <!-- โ -->
<img src="/.netlify/images?url=/a.jpg&w=4000" alt="">
<!-- Feed SVGs to the raster pipeline --> <!-- โ -->
<img src="/.netlify/images?url=/logo.svg&w=200" alt="">
<!-- Allowlist the whole internet --> <!-- โ -->
remote_images = [".*"]
<!-- Generate unbounded w values from user input --> <!-- โ -->
<img src="/.netlify/images?url=/a.jpg&w={query.w}" alt="">
<!-- Use a fixed fm for every <img> on the page --> <!-- โ -->
<img src="/.netlify/images?url=/a.jpg&fm=jpg" alt="">
Common Pitfalls
| Pitfall | Why It Happens | Fix |
|---|---|---|
| 403 on a remote source | Host missing from remote_images | Add an anchored regex pattern |
| Slow first paint | Cold transform on first request | Warm key widths after deploy |
| Blurry output | Target width exceeds source | Cap the largest srcset width |
| Same format for everyone | fm pinned in markup | Remove fm and let Accept decide |
| No resizing on a logo | SVG source | Serve the SVG directly |
| Cache filled with junk | Unbounded w from user input | Whitelist the allowed widths |
| Works locally, 403 in prod | Feature not enabled on the site | Enable Image CDN in site config |
| Layout shift on load | Missing width/height | Set intrinsic dimensions |
Real-World Examples
1. Hero With Negotiated Format
<img src="/.netlify/images?url=/hero.jpg&w=1600&q=75" alt="Hero">
2. Square Avatar Crop
<img src="/.netlify/images?url=/team/ana.jpg&w=96&h=96&fit=cover&position=top" alt="Ana">
3. Social Card, Format Pinned
<meta property="og:image" content="/.netlify/images?url=/og.jpg&w=1200&h=630&fit=cover&fm=jpg">
4. Remote Product Photo
<img src="/.netlify/images?url=https://images.example.com/p/1.jpg&w=600" alt="Product">
5. Allowlisting the Remote Origin
[images]
remote_images = ["https://images\\.example\\.com/.*"]
6. Gallery Thumbnail Grid
<img src="/.netlify/images?url=/g/1.jpg&w=240&h=240&fit=cover" loading="lazy" alt="">
7. Low-Quality Placeholder
<img src="/.netlify/images?url=/hero.jpg&w=32&q=20" alt="">
8. Blog Inline Illustration
<img src="/.netlify/images?url=/posts/x/figure.png&w=760&fit=contain" alt="Diagram">
9. Framework Component
// Next.js adapter output for <Image src="/hero.jpg" width={800} height={500} />
// -> /.netlify/images?url=%2Fhero.jpg&w=800&q=75
10. Cache Verification
curl -sI "https://site.netlify.app/.netlify/images?url=/hero.jpg&w=400" | grep -i cache-control
Visual
The Transform Request
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ BROWSER โ
โ GET /.netlify/images?url=/beach.jpg&w=800 โ
โ โ โ
โ โผ โ
โ NETLIFY EDGE โ
โ cache miss โโโบ fetch source โโโบ decode โ
โ โ โ
โ โผ โ
โ resize to 800px โโโบ encode โโโบ store at edge โ
โ โ โ
โ โผ โ
โ RESPONSE (second request skips the pipeline) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Format Negotiation and Cache Keys
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ SAME URL, DIFFERENT ACCEPT HEADERS โ
โ โ
โ Accept: image/avif,image/webp โโโบ AVIF entry โ
โ Accept: image/webp โโโบ WebP entry โ
โ Accept: image/jpeg โโโบ JPEG entry โ
โ โ
โ Response carries Vary: Accept โ
โ so caches never hand a WebP to a JPEG client. โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Build-Time Versus Request-Time
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ BUILD-TIME (plugin) REQUEST-TIME (CDN) โ
โ โโโ 6 widths x 2 formats โโโ 0 files in repo โ
โ โโโ 12 files per image โโโ 1 source file โ
โ โโโ slow deploys โโโ slow first hit โ
โ โโโ stale variants โโโ self-invalidating โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
The Remote Allowlist Boundary
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ ?url=https://images.example.com/a.jpg โ
โ โ โ
โ โผ โ
โ MATCH against [images].remote_images โ
โ โ โ
โ allowed โโโโโโดโโโโโ not allowed โ
โ โ โ โ
โ โผ โผ โ
โ transform 403 โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Summary
| Item | Value |
|---|---|
| Endpoint | /.netlify/images |
| Required parameter | url |
| Dimensions | w, h |
| Fit strategies | contain, cover, fill |
| Crop anchor | position |
| Format | fm, negotiated from Accept when absent |
| Quality | q, 1โ100 |
| Remote sources | netlify.toml โ [images].remote_images |
| Cache key | Full query string plus Vary: Accept |
| Build cost | None |
Key takeaways:
- The URL is the transformation. Every variant is described by a query string, so there are no derived files to store, name, or invalidate in Git.
- Omit
fmunless something requires a fixed type. Negotiation through theAcceptheader reaches supporting browsers with better formats without any markup change, andVary: Acceptkeeps the cache entries separate. - The first request pays. Transforms happen on a cache miss, so a cold width after a deploy is slower than the same width afterwards. Warm the handful of widths that appear in
srcsetif the first paint matters. - Remote images are denied by default. The
remote_imagesregex innetlify.tomlis the allowlist, and it is separate from any framework-level allowlist such asnext/image‘sremotePatterns; both are needed. - Not everything benefits. SVGs bypass the raster pipeline, upscaling beyond the source dimensions only adds bytes, and a fixed one-size transform often does not justify the round trip.
Remember: The Image CDN moves image work from build time to request time, which means the source file is the only artifact you own and every variant is a description in a URL. Keep the set of transformations small and deliberate, let Accept negotiation handle format selection, and anchor the remote allowlist tightly. What you gain is a deploy pipeline that no longer scales with the number of image variants, and what you give up is the certainty of a warm cache on the first request after every release.
Stop using slow, ad-bloated tool sites! ๐คฎ
๐ Search “KandZ Tools” on Google to use many professional utilities for free.
KandZ.me is the ultimate minimalist hub for:
โ
Finance (Mortgage, Interest, Inflation)
โ
Tech (Base64, JSON, Dev Suite, IP)
โ
Health (BMI, BMR, TDEE)
โ
Productivity (Timer, Workspace, QR)
โก๏ธ Fast & Private
๐ No data leaves your device
๐ 100% Free
๐ Use it now: https://tools.kandz.me
๐ Bookmark itโyouโll need it later!