Image - Bun

Documentation IndexFetch the complete documentation index at: https://bun.com/docs/llms.txtUse this file to discover all available pages before exploring further.Bun.Image is a chainable image pipeline for decoding, resizing, rotating, and re-encoding JPEG, PNG, WebP, HEIC, and AVIF — built on libjpeg-turbo, spng, libwebp, and SIMD geometry kernels, with zero npm dependencies and no native addon build step.await Bun.file("photo.jpg").image().resize(400, 400, { fit: "inside" }).webp({ quality: 80 }).write("thumb.webp");

The API is shaped after Sharp: construct from an input, chain transforms, pick an output format, then await a terminal method. Nothing runs until the terminal is awaited, and the work executes off the JavaScript thread.Input The constructor accepts a path, bytes, or a Blob — including Bun.file() and Bun.s3(). Blob#image() is shorthand for new Bun.Image(blob):new Bun.Image("./photo.jpg"); // file path new Bun.Image(buffer); // Buffer / ArrayBuffer / TypedArray new Bun.Image(Bun.file("photo.jpg")); // BunFile (read lazily, off-thread) Bun.file("photo.jpg").image(); // same as above Bun.s3("bucket/photo.jpg").image(); // S3File

The format is sniffed from the bytes — extensions and Content-Type are ignored. Path strings are filesystem paths. Don’t pass user-controlled strings directly to the constructor — that’s an arbitrary-file-read primitive. Read untrusted input into a Buffer (e.g. via fetch/Bun.file with your own validation) and pass the bytes. When passing a TypedArray/ArrayBuffer, don’t mutate it while a terminal is pending — decode runs off-thread and borrows the bytes. SharedArrayBuffer and resizable buffers are refused; use buf.slice() to pass a fixed view. A second options argument guards against decompression bombs and controls EXIF handling:new Bun.Image(input, { // Reject if width*height > this. Checked after reading the header, // before allocating the pixel buffer.

Default matches Sharp (~268 MP). maxPixels: 4096 * 4096, // Apply JPEG EXIF Orientation before any other op. Default: true. autoOrient: true, });

Read width, height, and format without decoding pixel data:const { width, height, format } = await new Bun.Image(input).metadata(); // => { width: 1920, height: 1080, format: "jpeg" }

Resize img.resize(800); // width 800, keep aspect ratio img.resize(800, 600); // exactly 800×600 (stretch) img.resize(800, 600, { fit: "inside" }); // fit within 800×600 img.resize(800, 600, { withoutEnlargement: true }); // never upscale img.resize(800, 600, { filter: "mitchell" });

fitBehavior"fill" (default)Stretch to exactly width × height"inside"Preserve aspect ratio; result fits within the box filter selects the resampling kernel. The default "lanczos3" is the right choice for photographs.FilterUse when"lanczos3" (default)General-purpose, sharpest for photos"lanczos2"Slightly softer, fewer ringing artifacts"mitchell"Smooth gradients; the classic bicubic compromise"cubic"Catmull-Rom — sharper than Mitchell, can ring"mks2013" / "mks2021"”Magic Kernel Sharp”; used by Facebook/Instagram"bilinear" / "linear"Fast, soft"box"Area-average; good for large integer downscales"nearest"Pixel art / hard edges When the source is a JPEG and the target is at most half the source size, decode skips straight to the nearest M/8 IDCT scale, so generating a thumbnail from a 24 MP photo never materializes the full-resolution buffer.

Rotate · flip img.rotate(90); // 90° clockwise (multiples of 90 only) img.flip(); // mirror vertically (about the x-axis) img.flop(); // mirror horizontally (about the y-axis)

Modulate img.modulate({ brightness: 1.2, // 1 = unchanged saturation: 0, // 0 = greyscale, 1 = unchanged, >1 = boost });

Output formats Calling a format method sets the encode target; without one, the source format is reused.img.jpeg({ quality: 85 }); // 1–100, default 80 img.png({ compressionLevel: 6 }); // zlib level 0–9 img.png({ palette: true, colors: 64, dither: true }); // indexed PNG img.webp({ quality: 80 }); img.webp({ lossless: true }); img.heic({ quality: 80 }); // macOS / Windows only img.avif({ quality: 60 }); // macOS / Windows only

palette: true quantizes to a ≤256-color palette and emits an indexed (color-type 3) PNG, optionally with Floyd–Steinberg dither. This is typically 3–5× smaller than truecolor for screenshots and UI assets.Terminals A pipeline does no work until one of these is awaited:await img.bytes(); // Uint8Array await img.buffer(); // Buffer await img.blob(); // Blob with .type set to the output MIME await img.toBase64(); // string await img.dataurl(); // "data:image/png;base64,…" await img.write("out.webp"); // number (bytes written) await img.write(Bun.s3("bucket/out.webp"));

.write() accepts the same destinations as Bun.write — a path string, Bun.file(), Bun.s3(), or an fd.

If you didn’t chain a format method and the destination is a path string, the extension picks one (.jpg/.png/.webp/.heic/.avif).Placeholders For a low-quality placeholder to inline in HTML before the real image loads, .placeholder() returns a ThumbHash-rendered ≤32px blur as a data: URL — ~400–700 bytes, no client-side decoder needed:const lqip = await Bun.file("hero.jpg").image().placeholder(); // <img src={lqip} … /> — then swap to the real URL on load.

For coarse-to-fine rendering of the image itself, encode a progressive JPEG:img.jpeg({ progressive: true });

After the first terminal resolves, img.width and img.height reflect the output dimensions (they’re -1 before).Bun.serve integration A Bun.Image pipeline is a valid Response body and sets Content-Type automatically. To keep the encode off the JS thread in a server handler, await a terminal first:Bun.serve({ routes: { "/avatar/:id": async req => { // Validate before touching the filesystem (see the Input note above). if (!/^[a-z0-9]+$/.test(req.params.id)) return new Response(null, { status: 400 }); const out = await Bun.file(`avatars/${req.params.id}.png`).image().resize(128, 128).webp().blob(); return new Response(out); }, }, });

Passing the pipeline directly (new Response(img)) also works, but currently runs the encode synchronously during body init.Clipboard const img = Bun.Image.fromClipboard(); if (img) { const png = await img.resize(800, 800, { fit: "inside" }).png().bytes(); }

fromClipboard() reads PNG, TIFF, HEIC, JPEG, WebP, GIF, or BMP from the system pasteboard on macOS and Windows; the regular decode pipeline takes it from there. Returns null if there’s no image, and always null on Linux — call wl-paste/xclip yourself and pass the bytes to the constructor.

For a passive “image in clipboard, press ⌘V” hint, poll clipboardChangeCount() (a single integer read) and call hasClipboardImage() only when it moves; macOS has no clipboard-change notification, so this is the documented pattern.Platform backends LinuxmacOSWindowsJPEG / PNG / WebPlibjpeg-turbo · spng · libwebpsamesameBMP / GIF (decode)built-inImageIOWICTIFF (decode)❌ImageIOWICResize / rotate / flipHighway SIMDAccelerate vImageHighway SIMDHEIC / AVIF❌ ERR_IMAGE_FORMAT_UNSUPPORTEDImageIO ²WIC ¹Clipboard❌ returns nullNSPasteboardWin32 ¹ Windows requires the HEIF Image Extensions / AV1 Video Extension from the Microsoft Store. ² AVIF encode needs an OS AV1 encoder — Apple Silicon M3+ only. Intel Mac and M1/M2 reject with ERR_IMAGE_FORMAT_UNSUPPORTED; AVIF decode works everywhere ImageIO does (macOS 13+). When a system-backend format isn’t available on the current machine, the terminal rejects with error.code === "ERR_IMAGE_FORMAT_UNSUPPORTED" — branch on that to fall back to a portable format:const out = await img .avif({ quality: 50 }) .bytes() .catch(e => { if (e.code === "ERR_IMAGE_FORMAT_UNSUPPORTED") return img.webp({ quality: 80 }).bytes(); throw e; });

Formats handled by the system backend (TIFF, HEIC, AVIF, clipboard) inherit the OS’s patch level — keep macOS / Windows updated. JPEG, PNG, and WebP go through the same statically-linked codecs on every platform, so encoded output is byte-identical across Linux, macOS, and Windows. To force the portable Highway path for geometry too — e.g. for golden-image tests — set the process-global backend:Bun.Image.backend = "bun"; // default is "system" on macOS/Windows