Bun’s New Image API: A Zero‑Dependency Alternative to Sharp for Node.js

Sharp has long been the go‑to image library for Node.js because it is fast, built on libvips, and can handle tens of megabytes of image data without slowing down. However, its native C++ extension makes deployment painful: each new OS, Docker base image, or serverless environment often requires recompilation, leading to many CI/CD pitfalls.

Bun.Image Arrives

On May 2, the Bun team announced on X that the next Bun release will bundle Bun.Image, a fast multi‑format image processing library with zero external dependencies and out‑of‑the‑box usability.

await Bun.file("photo.jpg")
  .image()
  .resize(1024, 1024, { fit: "inside" })
  .rotate(90)
  .webp({ quality: 85 })
  .write("thumb.webp");

This chain reads a file, creates an image object, resizes, rotates, encodes to WebP, and writes the result in a single fluent flow, mirroring the familiar Bun.file() API.

Format Support

Bun.Image statically links libjpeg‑turbo, libspng and libwebp, so JPEG, PNG and WebP work on every platform without any system libraries.

macOS : HEIC and AVIF are available via ImageIO/CG (HEIC requires macOS 10.13+, AVIF requires 13+).

Windows : HEIC and AVIF are available via WIC (HEIC needs Windows 10 1809+ with the HEIF Image Extensions, AVIF needs the AV1 Video Extension).

Linux : HEIC and AVIF are not supported; attempting to use them throws UnsupportedOnPlatform.

The omission on Linux is a deliberate trade‑off to avoid bundling additional binaries.

Resize and Filter Options

The resize API offers several controls:

img.resize(800);                         // width 800, keep aspect ratio
img.resize(800, 600);                  // force 800×600 (stretch)
img.resize(800, 600, { fit: "inside" }); // fit inside 800×600 box
img.resize(800, 600, { withoutEnlargement: true }); // never upscale
img.resize(800, 600, { filter: "mitchell" }); // choose resampling kernel

The fit parameter can be "fill" (default, stretch to exact dimensions) or "inside" (preserve aspect ratio and fit within the target box).

Filter choices control the resampling algorithm: "lanczos3" (default) – best overall sharpness for photos. "lanczos2" – slightly softer, fewer ringing artifacts. "mitchell" – smooth compromise between sharpness and ringing. "cubic" – Catmull‑Rom, sharper than Mitchell but can ring. "mks2013" / "mks2021" – “Magic Kernel Sharp”, used by Facebook/Instagram. "bilinear" / "linear" – fast and gentle. "box" – area‑average, ideal for integer‑factor downscaling. "nearest" – pixel‑art / hard‑edge scaling.

Both ARM64 and x64 builds include SIMD acceleration, and when the source is a JPEG and the target size is no more than half the original, Bun.Image skips full‑resolution decoding and jumps directly to the nearest M/8 IDCT scaling level, dramatically lowering peak memory usage for large photos.

Integration with Bun.s3

// S3 in, S3 out
await Bun.s3("uploads/raw.heic")
  .image()
  .resize(800)
  .jpeg({ quality: 85 })
  .write(Bun.s3("cdn/out.jpg"));

This pipeline reads an image from S3, resizes it, re‑encodes to JPEG, and writes the result back to S3 without touching the local filesystem or requiring any additional SDK.

Clipboard Reading

// ⌘↑4 → optimized PNG in one line
await Bun.Image.fromClipboard()
  ?.resize(800, 800, { fit: "inside" })
  .png({ palette: true, colors: 64 })
  .write("shot.png");

On macOS and Windows the API returns an image; on Linux, FreeBSD and Android it returns null.

Low‑Quality Placeholder Generation

const thumbnail = await file(process.argv.at(-1)).image().placeholder();
console.log(`<img src=${thumbnail} />`);

The .placeholder() method creates a base64‑encoded low‑quality image placeholder (LQIP) suitable for lazy‑loading patterns.

Community Debate

“As usual, a group says ‘this is bloat, just use the library.’ Image resizing especially benefits from native code, and libraries like Sharp are painful to deploy because you have to build the native part.”

Critics argue that bundling image processing inflates the runtime, while supporters point out that Sharp’s native extension causes deployment headaches across different OSes, glibc versions, CPU architectures, and Node.js versions.

The discussion mirrors the historic split between Node.js (minimal core, ecosystem fills gaps) and Deno (more batteries‑included). Bun leans toward the Deno philosophy, adding built‑in tools such as SQLite, an S3 client, a test framework, a bundler, and now image processing.

Current Limitations

HEIC/AVIF are not supported on Linux, limiting use on servers that process modern mobile photos.

The API is still in the upcoming Bun version and may change before the stable release.

Sharp remains more feature‑complete, offering sharpening, blurring, color‑space conversion, compositing, and other advanced operations not yet exposed by Bun.Image.

Trends to Watch

Bun’s strategy of embedding common capabilities directly into the runtime aims to reduce third‑party dependencies. This puts pressure on the Node.js ecosystem, which may need to reconsider how much functionality should remain external.