Caching
How Keenpix caches transforms and plays nicely with a CDN.
Optimizing an image is expensive; serving it again should be free. Keenpix caches every transform on disk and is built to sit behind a CDN.
The cache key
A result is keyed by everything that affects the output:
project + url + full transform option objectTwo requests with identical effective parameters share one cached file. Requests that arrive while the first identical transform is still running share that same in-flight work too.
In-flight coalescing
If many identical requests arrive during a cold cache (e.g. a popular image after a deploy), Keenpix runs the fetch + encode once and shares the result, instead of doing the same work N times.
CDN-friendly responses
Every successful response sets:
Cache-Control: public, max-age=31536000, immutable
Vary: AcceptBecause the source URL and every transform live in the URL, the response is immutable.
Configure your CDN to cache /img/* responses, including the full query string. For
Cloudflare, that usually means a Cache Rule for the endpoint; orange-cloud proxying alone
is not enough for every dynamic-looking path.
Vary: Accept keeps per-format variants correct under fmt=auto only when your CDN
supports caching separate variants by Accept. On CDNs that do not, prefer explicit
fmt=avif, fmt=webp, fmt=jpeg, fmt=png, or fmt=svg URLs. Explicit formats improve cache
predictability, but they also disable browser-based AVIF/WebP negotiation for that URL.
fmt=svg is one of those explicit formats; fmt=auto never preserves SVG output.
Where it's stored
The disk cache lives at KEENPIX_CACHE_DIR (default ./.keenpix-cache). Writes are
atomic (temp file + rename) so a crash mid-write can't serve a truncated image. See
Configuration for size limits and eviction.