ImgCap

Automatically compress images to approximate target file size using binary search algorithm.

pnpm install imgcap

Why?

Users often encounter "File too large" errors when uploading images, forcing them to manually compress files using external tools. This creates friction and leads to user dropout. imgcap solves this by automatically compressing images to approximate your target size - no user intervention needed.

Note: The targetSize represents an ideal target. The actual output size will approximate this value within a reasonable tolerance range for optimal performance.

// Before: User sees error, leaves frustrated
❌ "File too large: Image upload size cannot exceed 2MB"

// After: Seamless auto-compression
✅ await imgcap(userPhoto, { targetSize: 2 * 1024 * 1024 })

Usage

import imgcap from 'imgcap'

// Social media avatar (500KB limit)
const avatar = await imgcap(file, { targetSize: 500 * 1024 })

// With format conversion
const webp = await imgcap(imageFile, {
  targetSize: 300 * 1024,
  outputType: 'image/webp'
})

API

interface Options {
  targetSize: number // Target file size in bytes (approximate)
  outputType?: ImageType // Output format (default: same as input)
}

type ImageType = 'image/jpeg' | 'image/png' | 'image/webp' | 'image/avif'

Tolerance Behavior

The algorithm automatically applies smart tolerance based on target size:

• Small files (<100KB): ±1KB tolerance for high precision
• Medium files (100KB-100MB): ±1% tolerance for reasonable flexibility
• Large files (>100MB): ±1MB tolerance to avoid excessive processing

Examples:

• Target 50KB → Actual: 49-51KB
• Target 500KB → Actual: 495-505KB
• Target 50MB → Actual: 49.5-50.5MB
• Target 1GB → Actual: 1023-1025MB

Browser only - Requires OffscreenCanvas support (modern browsers).

License

MIT © molvqingtai