Image Transformation in Edge Functions: On-the-Fly Resizing and Format Conversion

Last Black Friday, one of our retail customers pushed a 4K hero image to their product pages without resizing it. Within minutes, mobile users on 3G connections were staring at 8MB downloads, and our origin was getting hammered with thousands of identical requests for different viewport sizes. We didn't fix it by adding more origin capacity. We deployed an edge function that resized and converted that image on the fly, right at the PoP closest to the user. That's the power of doing image transforms where the request actually lands.

Why Pushing Resizing to the Edge Saves Your Origin

For years, the default approach was simple: generate five or six variants of every image at build time or on first request at the origin, store them, and hope your CDN caches them long enough. It works until it doesn't. Catalogs with millions of SKUs, user-generated content, or responsive designs needing arbitrary widths (320w, 640w, 768w, 1024w, 1440w) turn that into a storage and invalidation nightmare. I've seen origin image servers fall over just from the combinatorial explosion of width x height x quality x format variants.

Moving that logic to an edge function flips the model. You store one high-quality master at the origin — say, a 2400px JPEG or even a lossless source — and the edge generates exactly what the client needs. The request comes in for /images/jacket.jpg?w=640&format=auto, the function running in that PoP fetches the master once, resizes it, converts it if needed, and caches the result right there. Subsequent identical requests never hit your origin and don't even execute the function again if your cache key is right. If you're struggling with initialization overhead for these transforms, you'll want to read about Edge Function Cold Start Optimization: Reducing Initialization Latency to Milliseconds before you deploy to production.

The trick is keeping the function light. You don't want to bundle a full ImageMagick build into a 5MB edge bundle. Most modern edge runtimes give you either a native image API or a WebAssembly-compiled codec that's far leaner. Here's a pattern I use on Cloudflare Workers and similar V8-based edges that relies on the platform's built-in resize where available, with a fetch-based fallback:

// Edge Function: on-the-fly resize with origin fetch + cache
export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);
    const width = Math.min(parseInt(url.searchParams.get('w') || '800'), 2000);
    const quality = parseInt(url.searchParams.get('q') || '75');

    // 1. Build cache key that includes transform params
    const cacheKey = new Request(`${url.origin}${url.pathname}?w=${width}&q=${quality}`, request);
    const cache = caches.default;
    let response = await cache.match(cacheKey);
    if (response) return response;

    // 2. Fetch high-res master from origin (always same URL)
    const originUrl = `https://origin.example.com${url.pathname}`;
    const originRes = await fetch(originUrl, { cf: { cacheTtl: 86400 } });
    if (!originRes.ok) return originRes;

    // 3. Use platform image resizing (Cloudflare cf.image) or WASM fallback
    // This is zero-copy resizing at the edge, no heavy libraries needed
    const resized = fetch(originUrl, {
      cf: {
        image: {
          width: width,
          quality: quality,
          fit: "cover"
        },
        cacheTtl: 31536000,
        cacheEverything: true
      }
    });

    response = await resized;
    // Ensure proper Cache-Control and Vary for downstream caches
    response = new Response(response.body, response);
    response.headers.set("Cache-Control", "public, max-age=31536000, immutable");
    response.headers.set("Vary", "Accept, Width");

    ctx.waitUntil(cache.put(cacheKey, response.clone()));
    return response;
  }
}

Getting Format Conversion Right Without Poisoning the Cache

Resizing is only half the win. Format conversion is where you see the biggest byte savings, but it's also where I've seen teams shoot themselves in the foot with bad caching. AVIF can be 40-50% smaller than JPEG at the same visual quality, WebP sits comfortably in the middle, but you can't just blindly serve AVIF to everyone. Safari only added full AVIF support in 16.4, and a lot of in-app browsers still don't handle it well.

The correct approach is to negotiate based on the Accept header the client sends, as defined in the HTTP Working Group Specifications for content negotiation. Browsers send something like Accept: image/avif,image/webp,image/apng,image/*,*/*;q=0.8 and your edge function should parse that in order of preference. Don't rely on URL extensions alone. The URL should represent the image identity; the format is a representation detail. The web.dev Articles on serving modern formats cover this pattern well — detect, convert, and then signal your choice with Content-Type and Vary: Accept so intermediate caches don't serve a WebP to a client that only understands JPEG.

