Client-Side Image Compression: @uppy/compressor vs compressorjs

Reducing image file size before upload is a critical optimization for modern web applications. It saves bandwidth, speeds up transfers, and reduces server storage costs. Two common solutions in the JavaScript ecosystem are compressorjs and @uppy/compressor. While they share the same goal, they serve different architectural roles. Let's explore how they differ in practice.

🏗️ Architecture & Dependency: Standalone vs Plugin

compressorjs is a standalone library.

• It has no dependencies on file uploaders.
• You can use it with fetch, XMLHttpRequest, or any custom logic.
• Best for projects that need compression without a full upload framework.

// compressorjs: Standalone usage
import { Compressor } from 'compressorjs';

const file = input.files[0];

new Compressor(file, {
  quality: 0.6,
  success(result) {
    // result is a Blob, ready to upload manually
    const formData = new FormData();
    formData.append('file', result);
    fetch('/upload', { method: 'POST', body: formData });
  },
});

@uppy/compressor is a plugin for the Uppy uploader.

• It depends on @uppy/core to function.
• It hooks into Uppy's lifecycle events automatically.
• Best for projects already committed to the Uppy ecosystem.

// @uppy/compressor: Plugin usage
import Uppy from '@uppy/core';
import Compressor from '@uppy/compressor';

const uppy = new Uppy()
  .use(Compressor, {
    quality: 0.6,
    // Automatically runs before upload
  });

// Uppy handles the upload after compression
uppy.upload();

⚙️ API Configuration & Control

compressorjs exposes detailed options for image manipulation.

• You control width, height, resize, and mimeType directly.
• Callbacks (success, error) handle the flow explicitly.
• Suitable for complex preprocessing logic beyond just uploading.

// compressorjs: Detailed configuration
new Compressor(file, {
  width: 800,
  height: 600,
  resize: 'cover',
  mimeType: 'image/webp',
  success(result) {
    console.log('Compressed to WebP:', result.size);
  },
  error(err) {
    console.error('Compression failed:', err.message);
  },
});

@uppy/compressor simplifies configuration for upload flows.

• Options are passed during plugin installation.
• It abstracts away the success/error callbacks into Uppy's event system.
• Less flexible if you need to manipulate the file outside the upload context.

// @uppy/compressor: Simplified configuration
uppy.use(Compressor, {
  quality: 0.6,
  mimeType: 'image/webp',
  // Uppy handles errors via its own logger/events
});

uppy.on('upload-success', (file, response) => {
  console.log('Upload complete after compression');
});

📄 File Handling & Output

compressorjs returns a new Blob object.

• You are responsible for replacing the original file.
• You must manually manage form data or request bodies.
• Gives you the freedom to store the blob locally or send it anywhere.

// compressorjs: Manual file handling
new Compressor(file, {
  success(result) {
    // You must create a new File or Blob to upload
    const compressedFile = new File([result], file.name, {
      type: result.type,
      lastModified: Date.now(),
    });
    // Proceed with your own upload logic
  },
});

@uppy/compressor replaces the file in Uppy's state.

• The original file in the Uppy store is swapped for the compressed version.
• No manual form data creation is needed.
• Ensures the uploader sends the optimized version without extra code.

// @uppy/compressor: Automatic file replacement
// No need to manually swap files. 
// The plugin intercepts the file before the request.
uppy.use(Compressor, {
  quality: 0.6,
});

// When uppy.upload() is called, it sends the compressed file

⚠️ Error Handling & Resilience

compressorjs requires explicit error callbacks.

• You must define what happens if compression fails (e.g., fallback to original).
• Gives you granular control over retry logic or user notifications.
• Essential for robust standalone implementations.

// compressorjs: Explicit error handling
new Compressor(file, {
  error(err) {
    // Decide whether to upload original or show error
    alert('Compression failed, uploading original.');
    uploadOriginal(file);
  },
});

@uppy/compressor integrates with Uppy's error system.

• Errors are emitted through Uppy's upload-error or plugin events.
• Less boilerplate but less control over specific compression failures.
• Relies on Uppy's built-in retry mechanisms.

// @uppy/compressor: Integrated error handling
uppy.on('upload-error', (file, error) => {
  // Handles both network and compression errors uniformly
  console.error('Upload or compression failed:', error);
});

🌱 When Not to Use These

These tools are specific to image optimization. Consider alternatives when:

• You need server-side compression for security or consistency: Use backend libraries (e.g., Sharp for Node.js).
• You are handling video or non-image files: These packages are strictly for images.
• You need advanced format conversion (e.g., HEIC to JPEG): Ensure the library supports the specific input format, as browser Canvas API has limitations.

📌 Summary Table

💡 Final Recommendation

Think in terms of your upload architecture:

• Building a custom uploader or just processing files? → Use compressorjs. It is lightweight, flexible, and does not force an upload framework on you.
• Already using Uppy? → Use @uppy/compressor. It saves development time by integrating directly into the existing pipeline, ensuring files are optimized without extra wiring.

Final Thought: Both tools solve the same problem but at different layers of the stack. compressorjs is the engine; @uppy/compressor is the integration of that engine into a specific vehicle. Choose based on whether you need the engine alone or the complete vehicle.