ee-cdn-cli can convert images to WebP or AVIF and scale down oversized photos

If your site generator has no image step, your site probably ships photos straight from the camera, and every visitor downloads them at full size. From 0.4.0, ee-cdn-cli can take care of that while it packages your site: it can convert your JPEG and PNG images to WebP or AVIF, and scale down images wider than a width you choose. Neither happens unless you ask for it.

npx @evolving-edge/ee-cdn-cli --domain www.example.com --project proj_… --images webp --image-max-width 2560

Converting images

• --images webp or --images avif converts your site’s JPEG and PNG images and rewrites every reference to them in your pages, so they point to the new files.
• --image-host names other hosts your site is served from, so references that use those hosts’ full addresses are rewritten too.
• --image-report writes a JSON report of what was converted, what was left alone and why.
• --images off turns conversion off for one deploy, even if your ee.jsonc turns it on.

Scaling down wide images

• --image-max-width <px> scales every JPEG and PNG wider than that many pixels down to that width, keeping its proportions. The width can be any whole number from 1 to 16383.
• Names and formats stay the same, so nothing in your pages needs rewriting. JPEGs are saved at quality 85 and PNGs without loss.
• An image is never made larger. If the scaled copy wouldn’t be smaller, the original is kept.
• It runs before conversion, so with both options on, it’s the scaled-down images that get converted. The report lists each scaled image’s size before and after.

In the Astro integration

The same options are deploy.images, deploy.imageHosts, deploy.imageReport and deploy.imageMaxWidth. A width that isn’t valid stops the build at setup, before anything is built.

Your files are left alone

Both options change only the files that are deployed. Your build output and your repository are never touched.

Limits

• Some images are left alone: GIF and SVG files, animated images, CMYK images, images with a colour profile other than sRGB, 16-bit images and images over 40 megapixels.
• Width hints in your pages still state the original width. Scaling changes no text, so a srcset width descriptor such as photo.jpg 4000w, or og:image:width, still names the old size. Browsers lay pages out by your CSS or the width and height attributes, so most pages look the same, but a page that relies only on a srcset descriptor for an image’s size shows it smaller.
• Scaling alone doesn’t lift the 100 MiB limit on a site.
• Portal deploys don’t convert or scale images yet. These options work only with ee-cdn-cli.

Builder checks

Image options need a recent builder: conversion is in builders published since 23 October, and --image-max-width in builders published since 24 October. Before packaging, the CLI checks that the builder it is about to use has the option you asked for, and if it doesn’t, it stops and tells you what to do. A builder version pinned in your lockfile is kept as it is. A cached latest builder is replaced when a newer one is published.

What you need to do

Nothing, unless you want to use these options. To try them, update ee-cdn-cli to 0.4.0 and add --images or --image-max-width to your deploy command. If you pin an older builder version, pin a newer one or remove the pin.