npm package: @sampathkumara/image-compressor
Description: High-performance image compressor CLI and Node.js plugin with embedded WebP support for Windows and Linux
Latest version: 1.0.2

# 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):**
```bash
# 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:**
```bash
sudo apt-get install webp
sudo apt-get install libavif-bin
sudo apt-get install libjxl-tools
```

**macOS (via Homebrew):**
```bash
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

```bash
# 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:

```bash
npm install @sampathkumara/image-compressor
```

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

```javascript
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:
```bash
# 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:
```javascript
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:
```bash
# 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:
```bash
# 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