Registry / http-networking / client-compress

client-compress

library2.2.2jsnpmunverified

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.

http-networking data

npm install client-compress

github ↗package ↗

INSTALL

IMPORT

SIG · CLIENT-COMPRESS

client-compress

http-networkingjavascriptv2.2.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Compress

✓ import Compress from 'client-compress'

✗ const { Compress } = require('client-compress')

Default export only. In ESM, default import works; in CJS, require the module itself (not destructured).

Compress.blobToBase64

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

✗ import { blobToBase64 } from 'client-compress'

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

Compress.loadImageElement

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

✗ import { loadImageElement } from 'client-compress'

Static method on the default export.

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); }); });

Debug

Known issues

breakingV1 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.

affects: >=2.0.0

breakingIn 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.

affects: >=2.0.0

gotchaPNG 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.

affects: all

gotchaGIF 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.

affects: all

gotchaLibrary 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.

affects: all

deprecatedUsing 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.

affects: >=2.0.0

Errors

Common errors & fixes

Uncaught TypeError: Compress is not a constructor

Using named import instead of default import.

fix

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

Cannot find module 'client-compress'

Package not installed or incorrect import path.

fix

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

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

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.

Upgrade

Version history

2.2.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

15 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/davejm/client-compress ↗

packagehttps://www.npmjs.com/package/client-compress ↗