Registry / web-framework / compressorjs

compressorjs

JSON →
library1.3.0jsnpmunverified

Compressor.js is a client-side JavaScript image compression library that leverages the browser's native `HTMLCanvasElement.toBlob()` method for its core functionality. It performs lossy, asynchronous compression, meaning results can vary slightly across different web browsers and privacy settings. Primarily designed for pre-compressing images on the client before upload, it provides a straightforward API for handling `File` or `Blob` objects. The current stable version is 1.3.0, and the project appears actively maintained with a steady cadence of minor updates addressing bug fixes and introducing new options. Its key differentiator is its reliance on native browser APIs, simplifying its footprint but also making its compression effects browser-dependent. It ships with TypeScript types.

npm install compressorjs
INSTALL
IMPORT
SIG · COMPRESSORJS
C
compressorjs
web-frameworkjavascriptv1.3.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

Compressor
import Compressor from 'compressorjs';
import { Compressor } from 'compressorjs';
Compressor.js uses a default export for its main class in ESM environments.
Compressor
const Compressor = require('compressorjs/dist/compressor.common.js');
const Compressor = require('compressorjs');
For CommonJS environments, it's recommended to explicitly import from the 'compressor.common.js' bundle to ensure correct module resolution, as specified by the package.
Compressor.setDefaults
import Compressor from 'compressorjs'; Compressor.setDefaults({ quality: 0.8 });
import { setDefaults } from 'compressorjs';
`setDefaults` is a static method on the `Compressor` class, not a named export. Access it via the default imported `Compressor` instance.

Demonstrates how to select an image file from an input, compress it using Compressor.js with specific quality and dimension constraints, and then preview the compressed image or prepare it for upload.

import Compressor from 'compressorjs'; // Create a dummy file input for demonstration purposes const inputElement = document.createElement('input'); inputElement.setAttribute('type', 'file'); inputElement.setAttribute('id', 'fileInput'); inputElement.setAttribute('accept', 'image/*'); document.body.appendChild(inputElement); document.getElementById('fileInput')?.addEventListener('change', (e) => { const target = e.target as HTMLInputElement; const file = target.files?.[0]; if (!file) { console.log('No file selected.'); return; } new Compressor(file, { quality: 0.6, maxWidth: 800, maxHeight: 600, // Output the original image instead of the compressed one if the compressed size is larger. strict: true, success(result) { console.log('Compression successful! Compressed file:', result); // The 'result' is a File object (or Blob in older versions). // You can now upload this 'result' to your server. const formData = new FormData(); formData.append('compressedImage', result, result.name); // Example of what you might do next (e.g., using fetch or axios): // fetch('/path/to/upload', { method: 'POST', body: formData }) // .then(response => console.log('Upload success', response)) // .catch(error => console.error('Upload error', error)); const reader = new FileReader(); reader.onload = (event) => { const img = document.createElement('img'); img.src = event.target?.result as string; img.style.maxWidth = '200px'; document.body.appendChild(img); console.log('Displaying compressed image preview.'); }; reader.readAsDataURL(result); }, error(err) { console.error('Compression error:', err.message); }, }); });
Debug
Known issues
gotchaCompressor.js relies on the browser's native `HTMLCanvasElement.toBlob()` method, which performs lossy compression. The final image quality and compression efficiency can vary significantly across different web browsers and their implementations.
fix
Always test compression results across your target browsers. For applications requiring consistent compression across all clients or server-side processing, consider implementing server-side image optimization as a fallback or primary method.
affects: >=1.0.0
gotchaThe compression process is asynchronous, meaning the compressed image `result` is only accessible within the `success` callback function. Attempting to access `result` outside this callback will lead to undefined behavior or errors.
fix
Structure your code to ensure all operations dependent on the compressed image are executed inside the `success` callback provided to the Compressor constructor.
affects: >=1.0.0
gotchaIn Firefox, with `privacy.resistFingerprinting` mode enabled, `canvas.getContext('2d').getImageData()` might be unavailable. In such scenarios, Compressor.js (v1.3.0 and later) will output the original image instead of attempting compression.
fix
Inform users about this browser-specific privacy setting's impact. If compression is critical, provide alternative client-side strategies or prompt users to adjust their browser settings.
affects: >=1.3.0
gotchaBy default (`strict: true`), the library will output the original image if the compressed image's size is larger than the original, unless specific options like `retainExif`, a `mimeType` change, or explicit `width`/`height` constraints are set.
fix
Review the `strict` option and its exceptions carefully. If you explicitly need a compressed output even if it's larger, set `strict: false`, but be aware of the potential for increased file sizes.
affects: >=1.0.0
breakingPrior to version 1.1.1, Compressor.js could encounter loading errors when used in Node.js environments due to incompatible syntax in its bundled files.
fix
Upgrade to version 1.1.1 or later to resolve Node.js loading issues. For legacy Node.js environments, ensure proper Babel or transpilation configuration if you must use older versions of the library.
affects: <1.1.1
Errors
Common errors & fixes
The operation is insecure
This error can occur when canvas operations (like `toBlob()`) are attempted on images loaded from different origins without appropriate Cross-Origin Resource Sharing (CORS) headers. While some internal cases were fixed in v1.0.6, it can still manifest with external image sources.
fix
Ensure that images loaded from external domains are served with proper CORS headers (e.g., `Access-Control-Allow-Origin: *` or specific domains). For locally generated or user-provided files, this error is less common but can indicate browser security restrictions.
TypeError: Cannot read properties of undefined (reading 'files')
This error typically indicates that the DOM element for the file input was not found or was accessed before the HTML document was fully loaded.
fix
Ensure your JavaScript code executes after the DOM is ready. Place your script tag at the end of the `<body>` or wrap your initialization code in a `DOMContentLoaded` event listener (e.g., `document.addEventListener('DOMContentLoaded', () => { ... });`).
TypeError: Cannot set properties of undefined (setting 'quality')
This error usually occurs if `new Compressor()` is called with an invalid `file` argument (e.g., `null` or `undefined`) or if the `Compressor` class is not correctly instantiated using the `new` keyword.
fix
Verify that the `file` argument passed to `new Compressor(file, options)` is a valid `File` or `Blob` object, and always instantiate the class with `new Compressor(...)`.
Upgrade
Version history
1.3.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
20 hits · last 30 days
node
16
OpenAI (training)
1
Resources