client-compress

2.2.2 verified Sat May 09 auth: no javascript

A client-side JavaScript image compression library that uses the Canvas API to compress images in the browser before upload. Current stable version is 2.2.2, released periodically with bug fixes and improvements. Key differentiators: returns Blob objects (not base64) for accurate size tracking, supports EXIF orientation correction for Android/iOS images, offers configurable max dimensions and quality, and provides a clean async/await API. Alternative to compress.js library with better option handling and bug fixes. Does not work in Node.js (browser/Canvas only). Limitations: transforms PNG transparency to black background, and GIFs lose animation.

Common errors

error Uncaught TypeError: Compress is not a constructor ↓

cause Using named import instead of default import.

fix

Change import statement to: import Compress from 'client-compress';

error Cannot find module 'client-compress' ↓

cause Package not installed or incorrect import path.

fix

Run 'npm install client-compress' and ensure import is from 'client-compress' without subpaths.

error Failed to execute 'toBlob' on 'HTMLCanvasElement': Tainted canvases may not be exported. ↓

cause Image loaded from cross-origin without CORS headers.

fix

Ensure the image server sends Access-Control-Allow-Origin header or load images from same origin.

Warnings

breaking V1 returned base64, V2+ returns Blob objects. Code expecting base64 strings will break. ↓

fix Use Blob data directly or call Compress.blobToBase64(photo.data) if you need base64.

breaking In v1, constructor options used 'maxWidth' and 'maxHeight' incorrectly; v2+ fixes this but may change behavior for large images. ↓

fix Re-test compression results and adjust quality/maxDimensions.

gotcha PNG images with transparent backgrounds will have transparency replaced with black in the output JPEG Blob. ↓

fix Use an image editor or alternative library if alpha preservation is required.

gotcha GIF images will lose animation after compression; only the first frame is kept as a static JPEG. ↓

fix Skip compression for animated GIFs, or use a GIF-specific library.

gotcha Library relies on Canvas API and will not work in Node.js or server-side environments. ↓

fix Use server-side alternatives like sharp or image-min.

deprecated Using CommonJS 'require' with bundlers that tree-shake may include unnecessary code; ESM import is recommended. ↓

fix Switch to ESM import syntax if your project supports it.

Install

npm install client-compress

yarn add client-compress

pnpm add client-compress

Imports

Compress
wrong
```
const { Compress } = require('client-compress')
```
correct
```
import Compress from 'client-compress'
```
Default export only. In ESM, default import works; in CJS, require the module itself (not destructured).

Compress.blobToBase64

wrong

import { blobToBase64 } from 'client-compress'

correct

import Compress from 'client-compress'; Compress.blobToBase64(blob)

Static method on the default export, not a named export.

Compress.loadImageElement

wrong

import { loadImageElement } from 'client-compress'

correct

import Compress from 'client-compress'; Compress.loadImageElement(imgEl, url)

Static method on the default export.

Quickstart

Creates a Compress instance with options, compresses an array of image Files, and displays the first result using a Blob URL.

import Compress from 'client-compress';

const options = {
  targetSize: 0.2,      // target size in MB
  quality: 0.75,         // JPEG quality
  maxWidth: 800,
  maxHeight: 600
};

const compress = new Compress(options);

// Assuming 'files' is an array of File/Blob from an <input type="file">
compress.compress(files).then(conversions => {
  const { photo, info } = conversions[0];
  console.log('Compressed size:', photo.size, 'bytes');
  console.log('Original name:', photo.name);
  console.log('Dimensions:', photo.width, 'x', photo.height);
  // Use photo.data (Blob) for upload or display
  const url = URL.createObjectURL(photo.data);
  document.getElementById('preview').src = url;
  // Revoke URL after image loads
  Compress.loadImageElement(document.getElementById('preview'), url).then(() => {
    URL.revokeObjectURL(url);
  });
});