Configure Image Compression to WebP

About the compression feature

What is it? Compression automatically converts JPG and PNG images to WebP format when delivering over the CDN.

WebP is a modern image format with advanced compression. It reduces file size with minimal quality loss.

Format	File Size	Notes
PNG	1860 KB	Original
JPG	169 KB	Quality 90%
WebP	132 KB	Lossy (quality 93 cap)

Enable compression

Compression is included in the Image Stack service. Configure via environment variables or query parameters.

Via environment variables

CONVERT_TO_WEBP=true   # Recommended

Note:

WebP: Uses libwebp for lossy encoding up to quality 93 (higher values are clamped and logged). When PNG_LOSSLESS=true, PNG inputs still take the pure-Rust lossless path to guarantee memory safety.

Via query parameters

image.jpg?fmt=webp

Values: webp

Browser detection

Image Optimizer detects browser support via Accept header. Modern browsers receive WebP. Old browsers get original format.

Usage examples

<!-- Automatic WebP conversion -->
<img src="photo.jpg" alt="Photo" />

<!-- Force WebP -->
<img src="photo.jpg?fmt=webp" alt="Photo" />

<!-- Resize + WebP -->
<img src="photo.jpg?width=800&fmt=webp" alt="Photo" />

<!-- Crop + WebP + Quality -->
<img src="photo.jpg?crop=16:9&fmt=webp&quality=80" alt="Photo" />

Quality parameter

Quality works with WebP (with limits).

Format	Quality Support	Notes
WebP	✅ Supported (1‑93)	Values `>93` are clamped to 93 to prevent WASI OOMs. PNG sources follow lossless path when `PNG_LOSSLESS=true`.
JPEG	✅ Supported	During re-encoding
PNG (no conversion)	❌ Ignored	Always lossless, quality ignored
PNG→WebP	⚠️ Conditional	Ignored if `PNG_LOSSLESS=true`, applied if `PNG_LOSSLESS=false`

Check HTTP headers

curl -I -H "Accept: image/webp,*/*" https://your-cdn.com/image.jpg?fmt=webp

Expected headers:

Content-Type: image/webp
X-Img-Operations: conversion
Vary: Accept

Limitations

WebP lossy limits under WASI

Libwebp lossy encoding is supported but memory/time spikes above quality 93 can crash the WASI module.
Image Optimizer automatically clamps quality to 93 and logs a warning when a higher value is requested.
PNG sources remain lossless when PNG_LOSSLESS=true (pure-Rust encoder), so quality is ignored in that specific case.

See limitations.md for details.

Troubleshooting

Compression not applied: Verify environment variables, check Accept header Quality over 93: Automatically clamped to 93 for WebP. Check logs for warnings.

Recommended configuration

CONVERT_TO_WEBP=true
QUALITY_PRESET=high
PNG_LOSSLESS=true