Image Delivery

How ValGuide stores, transforms, and delivers images to visitors and curators.

System Overview

ValGuide stores all media (images, audio, video) in Cloudflare R2. Images are transformed on the fly — resized, format-converted, and quality-optimized — before reaching the browser. Audio and video are served directly from R2 without transformation.

The active image delivery provider is controlled by VITE_IMAGE_DELIVERY_PROVIDER when set, with fallback to the legacy VITE_IMAGE_PROVIDER. Supported providers are cloudflare, imagekit, and origin.

The schema-level fallback default remains cloudflare until deployment envs are switched explicitly.

Cloudflare mode (VITE_IMAGE_DELIVERY_PROVIDER=cloudflare)

┌─────────────┐     ┌──────────────────────┐     ┌───────────────┐     ┌─────────┐
│   R2 Bucket │────▶│  Image Guard Worker  │────▶│  Edge Cache   │────▶│ Browser │
│  (originals)│     │  /i/w-640/path.jpg   │     │  (Cloudflare) │     │  + SW   │
└─────────────┘     └──────────────────────┘     └───────────────┘     └─────────┘
                              │
                    fetch(origin, {
                      cf: { image: {
                        width, quality,
                        format, fit
                      }}
                    })

ImageKit mode (VITE_IMAGE_DELIVERY_PROVIDER=imagekit)

┌─────────────┐     ┌──────────────────────┐     ┌─────────┐
│   R2 Bucket │────▶│  ImageKit CDN        │────▶│ Browser │
│  (originals)│     │  (transforms + CDN)  │     │  + SW   │
└─────────────┘     └──────────────────────┘     └─────────┘

Architecture Layers

Request Flow

1. <Image> component generates /i/ URLs

The custom <Image> component (wrapping @unpic/react) uses a transformer that converts source URLs into /i/ URLs with transform params:

Source:  https://assets.valguide.com/orgs/abc/cover.jpg
srcset:  https://assets.valguide.com/i/w-320/orgs/abc/cover.jpg 320w,
         https://assets.valguide.com/i/w-640/orgs/abc/cover.jpg 640w,
         https://assets.valguide.com/i/w-960/orgs/abc/cover.jpg 960w,
         ...

2. Worker validates and transforms

The Image Guard Worker at /i/*:

1. Parses the URL: /i/w-640,q-80/orgs/abc/cover.jpg
2. Snaps width to the nearest allowed value: 320, 640, 960, 1280, 1920 (e.g., w-999 → 960)
3. Clamps quality to max 85 (default 75)
4. Negotiates format from the browser's Accept header (AVIF → WebP → JPEG)
5. Ignores unknown transform keys silently (forward-compatible)
6. Fetches the original from R2 with cf.image options:

fetch('https://assets.valguide.com/orgs/abc/cover.jpg', {
  cf: {
    image: {
      width: 640,
      quality: 75,
      format: 'webp', // negotiated from Accept header
      fit: 'cover',
    },
  },
})

Cloudflare's edge performs the resize/encode as part of this fetch() call. The Worker never handles image bytes — it only validates and forwards.

3. Caching (three layers)

On repeat requests, the browser serves from local cache without any network call.

URL Format

https://assets.valguide.com/i/{transforms}/{storagePath}

Transform params

Multiple params are comma-separated: /i/w-640,q-80/path.jpg

Fallback behavior

The Worker never returns 400 errors for transform issues — it uses sensible fallbacks instead:

Always enforced (not configurable via URL)

Examples

/i/w-320/orgs/abc/cover.jpg          → 320px wide, q75, auto format
/i/w-1920/orgs/abc/cover.jpg         → 1920px wide, q75, auto format
/i/w-640,q-80/orgs/abc/cover.jpg     → 640px wide, q80, auto format
/i/w-640,h-400/orgs/abc/cover.jpg    → 640×400, q75, auto format

Width Whitelist

All requested widths are snapped to the nearest of 5 allowed values: 320, 640, 960, 1280, 1920

The Worker never rejects invalid widths — instead it snaps w-999 to 960, w-50 to 320, etc. This ensures bots and crawlers always get a valid image while still capping unique transformations to 5 per source image.

This exists for three reasons:

1. Cost control — Cloudflare bills per unique (source + params) transformation per month ($0.50/1,000). With 5 widths, 1,000 images = 5,000 unique transformations (within free tier). Without restriction, a bot could generate thousands of billable variants.

2. Cache efficiency — Fewer variants means higher cache hit rates at the edge. 5 widths cover all standard responsive breakpoints.

3. Predictability — Monthly cost scales linearly with image count: images × 5 = unique transformations.

Code Locations

Using the <Image> Component

The custom Image component provides automatic responsive images, lazy loading, and content layout shift prevention.

// In apps (studio, app, admin):
import { Image } from '@valguide/ui/components/image'

// In packages/core:
import { Image } from '@valguide/core/ui/components/image'

Layout Modes

For component patterns, code examples, and usage conventions, see Image Handling.

Pricing

We use Cloudflare Image Transformations (not the Cloudflare Images storage product).

A "unique transformation" = unique (source image + params) combo, billed once per calendar month. Repeat requests serve from cache at no cost. There are no delivery fees.

Related

• Image Handling — <Image> component patterns, URL helpers, fallbacks, usage inventory, and coding conventions