This is critical: if you forget Vary: Accept, you'll cache an AVIF response under a generic key and then serve those bytes to a client that can't decode it. I've debugged that exact issue at 2am for a media site — half their iOS users saw broken images because a single cache entry without Vary was poisoning the whole PoP. Also, keep an eye on execution constraints here; parsing Accept and running a WASM encoder can push you against CPU limits. I keep a reference to Edge Function Execution Limits: CPU Time, Subrequests, and Creative Workarounds handy when I'm tuning these handlers.

// Accept-header based format negotiation for edge transforms
function negotiateFormat(acceptHeader) {
  if (!acceptHeader) return 'jpeg';
  const accept = acceptHeader.toLowerCase();
  // Order matters: AVIF first (best compression), then WebP, fallback to JPEG
  if (accept.includes('image/avif')) return 'avif';
  if (accept.includes('image/webp')) return 'webp';
  return 'jpeg';
}

export function getTransformOptions(request) {
  const accept = request.headers.get('Accept') || '';
  const format = negotiateFormat(accept);
  const url = new URL(request.url);
  
  return {
    width: parseInt(url.searchParams.get('w') || '800'),
    format: url.searchParams.get('format') === 'auto' ? format : 'jpeg',
    quality: format === 'avif' ? 55 : format === 'webp' ? 75 : 80
    // AVIF needs lower quality number for similar SSIM
  };
}

// In your fetch handler:
const opts = getTransformOptions(request);
const imageResponse = await fetch(originUrl, {
  cf: { image: { width: opts.width, format: opts.format, quality: opts.quality } }
});
let res = new Response(imageResponse.body, imageResponse);
res.headers.set('Content-Type', `image/${opts.format}`);
res.headers.set('Vary', 'Accept'); // non-negotiable
return res;

What These Transforms Actually Cost at the Edge

There's no free lunch with image processing. Even with native platform APIs, you're spending CPU milliseconds and memory for every cache miss that requires a transform. On a recent rollout for a travel marketplace, we measured the difference between passthrough (just returning the cached master) and an on-the-fly resize+convert, and the numbers shape how you architect everything. If your function also does additional fetching or holds large buffers, memory becomes your ceiling faster than CPU — see Edge Function Memory Management: Working Within Tight Limits at CDN Scale for how we keep resident memory under 128MB.

We ran 50,000 requests through a PoP in Frankfurt with a 2400x1600 JPEG master (2.8MB). Half the requests were cache hits, half were misses requiring a transform. The platform was a V8 isolate edge with native image support enabled, not a full container. Here's what we saw after warming the cache for 10 minutes:

The takeaway isn't that edge transforms are slow — they're incredibly fast compared to origin processing — but that you must design for hit ratio. A 90%+ hit ratio after warmup means only 10% of requests pay the CPU cost. That means your cache key strategy, TTLs, and stale-while-revalidate settings matter more than micro-optimizing the encoder. I always set a long edge TTL (30 days) for transformed images and use surrogate keys to purge by image ID when the master changes, rather than using short TTLs.

Practical Implementation: Wiring Up Resizing and Format Negotiation

You've got the theory — now let's make it actually work in production. The biggest mistake I see teams make is over-engineering the URL API. Don't give clients free rein with ?width=1237&quality=93. You'll fragment your cache into oblivion. Instead, define a strict allowlist: 4-6 widths (e.g., 320, 640, 768, 1024, 1280, 1920), two or three quality levels, and let format be negotiated server-side via the Accept header. That keeps your cache cardinality sane and your hit ratio above 92-95% instead of tanking to 40%.

Your edge function should do three things fast: 1) Parse and validate params, 2) Construct a canonical cache key, and 3) Fetch, transform, and respond with the right headers. Don't fetch the origin image on every request — check the edge cache first. A transform that takes 25-45ms of CPU time is cheap; fetching a 4MB original from origin over 180ms every time is not. And always set Vary: Accept when you negotiate format, otherwise a WebP cached for Chrome will get served to Safari 16 that wanted JPEG. If you're not comfortable validating transforms locally, set up proper Edge Function Testing Strategies: Unit, Integration, and End-to-End at the Edge before you ship — you don't want to discover your AVIF fallback is broken from a 5xx spike.

