{"id":27651,"library":"client-compress","title":"client-compress","description":"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.","status":"active","version":"2.2.2","language":"javascript","source_language":"en","source_url":"https://github.com/davejm/client-compress","tags":["javascript","image","compression","base64"],"install":[{"cmd":"npm install client-compress","lang":"bash","label":"npm"},{"cmd":"yarn add client-compress","lang":"bash","label":"yarn"},{"cmd":"pnpm add client-compress","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Default export only. In ESM, default import works; in CJS, require the module itself (not destructured).","wrong":"const { Compress } = require('client-compress')","symbol":"Compress","correct":"import Compress from 'client-compress'"},{"note":"Static method on the default export, not a named export.","wrong":"import { blobToBase64 } from 'client-compress'","symbol":"Compress.blobToBase64","correct":"import Compress from 'client-compress'; Compress.blobToBase64(blob)"},{"note":"Static method on the default export.","wrong":"import { loadImageElement } from 'client-compress'","symbol":"Compress.loadImageElement","correct":"import Compress from 'client-compress'; Compress.loadImageElement(imgEl, url)"}],"quickstart":{"code":"import Compress from 'client-compress';\n\nconst options = {\n  targetSize: 0.2,      // target size in MB\n  quality: 0.75,         // JPEG quality\n  maxWidth: 800,\n  maxHeight: 600\n};\n\nconst compress = new Compress(options);\n\n// Assuming 'files' is an array of File/Blob from an <input type=\"file\">\ncompress.compress(files).then(conversions => {\n  const { photo, info } = conversions[0];\n  console.log('Compressed size:', photo.size, 'bytes');\n  console.log('Original name:', photo.name);\n  console.log('Dimensions:', photo.width, 'x', photo.height);\n  // Use photo.data (Blob) for upload or display\n  const url = URL.createObjectURL(photo.data);\n  document.getElementById('preview').src = url;\n  // Revoke URL after image loads\n  Compress.loadImageElement(document.getElementById('preview'), url).then(() => {\n    URL.revokeObjectURL(url);\n  });\n});","lang":"javascript","description":"Creates a Compress instance with options, compresses an array of image Files, and displays the first result using a Blob URL."},"warnings":[{"fix":"Use Blob data directly or call Compress.blobToBase64(photo.data) if you need base64.","message":"V1 returned base64, V2+ returns Blob objects. Code expecting base64 strings will break.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Re-test compression results and adjust quality/maxDimensions.","message":"In v1, constructor options used 'maxWidth' and 'maxHeight' incorrectly; v2+ fixes this but may change behavior for large images.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use an image editor or alternative library if alpha preservation is required.","message":"PNG images with transparent backgrounds will have transparency replaced with black in the output JPEG Blob.","severity":"gotcha","affected_versions":"all"},{"fix":"Skip compression for animated GIFs, or use a GIF-specific library.","message":"GIF images will lose animation after compression; only the first frame is kept as a static JPEG.","severity":"gotcha","affected_versions":"all"},{"fix":"Use server-side alternatives like sharp or image-min.","message":"Library relies on Canvas API and will not work in Node.js or server-side environments.","severity":"gotcha","affected_versions":"all"},{"fix":"Switch to ESM import syntax if your project supports it.","message":"Using CommonJS 'require' with bundlers that tree-shake may include unnecessary code; ESM import is recommended.","severity":"deprecated","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Change import statement to: import Compress from 'client-compress';","cause":"Using named import instead of default import.","error":"Uncaught TypeError: Compress is not a constructor"},{"fix":"Run 'npm install client-compress' and ensure import is from 'client-compress' without subpaths.","cause":"Package not installed or incorrect import path.","error":"Cannot find module 'client-compress'"},{"fix":"Ensure the image server sends Access-Control-Allow-Origin header or load images from same origin.","cause":"Image loaded from cross-origin without CORS headers.","error":"Failed to execute 'toBlob' on 'HTMLCanvasElement': Tainted canvases may not be exported."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}