Getting Started

Install

pnpm add imagemin-rs

imagemin-rs requires Node.js 22.13 or newer. Native packages are provided for supported macOS, Linux, and Windows targets. Keep optional dependencies enabled: they carry the native binding and codec executables for the current platform.

The stable package is published under npm's latest tag. Use an explicit version or prerelease tag only when intentionally testing a candidate.

AVIF is an explicit opt-in for the initial stable release. Install the pinned optional peer only in projects that call avif():

pnpm add sharp@0.35.3

Importing imagemin-rs and using every other plugin does not install or load Sharp. Convertible AVIF input reports a stable, actionable error if the peer is absent.

Optimize a buffer

import imagemin, { oxipng } from "imagemin-rs";

const output = await imagemin.buffer(input, {
  plugins: [
    oxipng({
      optimizationLevel: 3,
      strip: "safe",
    }),
  ],
});

Process files concurrently

const controller = new AbortController();

const files = await imagemin(["images/**/*.{png,jpg,svg}"], {
  concurrency: 4,
  destination: "dist/images",
  plugins: [oxipng()],
  signal: controller.signal,
});

// controller.abort();

The file API processes up to four files at once by default, lowers that limit on smaller machines, and preserves deterministic result order. Built-in sidecars terminate their child process on cancellation; completed destination files are not rolled back.

Inspect optimization statistics

import { optimize, oxipng } from "imagemin-rs";

const result = await optimize(input, {
  plugins: [oxipng()],
});

console.log({
  format: result.format,
  inputBytes: result.inputBytes,
  outputBytes: result.outputBytes,
  steps: result.steps,
});

Compose existing imagemin plugins

Function plugins can be inserted directly:

const customPlugin = async (input: Uint8Array) => {
  return new Uint8Array(input);
};

const output = await imagemin.buffer(input, {
  plugins: [oxipng(), customPlugin],
});

Plugins run strictly in array order. Adjacent native plugins may be fused internally, but execution is never reordered across a JavaScript plugin.

Choose svgo() for full imagemin-svgo configuration compatibility or svgm() for bounded worker-pool execution. For PNG and JPEG, choose between lossless and lossy adapters according to the codec guides. webp() converts supported static images by default; the opt-in avif() path does the same after Sharp is installed. Both update destination extensions based on output magic.

You can also try common browser-supported formats locally in the Playground. Uploaded files never leave the browser.

Run in a browser or Web Worker

Use the separate memory-only WASM package when Node.js native bindings and file APIs are unavailable:

pnpm add @imagemin-rs/wasm

import { initWasm, optimize, oxipng } from "@imagemin-rs/wasm";

await initWasm();

const result = await optimize(input, {
  plugins: [oxipng({ optimizationLevel: 3 })],
});

The browser package supports giflossless, oxipng, optipng, and svgm. It does not include paths, globs, N-API, or executable sidecars. See the Browser and Web Worker Guide for a runnable application, file downloads, hard cancellation, and deployment. The Browser WASM API is the complete runtime reference.

Migrating an existing project? Continue with Migrating from imagemin. For native package, sidecar, or deployment failures, see Troubleshooting.