Image Compressor

A high-performance image compressor tool built with Go CLI and Node.js plugin. Supports Windows and Linux with multiple output formats.

Features

• Cross-platform: Works on Windows and Linux
• Multiple formats: JPEG, PNG, WebP, AVIF, JPEG XL output
• Lossless compression: Support for lossless mode on WebP, AVIF, and JPEG XL
• Resize: Compress and resize images with max width/height (0 = original)
• Quality control: Adjustable compression quality (1-100)
• CLI tool: Standalone Go command-line tool
• Node.js Plugin: No dependencies, drop-in plugin for Node.js applications

Installation

Prerequisites

• Go 1.21 or later (for building the CLI from source, optional)

Optional External Tools (for WebP, AVIF, JPEG XL encoding)

For full format support, install these optional tools:

Windows (via Chocolatey or manual):

# Install via package managers or download pre-built binaries
# WebP: https://developers.google.com/speed/webp/download
# AVIF: https://github.com/AOMediaCodec/libavif
# JPEG XL: https://github.com/libjxl/libjxl

Ubuntu/Debian:

sudo apt-get install webp
sudo apt-get install libavif-bin
sudo apt-get install libjxl-tools

macOS (via Homebrew):

brew install webp
brew install libavif
brew install libjxl

Note: If these tools aren't installed, the tool will gracefully handle it:

• WebP defaults to JPEG encoding
• AVIF and JPEG XL will show helpful error messages

Pre-built Binaries

Pre-built binaries are included:

• compressor-windows.exe - Windows executable
• compressor-linux - Linux executable

No installation needed! Just use them directly.

Usage

Command Line Interface

# Lossless WebP compression (default)
./compressor \
  -input input.jpg \
  -output output.webp \
  -width 1920 \
  -height 1080

# Lossy WebP compression with quality setting
./compressor \
  -input input.jpg \
  -output output.webp \
  -quality 80 \
  -lossless=false

CLI Flags

• -input (required): Path to input image (supports: JPEG, PNG, WebP, AVIF, JPEG XL)
• -output (required): Path to output image (extension determines format)
• -width (optional): Maximum width in pixels (0 = use original, default: 0)
• -height (optional): Maximum height in pixels (0 = use original, default: 0)
• -quality (optional): Compression quality 1-100 (default: 85)
• -lossless (optional): Lossless compression mode true/false (default: true)

Supported Formats

Input formats:

• JPEG (.jpg, .jpeg)
• PNG (.png)
• WebP (.webp)
• AVIF (.avif)
• JPEG XL (.jxl)

Output formats:

• .jpg/.jpeg - JPEG format (lossy compression, best for photos)
• .png - PNG format (lossless compression, best for graphics)
• .webp - WebP format (lossless/lossy, modern efficient format)
• .avif - AVIF format (lossless/lossy, next-gen codec)
• .jxl - JPEG XL format (lossless/lossy, excellent compression)

Node.js Plugin Usage

To use the Node.js plugin, first install it via npm:

npm install @sampathkumara/image-compressor

Then, you can use the ImageCompressor class directly in your Node.js applications:

const ImageCompressor = require('@sampathkumara/image-compressor');

const compressor = new ImageCompressor();

async function example() {
  try {
    const result = await compressor.compress(
      './input.jpg',
      './output.webp',
      {
        maxWidth: 1920,
        maxHeight: 1080,
        quality: 85,
      }
    );

    console.log('Compression successful!');
    console.log(`Output: ${result.outputPath}`);
    console.log(`Dimensions: ${result.width}x${result.height}`);
    console.log(`File size: ${result.fileSize} bytes`);
  } catch (error) {
    console.error('Compression failed:', error.message);
  }
}

example();

Directory Structure

image-compressor/
├── main.go                      # Go CLI source code
├── go.mod                       # Go module definition
├── go.sum                       # Go module checksums
├── compressor.js                # Node.js plugin (no dependencies)
├── compressor-windows.exe       # Windows binary
├── compressor-linux             # Linux binary
├── FINAL_BINARIES.txt           # Binary usage guide
└── README.md                    # This file

How the Plugin Works

The compressor.js plugin:

1. Auto-detects your platform (Windows or Linux)
2. Looks for the binary in: current directory → ./bin/ → system PATH
3. Calls the binary with command-line arguments
4. Parses the output and returns results as a Promise
5. Zero dependencies - works with vanilla Node.js

Examples

Compress a large image for web

CLI:

# Windows
compressor-windows.exe -input large-photo.jpg -output optimized.webp -width 2560 -height 1440 -quality 80

# Linux
./compressor-linux -input large-photo.jpg -output optimized.webp -width 2560 -height 1440 -quality 80

Node.js Plugin:

const ImageCompressor = require('@sampathkumara/image-compressor');
const compressor = new ImageCompressor();

await compressor.compress(
  'large-photo.jpg',
  'optimized.webp',
  { maxWidth: 2560, maxHeight: 1440, quality: 80 }
);

Create thumbnails

CLI:

# Windows
compressor-windows.exe -input original.png -output thumbnail.webp -width 200 -height 200 -quality 90

# Linux
./compressor-linux -input original.png -output thumbnail.webp -width 200 -height 200 -quality 90

Convert formats

CLI:

# Windows
compressor-windows.exe -input image.jpg -output image.png -quality 95

# Linux
./compressor-linux -input image.jpg -output image.png -quality 95

Performance & Recommendations

Format Comparison

| Format | Lossless | Lossy | Compression | Best For | |--------|----------|-------|-------------|----------| | JPEG | ✗ | ✓ | Medium | Photos | | PNG | ✓ | ✗ | Medium | Graphics | | WebP | ✓ | ✓ | Excellent | Web | | AVIF | ✓ | ✓ | Excellent | Modern web | | JPEG XL| ✓ | ✓ | Excellent | Archival |

Speed & File Size

• JPEG/PNG: Fastest (no external tools needed)
• WebP: Fast, ~25-30% smaller than JPEG
• AVIF: Medium speed, ~50% smaller than JPEG
• JPEG XL: Medium speed, ~25% smaller than AVIF

Recommendations

• Use WebP for modern web applications
• Use AVIF for maximum compression on modern browsers
• Use JPEG XL for archival and format-agnostic compression
• Use PNG for graphics and lossless requirements
• Use JPEG only for backward compatibility

Limits

• Maximum recommended image size: 10000x10000 pixels
• API file upload limit: 100MB
• Resizing uses nearest-neighbor algorithm (fast, not perfect quality)

License

MIT