wasm-image-optimization

wasm-image-optimization

High-performance image conversion and resizing tool leveraging WebAssembly (Emscripten). Built on the Skia rendering engine, it supports animations (GIF/WebP) and modern formats (AVIF/SVG/ThumbHash).

It provides a lightweight, dependency-free solution for generating high-quality visuals and documents across Node.js, Cloudflare Workers, Deno, and Web Browsers.

Playground

https://node-libraries.github.io/wasm-image-optimization/

Examples

https://github.com/SoraKumo001/wasm-image-optimization-samples

Supported Formats

Format	Input (Decoding)	Output (Encoding)	Notes
PNG	✅	✅
JPEG	✅	✅
WebP	✅	✅	Supports animations
AVIF	✅	✅	Powered by AOM encoder / dav1d decoder
ThumbHash	✅	✅	Returns a compact image placeholder hash
RAW	✅	✅	Returns uncompressed 32-bit RGBA pixel data
GIF	✅	-	Input only (supports animations)
SVG	✅	-	High-fidelity rendering via SkSVGDOM
BMP	✅	-
None	✅	✅	Returns original data with metadata

Installation

pnpm add wasm-image-optimization

CLI Usage

After installation, the wasm-image-optimization command will be available.

# Basic conversion (default is WebP)
wasm-image-optimization input.png

# Specify format and quality
wasm-image-optimization input.jpg -f avif -q 80

# Convert maintaining animation
wasm-image-optimization input.gif -f webp -a

# Specify encoding speed (e.g., for AVIF)
wasm-image-optimization input.png -f avif -s 0

# Resize and save with a different name
wasm-image-optimization input.png -w 800 -h 600 -o resized.webp

Library Usage (TypeScript)

Basic Usage

import { optimizeImage } from 'wasm-image-optimization';


const inputBuffer = ...; // Uint8Array or ArrayBuffer

const result = await optimizeImage({
  image: inputBuffer,
  width: 800,
  height: 600,
  fit: 'contain', // 'contain' | 'cover' | 'fill' (default: 'contain')
  format: 'webp',  // 'none' | 'png' | 'webp' | 'jpeg' | 'avif' | 'raw' | 'thumbhash'
  quality: 85,
  speed: 6,       // 0-10 (encoding speed for AVIF, etc.)
  animation: true // maintain animation if possible
});

Parameters (OptimizeParams)

Parameter	Type	Default	Description
image	Uint8Array ArrayBuffer	Required	The raw binary data of the image to process.
width	number	-	Target width for resizing. If omitted, it's calculated from height to maintain aspect ratio.
height	number	-	Target height for resizing. If omitted, it's calculated from width to maintain aspect ratio.
fit	contain cover fill	'contain'	Resizing strategy. - contain: Fits within bounds (aspect ratio preserved). - cover: Fills bounds (may crop). - fill: Stretches to match bounds exactly.
format	string	'webp'	Output format: 'none', 'png', 'webp', 'jpeg', 'avif', 'raw', 'thumbhash'. Note: If animation: true and the input is animated, this is forced to 'webp'.
quality	number	100	Compression quality (0-100). Applies to WebP, JPEG, and AVIF.
speed	number	6	Encoding speed (0-10). Primarily used for AVIF. Lower is slower but better compression.
animation	boolean	false	If true, preserves animation frames (e.g., GIF/animated WebP source).

Result (OptimizeResult)

Property	Type	Description
data	Uint8Array	The processed image data.
originalWidth	number	Width of the input image.
originalHeight	number	Height of the input image.
originalAnimation	boolean	true if the input image was animated.
originalFormat	string	Format of the input image (e.g., "jpeg", "gif").
width	number	Width of the output image.
height	number	Height of the output image.
animation	boolean	true if the output image is animated.
format	string	Format of the output image.

Logging & Debugging

You can monitor the internal processing and Skia logs.

import { ImageConverter } from "wasm-image-optimization";

const converter = new ImageConverter();

// Set log level: 0 (None), 1 (Error), 2 (Warning), 3 (Info), 4 (Debug)
converter.logLevel = 3;

// Custom log handler
converter.onLog = (level, message) => {
  console.log(`[ImageConverter][${level}] ${message}`);
};

Multi-threading (Workers)

Use Workers for high-throughput processing without blocking the main thread.

import { optimizeImage } from "wasm-image-optimization/workers";

const result = await optimizeImage({
  image: inputBuffer,
  width: 800,
  format: "png",
});

Build

Prerequisites

• Emscripten (emsdk): Ensure the latest version is installed and environment variables are set.
• vcpkg: Used for managing C++ dependencies.

Steps

# Install dependencies
pnpm install

# Configure CMake (using Ninja)
pnpm wasm:configure

# Build Wasm
pnpm wasm:build

Tech Stack

• Core: Skia, libavif (AOM / dav1d), Wuffs, expat
• Runtime: WebAssembly (Emscripten)
• Language: C++20, TypeScript

License

MIT