125 online 3 members  + Join RP Base  +
FreeTool

compresso

by iziuqo  ·  version 2026.11.14  ·  updated 2 days ago

No reviews yet

Downloads
0
Reviews
0
Size
3 MB
Code check
Checked
Licence
MIT
Released
Nov 2026

Tiny, zero-dependency image optimizer that runs entirely in the browser. Compress, resize, and convert images on the client side — no server needed.

compresso
Compresso

Compress, resize, and convert images in the browser.
A 3.6 KB, zero-dependency image compressor with HEIC input, parallel Web Worker batching, and a never-bigger-output guarantee — no server needed.

▶ Try the live demo ·
Documentation ·
Compare ·
FAQ ·
Batch & Workers

Why Compresso
  • Smallest in its class — 3.6 KB gzipped, zero required dependencies. Roughly 4–5× smaller than browser-image-compression and pica, and still leaner than compressorjs (see comparison). The core is pure Canvas API — no WASM, no codecs bundled.
  • iPhone HEIC/HEIF input, everywhere. Safari/iOS decode natively; other browsers lazy-load a WASM decoder only the first time a HEIC file appears, so the tiny core stays codec-free for every other format. No other browser compressor handles HEIC.
  • Never returns a bigger file. Lossy output is guaranteed to be no larger than the original — if a format can't beat an already-efficient source, Compresso adapts (quality/resolution) instead of inflating it. No rival makes this guarantee.
  • Real parallel batch compression, off the main thread. compresso.js/pool runs a resilient Web Worker pool — crash and timeout recovery included — for compressing many files at once without blocking the UI. Falls back to the exact same API on the main thread where Workers aren't available, so you never branch on environment yourself (see Batch & Workers).
  • Modern by default — format: 'auto' picks AVIF → WebP → JPEG per browser, promise-based API, first-class TypeScript types, and it's actively maintained.
  • 100% client-side — no server round-trips, no API keys, no upload of user images anywhere. Private by construction.
Install
npm install compresso.js

Or from a CDN:


Or as an ES module, straight from jsDelivr (it rewrites the optional HEIC decoder's import for you):


  import { compress } from 'https://cdn.jsdelivr.net/npm/compresso.js@1/+esm';

Quick Start
import { compress } from 'compresso.js';

const input = document.querySelector('input[type="file"]');

input.addEventListener('change', async (e) => {
  const file = e.target.files[0];

  const result = await compress(file, {
    quality: 0.8,
    maxWidth: 1920,
    format: 'auto', // AVIF / WebP / JPEG — best the browser supports
  });

  console.log(`${result.savings}% smaller`);
  // → "87.3% smaller"

  // Use result.file for upload, result.url for preview
});

Comparison
How Compresso compares to the popular browser-side image libraries:

compresso.js, compressorjs, browser-image-compression, pica

Bundle, min+gzip 1, 3.8 KB, 4.6 KB, 19.6 KB, 15.7 KB
Required dependencies, 0, 2, 1, 2
HEIC / HEIF input, ✅, ❌, ❌, ❌
AVIF output, ✅, ❌, ❌, ❌
Auto best-format, ✅, ❌, ❌, ❌
Never larger than input, ✅, ❌, ❌, ❌
Target max file size, ✅, ❌, ✅, ❌
Non-blocking (Web Worker), ✅ (compresso.js/pool), ❌, ✅, ✅
API style, Promise, Callbacks, Promise, Promise
TypeScript types, ✅, ✅, ✅, ✅
Latest release 2, 2026-08, 2026-04, 2023-03, 2026-06
License, MIT, MIT, MIT, MIT

1 Bundlephobia min+gzip, each package's latest version. 2 npm latest-publish date. Figures verified 2026-08-04 — reproduce with https://bundlephobia.com/api/size?package=.

When not to use Compresso: for server-side/batch processing use sharp; for pixel-level image editing use Jimp; if you only need the highest-quality downscale, pica specializes in that. Compresso is for optimizing user-selected images in the browser before upload.
Target a Maximum File Size
Perfect for systems with strict upload limits:

const result = await compress(file, {
  maxSizeMB: 2,       // never exceeds 2 MB
  format: 'jpeg',
});

Compresso binary-searches for the highest quality that fits within your size constraint.
Batch & Parallel Compression
New in 1.0.0: compresso.js/pool runs many compressions in parallel, off the main thread, via a resilient Web Worker pool — no UI jank on a 50-photo upload.

import { createPool } from 'compresso.js/pool';

const pool = createPool();

const results = await pool.compressMany(fileList, { format: 'auto' }, (e) => {
  console.log(`${e.fileIndex + 1}/${e.totalFiles} — ${Math.round(e.overallProgress * 100)}%`);
});

for (const r of results) {
  if (r.status === 'fulfilled') uploads.push(r.value.file);
}

pool.destroy();

  • Same shape everywhere. createPool() never throws for lack of Worker support (or a CSP that blocks worker construction) — it silently falls back to the exact same API on the main thread. You call it unconditionally; it decides how much parallelism the environment can actually offer.
  • Self-healing. A worker that crashes (OOM, driver fault) or goes silent past a per-job timeout — e.g. iOS backgrounding a tab — is detected and replaced automatically. pool.stats().recoveries tells you if it happened.
  • Never a whole-batch failure. compressMany() results are Promise.allSettled-shaped — one file failing doesn't sink the other 49.

Full API (createPool options, pool.stats(), CSP requirements) is in the package README.
API**compress(source, options?)**
Compresses a single image.

Parameter, Type, Description

source, File \, Blob \, string, Image file, blob, or URL (HEIC/HEIF accepted)
options, CompressOptions, See below
Options
Option, Type, Default, Description

quality, number, 0.8, Output quality, 0–1
maxWidth, number, unbounded †, Maximum output width in px
maxHeight, number, unbounded †, Maximum output height in px
format, string, 'auto', 'jpeg', 'png', 'webp', 'avif', or 'auto'
maxSizeMB, number, source size ‡, Maximum output file size in MB
backgroundColor, string, `

…