Image Conversion on Cloudflare Workers

How we built server-side AVIF, JPG, PNG, and WebP conversion using WASM

The Challenge

Cloudflare Workers run in V8 isolates — not containers, not VMs. You can't install system binaries or use native Node.js addons. That rules out Sharp (which needs libvips), ImageMagick, and most traditional image processing libraries.

We needed to convert between AVIF, JPG, PNG, and WebP entirely within the Worker runtime. The only viable path: WebAssembly.

Why Cloudflare Workers

Workers run on Cloudflare's edge network — over 300 locations worldwide. Every API request is handled by the nearest data center, giving users sub-100ms latency regardless of where they are. Cold starts are typically under 5ms (compared to seconds for Lambda or Cloud Functions).

The trade-off is the constrained runtime. No filesystem, no native code, 128MB memory. But for a focused task like image conversion, these constraints are manageable.

The WASM Approach

We use two WASM libraries that cover all four formats:

• @cf-wasm/photon — A Cloudflare Workers fork of Photon (Rust-based). Handles JPG, PNG, and WebP decode/encode. Auto-loads its WASM module when imported via the @cf-wasm/photon/workerd entry point.
• @jsquash/avif — AVIF encode and decode based on libavif compiled to WASM. Requires manual WASM initialization because Workers can't fetch WASM at runtime — the .wasm files must be imported directly so wrangler can bundle them.

Together they cover all 16 input/output format combinations: any of AVIF, JPG, PNG, WebP to any of AVIF, JPG, PNG, WebP.

Memory Constraints

The 128MB per-isolate limit is the biggest engineering challenge. A compressed image file can decompress to many times its size in raw RGBA pixels. A 10MB PNG screenshot (10:1 compression ratio) becomes ~100MB of decoded pixel data — dangerously close to the limit.

We use a two-gate validation strategy to prevent out-of-memory crashes:

1. File size gate — Reject files larger than 10MB before any processing begins.
2. Pixel dimension gate — Read the image header bytes (PNG IHDR chunk, JPEG SOF marker, WebP VP8 header, AVIF ispe box) to extract dimensions without decoding the full image. Reject if width × height exceeds 10 megapixels.

This handles both "big file" and "small file with huge dimensions" edge cases. The memory budget breaks down roughly as:

The ImageData Polyfill

The workerd runtime has no Canvas or DOM APIs. The browser's ImageData constructor — which jSquash depends on — simply doesn't exist. We polyfill it at the top of our conversion module:

if (typeof globalThis.ImageData === "undefined") {
  globalThis.ImageData = class ImageData {
    constructor(dataOrWidth, widthOrHeight, height) {
      if (dataOrWidth instanceof Uint8ClampedArray) {
        this.data = dataOrWidth;
        this.width = widthOrHeight;
        this.height = height;
      } else {
        this.width = dataOrWidth;
        this.height = widthOrHeight;
        this.data = new Uint8ClampedArray(
          this.width * this.height * 4
        );
      }
    }
  };
}

This provides just enough of the ImageData interface for jSquash's AVIF codec to work — storing pixel data as a flat Uint8ClampedArray with width and height metadata.

Conversion Pipeline

The conversion routes through four codec paths depending on the input and output formats:

• Non-AVIF → Non-AVIF (e.g., JPG → WebP) — Photon decodes and Photon encodes. The simplest path.
• Non-AVIF → AVIF (e.g., PNG → AVIF) — Photon decodes to a PhotonImage, we extract raw RGBA pixels, wrap them in an ImageData object, and pass to jSquash's AVIF encoder.
• AVIF → Non-AVIF (e.g., AVIF → JPG) — jSquash decodes AVIF to ImageData, we construct a new PhotonImage from the RGBA pixel data, and Photon encodes to the target format.
• AVIF → AVIF (re-compress) — jSquash decodes, then jSquash encodes at the requested quality level.

Input format detection uses magic bytes — the first few bytes of the file header — rather than trusting the provided MIME type. This handles cases where files have wrong extensions or content types.

Memory Management

WASM memory in Cloudflare Workers requires careful management. Workers reuse isolates across requests — leaked WASM memory accumulates until an OOM crash (Error 1102). Every PhotonImage instance must be freed in a finally block:

const image = PhotonImage.new_from_byteslice(
  new Uint8Array(inputBytes)
);
try {
  // ... decode, transform, encode
  return encodedBytes;
} finally {
  image.free();
}

This pattern ensures WASM linear memory is released even if the conversion throws an error. Without it, a Worker handling hundreds of requests would eventually run out of memory and crash.

Performance

Most conversions complete well within the 30-second CPU time budget that Workers Unbound provides. Typical timings for a 2MB input image:

AVIF encoding is the slowest operation because the AV1 codec is computationally intensive. For latency-sensitive applications, converting to WebP instead of AVIF can cut response times in half.