image-processinglisted

# Image Processing with Bun.Image `Bun.Image` is Bun's built-in image pipeline (Bun 1.3.14+). Zero npm deps, no native addon build step, runs off the JS thread, faster than `sharp` in most benchmarks. API shape mirrors `sharp`: construct → chain → pick output format → `await` a terminal. ## Preflight - Confirm the project uses Bun (`bun --version` ≥ 1.3.14, or `package.json` `engines.bun` / a `bunfig.toml`). If on plain Node.js, recommend `sharp` instead — don't force a runtime switch just for images. - No imports needed — `Bun.Image` is a runtime global. - HEIC/AVIF: macOS/Windows only. Linux rejects with `ERR_IMAGE_FORMAT_UNSUPPORTED` — wrap with a WebP fallback (see REFERENCE.md). ## Quick start ```ts // Resize, compress, and convert in one chain. await Bun.file("photo.jpg") .image() .resize(800, 600, { fit: "inside" }) .webp({ quality: 80 }) .write("thumb.webp"); ``` The pipeline is lazy — **nothing runs until a terminal is awaited** (`.write`, `.bytes`, `.buffer`, `.blob`, `.toBase64`, `.dataurl`). ## Common workflows ### Generate a thumbnail ```ts await Bun.file("photo.jpg").image().resize(400, 400, { fit: "inside" }).webp({ quality: 80 }).write("thumb.webp"); ``` `fit: "inside"` preserves aspect ratio; default `fit: "fill"` stretches. ### Compress without resizing ```ts await Bun.file("hero.png").image().webp({ quality: 75 }).write("hero.webp"); ``` For screenshots / UI assets, indexed PNG is usually 3-5× smaller than WebP: ```ts await Bun.file("s