Quick Start

Learn the basics of bun-image-turbo in 5 minutes.

Basic Usage

import { metadata, resize, toWebp, transform } from 'bun-image-turbo';

// Read an image file
const input = await Bun.file('photo.jpg').arrayBuffer();
const buffer = Buffer.from(input);

Get Image Metadata

Extract image information without decoding the full image:

const info = await metadata(buffer);

console.log(info);
// {
//   width: 1920,
//   height: 1080,
//   format: 'jpeg',
//   channels: 3,
//   hasAlpha: false
// }

Resize Images

Resize with automatic aspect ratio preservation:

// Resize by width (height calculated automatically)
const resized = await resize(buffer, { width: 800 });

// Resize by height
const resized = await resize(buffer, { height: 600 });

// Resize to exact dimensions
const resized = await resize(buffer, {
  width: 800,
  height: 600,
  fit: 'Cover'  // crop to fill (PascalCase)
});

Convert Formats

Convert between image formats:

import { toJpeg, toPng, toWebp } from 'bun-image-turbo';

// Convert to JPEG
const jpeg = await toJpeg(buffer, { quality: 85 });

// Convert to PNG
const png = await toPng(buffer, { compression: 6 });

// Convert to WebP (smaller file size)
const webp = await toWebp(buffer, { quality: 80 });

// Lossless WebP
const lossless = await toWebp(buffer, { lossless: true });

Apply Transformations

Use transform() for multiple operations in one call:

const result = await transform(buffer, {
  // Resize (enum values are PascalCase)
  resize: { width: 800, height: 600, fit: 'Cover' },

  // Rotate (90, 180, or 270)
  rotate: 90,

  // Flip
  flipH: true,  // horizontal
  flipV: false, // vertical

  // Adjustments
  grayscale: true,
  brightness: 10,   // -100 to 100
  contrast: 5,      // -100 to 100
  blur: 2,          // 0 to 100
  sharpen: 10,      // 0 to 100

  // Output format (PascalCase: 'Jpeg', 'Png', 'WebP', 'Gif', 'Bmp')
  output: {
    format: 'WebP',
    webp: { quality: 80 }
  }
});

await Bun.write('output.webp', result);

Generate Blurhash

Create compact image placeholders:

import { blurhash } from 'bun-image-turbo';

const { hash, width, height } = await blurhash(buffer, 4, 3);
console.log(hash); // "LEHV6nWB2yk8pyo0adR*.7kCMdnj"

HEIC Conversion (macOS ARM64)

Convert iPhone photos:

import { toJpeg, metadata } from 'bun-image-turbo';

// Read HEIC file
const heic = await Bun.file('IMG_1234.HEIC').arrayBuffer();
const buffer = Buffer.from(heic);

// Get metadata
const info = await metadata(buffer);
console.log(info.format); // 'heic'

// Convert to JPEG
const jpeg = await toJpeg(buffer, { quality: 90 });
await Bun.write('photo.jpg', jpeg);

Sync API

All functions have synchronous versions:

import {
  metadataSync,
  resizeSync,
  toJpegSync,
  transformSync
} from 'bun-image-turbo';

// Synchronous operations (blocks event loop)
const info = metadataSync(buffer);
const resized = resizeSync(buffer, { width: 400 });
const jpeg = toJpegSync(buffer, { quality: 80 });

WARNING

Sync functions block the event loop. Use async versions for better performance in servers.

Next Steps

• Image Formats - Supported formats and options
• Resizing - Advanced resize options
• Transformations - All transformation options
• API Reference - Complete API documentation