An image CDN caches the derivatives it generates. What forms the cache key for a derivative, and how does a front-end team accidentally destroy that cache's hit rate?

## What is actually being cached An image CDN stores **derivatives** — the resized, re-encoded outputs it has already produced — so it does not have to redo that work. Every derivative sits under a **cache key**. Understanding what goes into that key is the whole game, because two requests reuse the same stored bytes if and only if they compute the same key. A typical key is built from: - **The path**, which identifies the master image. - **The transformation parameters**: width, height, fit/crop mode, quality, format, and anything else the vendor supports. - **Selected request headers**, when the response genuinely depends on them — most commonly the client's accepted formats, and sometimes a device-pixel-ratio hint. Everything in that key multiplies. Five widths times three formats is fifteen derivatives per master, each with its own miss to pay and its own storage. ## The cost of a miss On a hit, the edge streams bytes it already has. On a miss it must fetch the master from origin, decode a possibly very large image, resize it, encode the output — AVIF encoding in particular is CPU-hungry — and only then start responding. That is easily hundreds of milliseconds, and it lands on whichever unlucky visitor asked first. This matters disproportionately for the largest image on the page, because that image is usually what the browser paints last and what your loading metrics are measured against. "The hero is fast in staging" often just means staging's cache was warm. ## Four ways teams destroy hit rate **Runtime-computed dimensions.** Code that measures the container and requests exactly that many pixels feels precise and is a disaster for caching: ```js // every viewport width mints a distinct derivative const w = Math.round(el.clientWidth * devicePixelRatio); img.src = `/photos/hero.jpg?width=${w}`; ``` Across real devices this produces hundreds of near-identical widths — 731, 733, 736 — that look the same to a human and are entirely different to a cache. Snapping to a small fixed ladder collapses them back to a handful of keys with no visible difference. **Foreign query parameters.** Analytics tags, campaign parameters, or a deploy-stamped `?v=` appended to image URLs change the key even though they change nothing about the image. Some CDNs can be configured to ignore unknown parameters when keying; do not assume yours does. **Inconsistent formatting.** `?w=640&q=75` and `?q=75&w=640` may key differently, as may `AUTO` versus `auto`. Multiple templates written by multiple people drift apart quickly. **Per-request tokens.** Signed URLs whose signature includes a fresh timestamp, or a per-user identifier, make every request unique by construction. Signing is worth having — but the signature must be stable for a given transformation, or excluded from the key, or the cache is decorative. ## Making the key small on purpose The discipline is to treat the set of URLs your site can emit as a deliberately bounded set: - Generate every image URL through **one helper function** so parameter names, order, and casing are identical everywhere and no template can invent its own dialect. - **Quantize** any computed dimension to a fixed ladder before it reaches the URL. - **Strip** parameters the CDN does not understand, at the edge, so a stray tracking tag cannot fragment the cache. - Keep the master path **stable and versioned** — a new image gets a new path, rather than new bytes at an old path. ## Watching it in production The number to alarm on is **cache hit ratio for image requests**, split by whether the request was a miss. A healthy pipeline sits high and boring; a sudden fall almost always means new URLs are being minted — a shipped change that started computing widths, a new tracking parameter, or someone probing the endpoint. Pair that with **miss latency**, because hit ratio alone hides the impact. A 95% hit ratio sounds fine until you notice the 5% is concentrated on first views of new campaign pages, where the miss lands on the hero. One more subtlety: the edge cache is not the only cache. Repeat visitors may be served from the browser cache regardless of edge state, which is why field data can look better than a synthetic cold run — and why a cold-cache test is the honest one when you are judging the pipeline itself.