Package Exports

@thaparoyal/image-compression
@thaparoyal/image-compression/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@thaparoyal/image-compression) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Advanced Image Compression (Browser & CDN Only)

An advanced, production-ready image compression library for JavaScript and TypeScript, designed for browser and CDN usage. No Node.js/Sharp dependency. Offers extensive configuration, automatic format selection, and high-quality compression.

Features

Multiple output formats: WebP, JPEG, PNG, AVIF (auto-detects browser support)
Five resize modes: contain, cover, fill, inside, outside
Progressive JPEG support
EXIF metadata preservation option
Smart quality optimization using binary search
Automatic downscaling for large images
High-quality image rendering with smoothing
TypeScript support with comprehensive type definitions
Flexible configuration options
Custom output filenames
Automatic format fallbacks
Detailed progress logging and error handling

Installation

npm install @thaparoyal/image-compression

CDN Usage

Use the UMD build for browser/CDN:

<script src="https://cdn.jsdelivr.net/npm/@thaparoyal/image-compression/dist/image-compression.umd.js"></script>

Quick Start (Browser)

import { compress } from '@thaparoyal/image-compression';

// Basic compression
const file = document.querySelector('input[type="file"]').files[0];
const compressedFile = await compress(file, {
  maxSizeMB: 0.5,  // target size in megabytes
  maxWidth: 1920,  // maximum width in pixels
  preferredFormat: 'webp'  // preferred output format
});

// Advanced compression with all options
const compressedFile = await compress(file, {
  maxSizeMB: 0.5,
  maxWidth: 1920,
  maxHeight: 1080,
  preferredFormat: 'webp',
  quality: 0.9,
  resizeMode: 'cover',
  preserveExif: true,
  progressive: true,
  debug: true,
  outputFilename: 'compressed-image.webp',
  downscaleDivisor: 4,
  minQuality: 0.2,
});

CDN Example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Image Compression</title>
  <script src="https://cdn.jsdelivr.net/npm/@thaparoyal/image-compression/dist/image-compression.umd.js"></script>
</head>
<body>
  <input type="file" id="fileInput" />
  <script>
    document.getElementById('fileInput').addEventListener('change', async (event) => {
      const file = event.target.files[0];
      const options = {
        maxSizeMB: 0.1,
        quality: 0.9,
        maxWidth: 800,
        maxHeight: 600,
        resizeMode: 'contain',
        preserveExif: false,
        progressive: false,
        debug: true,
        outputFilename: 'output.webp',
      };
      try {
        const compressedFile = await ImageCompression.compress(file, options);
        console.log('Compressed file:', compressedFile);
      } catch (error) {
        console.error('Compression failed:', error);
      }
    });
  </script>
</body>
</html>

API Reference

`compress(fileOrBlob: File | Blob, options: CompressionOptions): Promise<File>`

Compresses an image in the browser with advanced options.

`CompressionOptions`

interface CompressionOptions {
  maxSizeMB?: number;        // Target maximum size in megabytes (default: 0.1)
  quality?: number;          // Starting compression quality 0-1 (default: 0.9)
  maxWidth?: number;         // Maximum width in pixels (default: 800)
  maxHeight?: number | null; // Maximum height in pixels (default: null)
  preferredFormat?: 'webp' | 'jpeg' | 'png' | 'avif';  // Preferred output format (default: 'webp')
  preserveExif?: boolean;    // Preserve EXIF metadata (default: false)
  resizeMode?: 'contain' | 'cover' | 'fill' | 'inside' | 'outside';  // Resize mode (default: 'contain')
  minQuality?: number;       // Minimum allowed quality (default: 0.1)
  progressive?: boolean;     // Enable progressive JPEG (default: false)
  debug?: boolean;           // Enable debug logging (default: false)
  outputFilename?: string;   // Custom output filename
  downscaleDivisor?: number; // Divisor for initial downscaling (default: 5)
}

Advanced Usage Examples

Example: Custom Resize Mode

const compressedFile = await compress(file, {
  maxSizeMB: 0.2,
  maxWidth: 1024,
  maxHeight: 768,
  resizeMode: 'cover',
});

Example: Progressive JPEG

const compressedFile = await compress(file, {
  preferredFormat: 'jpeg',
  progressive: true,
});

Example: Preserve EXIF Metadata

const compressedFile = await compress(file, {
  preserveExif: true,
});

Example: Custom Output Filename

const compressedFile = await compress(file, {
  outputFilename: 'my-image.webp',
});

Example: Debug Logging

const compressedFile = await compress(file, {
  debug: true,
});

How It Works

Uses browser canvas for resizing and format conversion
Automatically selects the best supported format
Optimizes quality using binary search to meet target size
Preserves EXIF metadata if requested
Supports all major browsers and CDN delivery

@thaparoyal/image-compression