imagemagick-nodejs

⚠️ Notice — This package is currently in beta. APIs may change before the stable release. Please report any issues you encounter on GitHub.

ImageMagick Node.js

A comprehensive, type-safe Node.js wrapper for ImageMagick CLI

Features • Installation • Quick Start • API Reference • Error Handling • Contributing

✨ Features

• 📥 Zero Configuration — Bundled ImageMagick binaries, automatically downloaded on install
• 🔒 Full TypeScript Support — Comprehensive type definitions and type-safe APIs
• ⚡ Dual Module Support — ESM and CommonJS compatibility via tsup
• 🎨 High-Level Fluent API — Chainable methods for intuitive image processing
• 🔧 Low-Level Command Wrappers — Direct access to all ImageMagick tools
• 📦 Batch Processing — Process multiple images with built-in progress tracking
• 🌊 Stream Support — Efficient memory usage with streaming operations
• 🌍 Cross-Platform — Windows, macOS, and Linux (glibc & musl)

📦 Installation

npm install imagemagick-nodejs

That's it! ImageMagick binaries are automatically downloaded during installation.

Supported Platforms

Platform	Architectures	Notes
Windows	x64, x86	Portable static build
macOS	arm64, x64	Bundled with dylibs
Linux	amd64, arm64	glibc and musl (Alpine) variants

Using System ImageMagick

To skip the bundled binary and use your system's ImageMagick instead:

IMAGEMAGICK_SKIP_DOWNLOAD=1 npm install imagemagick-nodejs

🚀 Quick Start

import { imageMagick, identify, convert } from 'imagemagick-nodejs';

// High-level fluent API
await imageMagick('input.jpg').resize(800, 600).quality(85).blur(2).toFile('output.webp');

// Get image information
const info = await identify('image.jpg');
console.log(`${info.width}x${info.height} ${info.format}`);

// Low-level command builder
await convert('input.png')
  .resize(1200)
  .sharpen({ sigma: 1.5 })
  .quality(90)
  .strip()
  .output('output.jpg')
  .run();

📚 API Reference

High-Level Fluent API

import { imageMagick } from 'imagemagick-nodejs';

const image = imageMagick('input.jpg');

// Chain operations
await image
  .resize(800, 600, { fit: 'cover' })
  .crop(800, 600)
  .rotate(45, 'white')
  .blur(3)
  .sharpen(1)
  .quality(85)
  .strip()
  .toFile('output.jpg');

// Output options
await image.toFile('output.jpg'); // Write to file
const buffer = await image.toBuffer(); // Get as Buffer
const stream = await image.toStream(); // Get as stream

Command Wrappers

Convert

import { convert, runConvert, convertImage } from 'imagemagick-nodejs';

// Builder pattern
const builder = convert('input.jpg').resize(800, 600).quality(85).output('output.webp');

await runConvert(builder);

// Simple conversion
await convertImage('input.jpg', 'output.webp', {
  resize: { width: 800 },
  quality: 85,
  strip: true,
});

Identify

import { identify, getDimensions, getFormat } from 'imagemagick-nodejs';

// Full image info
const info = await identify('image.jpg');
console.log(info.format); // 'JPEG'
console.log(info.width); // 1920
console.log(info.height); // 1080
console.log(info.depth); // 8
console.log(info.colorspace); // 'sRGB'

// Quick helpers
const dims = await getDimensions('image.jpg');
const format = await getFormat('image.jpg');

Mogrify (Batch In-Place)

import { mogrify, batchResize, batchOptimize } from 'imagemagick-nodejs';

// Batch resize all JPGs in place
await batchResize('*.jpg', 800);

// Batch optimize for web
await batchOptimize('images/*.png');

Composite

import { composite, overlayImage, addWatermark } from 'imagemagick-nodejs';

// Add watermark
await addWatermark('watermark.png', 'photo.jpg', 'output.jpg', {
  gravity: 'SouthEast',
  opacity: 50,
});

// Blend images
await blendImages('image1.jpg', 'image2.jpg', 'blended.jpg', 50);

Montage

import { createContactSheet, createThumbnailGallery } from 'imagemagick-nodejs';

// Create contact sheet
await createContactSheet(['img1.jpg', 'img2.jpg', 'img3.jpg'], 'sheet.jpg', {
  columns: 3,
  tileSize: 200,
  label: true,
});

Compare

import { compareImages, areIdentical, getSSIM } from 'imagemagick-nodejs';

// Check if identical
const identical = await areIdentical('img1.jpg', 'img2.jpg');

// Get similarity score
const ssim = await getSSIM('img1.jpg', 'img2.jpg');

// Create diff image
await createDiffImage('img1.jpg', 'img2.jpg', 'diff.png');

Animate

import { createGif, createWebP, extractFrames } from 'imagemagick-nodejs';

// Create animated GIF
await createGif(['frame1.png', 'frame2.png', 'frame3.png'], 'animation.gif', {
  delay: 50,
  loop: 0,
});

// Extract frames from GIF
await extractFrames('animation.gif', 'frame-%03d.png');

Batch Processing

import { processBatch, findImages, batchOptimizeFiles } from 'imagemagick-nodejs';

// Find all images
const images = await findImages('./photos', {
  extensions: ['.jpg', '.png'],
  recursive: true,
});

// Process with progress tracking
await processBatch(
  images,
  (file) => ['convert', file, '-resize', '800x600', `output/${path.basename(file)}`],
  {
    parallel: 4,
    onProgress: ({ current, percentage }) => {
      console.log(`${percentage}% - ${current}`);
    },
  }
);

Utilities

import { isFormatSupported, getMimeType, detectFormat, extractPalette } from 'imagemagick-nodejs';

// Check format support
const supported = await isFormatSupported('webp');

// Get MIME type
const mime = getMimeType('png'); // 'image/png'

// Detect actual format (from content)
const format = await detectFormat('unknown-file');

// Extract color palette
const colors = await extractPalette('image.jpg', 8);

Binary Management

import {
  findBinary,
  setBinaryPath,
  addBinarySearchPath,
  getVersion,
  isAvailable,
  getSupportedFormats,
} from 'imagemagick-nodejs';

// Check availability
if (await isAvailable()) {
  const version = await getVersion();
  console.log(`ImageMagick ${version.version}`);
}

// Set explicit binary path (highest priority)
setBinaryPath('/custom/path/to/magick');

// Add additional search paths (checked after bundled binary)
addBinarySearchPath('/opt/imagemagick/bin/magick');

// List supported formats
const formats = await getSupportedFormats();

Binary Search Order

• Custom path set via setBinaryPath()
• Bundled binary in bin/ (downloaded during install)
• System PATH
• Common installation paths + paths added via addBinarySearchPath()

🛠️ Error Handling

import { ImageMagickError, BinaryNotFoundError, ExecutionError } from 'imagemagick-nodejs';

try {
  await convertImage('input.jpg', 'output.webp');
} catch (error) {
  if (error instanceof BinaryNotFoundError) {
    console.error('ImageMagick not found. Please install it.');
  } else if (error instanceof ExecutionError) {
    console.error(`Command failed: ${error.stderr}`);
  }
}

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details on:

• Development setup and workflow
• Coding standards and conventions
• Testing guidelines
• Pull request process

🙏 Acknowledgments

Built on top of ImageMagick — a powerful suite of image manipulation tools.