Examples

Build a command.
Copy it.

Start from a real recipe. The builder writes the CLI, the Node API, and the config file for the same job.

Extras

The example input is public/images/**/*.{jpg,png}. Change the path in the generated code. Report is CLI-only.

generated

            

            

          
Recipes

Jobs people
actually run.

Small commands, complete output. Every recipe can be combined with the cache, report, and manifest options.

Responsive

The web set.

AVIF + WebP at three widths, with a manifest and picture snippets.

shell
pixelpress "assets/**/*.{jpg,png}" -o dist -r \
  --preset web \
  --manifest dist/images.json \
  --picture dist/picture.html --public-path /images
Social

One card. Two formats.

1200×630 cover crop, JPEG + WebP, and a local report to check the crop.

shell
pixelpress og-source.jpg -o social \
  --preset social \
  --report social/report.html
Thumbnails

One size, many files.

A 400px WebP thumbnail tree with hashed filenames for immutable caching.

shell
pixelpress products -o dist/thumbs -r \
  --preset thumb --hash --cache --prune
Budget

Fit 120 KB or fail.

Quality searches down per variant. If quality 1 cannot fit, the file is reported as failed.

shell
pixelpress hero.jpg -o dist \
  -f avif,webp -q avif=70,webp=85 \
  --max-bytes 120kb
Animation

Keep the frames.

WebP output preserves animation. Use it before static AVIF/JPEG fallbacks in <picture>.

shell
pixelpress loop.gif -o dist \
  -f webp -w 320,640 --hash
Watch

Clean while you work.

Cache makes reruns cheap; prune removes retired widths and deleted sources; watch keeps going.

shell
pixelpress public/images -o dist -r \
  --preset web --cache --prune --watch
Ship

Manifest, picture, report.

Everything a template or review needs, from one run.

shell
pixelpress photos -o dist -r \
  --preset web --lqip \
  --manifest dist/images.json \
  --picture dist/picture.html --public-path /images \
  --report dist/report.html
Pipe

No temp files.

One image in, one image out. Logs stay on stderr.

shell
cat photo.jpg \
  | pixelpress - -f webp --width 1200 --stdout \
  > photo.webp
Config

Set it once.

Scaffold a config, edit the paths, and run with no arguments.

shell
pixelpress --init
# edit pixelpress.config.json
pixelpress
API

Build it in Node.

Same options, absolute result paths, explicit failures.

build.js
import { optimize } from 'pixelpress';

const report = await optimize(['public/images'], {
  outDir: 'dist/images',
  preset: 'web',
  cache: true,
  prune: true,
});

if (report.failed.length) process.exitCode = 1;
Output tree

Predictable
by default.

Mirror the source tree, append width and hash suffixes, and keep format subdirectories out of the way. Every path in a manifest is relative to the directory you ran from.

dist/
dist/
  images/
    hero-480.avif
    hero-480.webp
    hero-960.avif
    hero-960.webp
    team/
      ana-480.avif
      ana-480.webp
  images.json
  picture.html
  report.html

Ready for your tree?

Copy a recipe, change the paths, and run it. The CLI and API are waiting.