WebP Conversion

Free — GPL coresize Splanned, not built

Generated from docs/plan/core/webp-conversion/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

WebP Conversion automatically encodes uploaded and optimized images in modern WebP format (90% smaller than JPEG) while maintaining JPEG fallback for older browsers. Storefront serves WebP to capable browsers, JPEG to others. This is core GPL functionality: infrastructure, honest format conversion, no per-country obligation.

The problem

Merchants’ images load slowly because browsers don’t get modern formats. Checkout abandonment climbs when images take 3 seconds to load. WebP cuts image size 50–90% vs JPEG, dramatically improving page speed and checkout performance.

What it does

• Auto-encode as WebP: after compression, encode to WebP format at quality 80-85
• Format detection: identify JPEG/PNG, encode to WebP, store both
• Browser detection: storefront detects Accept: image/webp header, serves WebP or JPEG accordingly
• Fallback: older browsers (IE, old Safari) served JPEG without error
• AVIF support: experimental AVIF encoding (70% smaller than WebP) for cutting-edge browsers, with WebP fallback
• Batch encoding: if merchant uploads 100 images, encode all in parallel
• Metadata stripping: WebP removes EXIF metadata (same as JPEG optimization)

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Format negotiation per device type (mobile gets more aggressive compression) — scope is single quality for all; device-specific is storefront responsibility
• Animated WebP (MP4 → animated WebP) — scope is static images only; video is separate

Data model

Extend asset storage: store variant formats in metadata = {jpeg: {…}, webp: {…}, avif: {…}}. No schema migration.

API

• GET /api/assets/:id/:variant — returns best format (WebP, AVIF, JPEG) based on Accept header

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Asset info shows file size comparison: ‘Original JPEG 800 KB → WebP 160 KB (80% smaller)’.

The seam — why this is core

Core owns: WebP encoding algorithm, format detection, browser Accept-header negotiation. No paid pack owns this; it’s infrastructure.

Core owns the interface + honest format converter; WebP is infrastructure, not a per-country obligation or credential.

Dependencies

• image-optimization (post-compression, before WebP encode)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• JPEG uploaded, encoded to WebP at 80% quality
• WebP file size 80% smaller than JPEG
• Browser with Accept: image/webp header served WebP format
• Older browser without WebP support served JPEG fallback
• AVIF encoding produces smaller file; modern browsers served AVIF first, fallback to WebP, fallback to JPEG

Risks

WebP encoding too aggressive (quality 70) looks pixelated; quality threshold must be tested. AVIF not widely supported in 2026; premature optimization. Browser detection via Accept header breaks if CDN strips headers; must validate Accept header present. JPEG fallback missing breaks older browsers.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.