id: 0008-images-from-the-bucket-domain
type: decision
owner: justin
status: accepted
reviewed: 2026-10-08

0008 Serve images from the bucket's custom domain

Context

[[0002-serve-images-through-the-api]] had storefront-api serve every image, and said to revisit it if image requests started to dominate. They have: a catalog page shows 24 products, so one page view is one API request and up to 24 image requests. Since the catalog went live, about 85% of the Worker's requests were GET /images/*, each one a Worker invocation returning bytes that never change. The shop also moved to its own domain, so a second hostname for images costs nothing to set up.

Decision

Make storefront-images public on images.larkspur.shop (an R2 custom domain) and return image URLs on that domain, from IMAGES_URL. Remove GET /images/* from storefront-api. Uploads still go through the API with the admin token ([[product-images]]).

Consequences

• Image requests are served by R2 and Cloudflare's cache and no longer count against the Worker.
• Everything in the bucket is public. Only product images go in it; anything private needs another bucket.
• The rule that only products/ keys are reachable is gone with the route. It held only because the Worker enforced it.
• Old /images/... URLs stop working. Nothing outside the shop's own pages used them, and those pages read image_url from the API.