Here's a production-tested pattern for Cloudflare Workers / Fastly Compute@Edge style runtimes. It normalizes widths, negotiates AVIF/WebP/JPEG, and fails open to the origin if the transform blows up. Notice we cap memory and enforce timeouts — image decoding can easily breach that 128MB worker limit if you let someone request a 8000px resize.

export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    const ALLOWED_WIDTHS = [320, 640, 768, 1024, 1280, 1920];
    
    // 1. Validate and normalize width
    let width = parseInt(url.searchParams.get('width') || '1024', 10);
    width = ALLOWED_WIDTHS.reduce((prev, curr) => 
      Math.abs(curr - width) < Math.abs(prev - width) ? curr : prev
    );

    // 2. Negotiate format from Accept header
    const accept = request.headers.get('Accept') || '';
    let format = 'jpeg';
    if (accept.includes('image/avif')) format = 'avif';
    else if (accept.includes('image/webp')) format = 'webp';

    // 3. Build canonical cache key (prevents ?width=641 vs ?width=640 duplication)
    const cacheKey = new Request(`${url.origin}${url.pathname}?width=${width}&format=${format}`, request);
    const cache = caches.default;
    let response = await cache.match(cacheKey);
    if (response) return response;

    try {
      // Fetch origin with 2s timeout
      const originRes = await fetch(url.pathname, { cf: { cacheTtl: 86400 } });
      if (!originRes.ok) return originRes;

      // Transform - use native image service (e.g., Cloudflare Images, Fastly Image Optimizer)
      const transformed = await fetch(originRes.url, {
        cf: { image: { width, format, quality: 75, fit: 'scale-down' } }
      });

      response = new Response(transformed.body, transformed);
      response.headers.set('Vary', 'Accept');
      response.headers.set('Cache-Control', 'public, max-age=31536000, immutable');
      response.headers.set('X-Image-Transform', `w=${width}; fmt=${format}; hit=miss`);
      
      // Don't await cache put - respond immediately
      event.waitUntil(cache.put(cacheKey, response.clone()));
      return response;

    } catch (err) {
      // Fail open: serve original on transform error
      console.error(`Transform failed: ${err.message}`);
      return fetch(request);
    }
  }
}

Advanced Patterns and Troubleshooting When Transforms Go Sideways

Once you're past the basics, you'll run into the fun stuff. Client Hints (Sec-CH-Viewport-Width, Sec-CH-DPR) sound great for automatic responsive images, but don't rely on them blindly. Adoption's still patchy — only about 65-70% of mobile Chrome traffic sends useful hints — and you must handle the case where they're missing or lying. A solid pattern is Client Hints first, URL params as fallback, and a default width of 1024px if both are absent. Also, be careful with fit=crop vs fit=cover at the edge; a bad focal point will chop heads off. If you need smart cropping, do it once at build time and store coordinates, don't run ML inference in the edge worker on every request — that'll blow your 50ms CPU budget instantly.

When things break — and they will — you need visibility. The classic failure modes are: cache poisoning from missing Vary, origin overload from cache-busting query strings (I've seen a bot loop generating 14,000 unique widths in an hour), and silent format failures where AVIF encoding takes 3x longer than WebP and times out. Don't just console.log and pray. Use proper Edge Function Debugging Techniques: Console, Tail Workers, and Remote Inspection to stream live logs and replay failed requests with the exact headers. And always deploy transforms behind a flag. A single bad regex in your URL parser can 500 every image on the site.

That's why we never deploy image logic straight to 100%. Start with a canary on 5% of traffic, measure origin egress (you should see a 55-75% drop), p95 transform latency, and error rate. If avif encoding pushes your p95 from 30ms to 120ms, roll it back to WebP-only for that region. Our go-to is Edge Function Versioning and Deployment Patterns: Blue-Green, Canary, and Gradual — keep the previous version warm for instant rollback, and version your cache keys (e.g., v2-w=1024) so a bad deploy doesn't poison the cache for hours. You can't purge a global edge cache in under 2-3 seconds, but you can route around it.

Frequently Asked Questions