Caching

Transformed images are cached in Cloudflare R2 so subsequent identical requests skip the origin fetch and image processing entirely.

Cache key

The cache key is built from the output format, URL path, and query string:

{format}{pathname}{search}

// Example:
avif/photos/hero.jpg?w=800&quality=80

Because steps snap query parameters to fixed values before cache lookup, similar requests like ?w=799 and ?w=801 resolve to the same cache key.

Cache behavior

Status	Description
HIT	Image is served directly from R2, no origin fetch or processing
MISS	Image is fetched from origin, transform, stored in R2, and served
BYPASS	Image processing failed; the original image is served unmodified

Observability

Every response includes an X-Cache header:

X-Cache: HIT     // served from R2
X-Cache: MISS    // fetched and processed from origin
X-Cache: BYPASS  // processing failed, original served

Cache storage

Cache writes are non-blocking - the response is sent to the client immediately, and the image is stored in R2 in the background. This keeps response times fast even on cache misses.

Cache duration

Cached responses include Cache-Control: public, max-age=86400 (24 hours). This applies to both the R2-stored object and the browser cache header.