@iamasek/optim

Fast local image optimization for WebP with beautiful ASCII progress bars.

Features

• 🚀 Fast parallel processing - Processes multiple images concurrently
• 🎨 Real-time progress bars - Overall progress + individual file progress
• 🖼️ Smart format selection - Automatically picks WebP or original format based on size
• 🎯 Quality/Speed balance - Optimized for both quality (82% default) and speed
• 📊 Detailed reporting - Shows savings, file sizes, and compression ratios
• 🔧 Flexible options - Quality, width, output directory, recursive mode, and more

Installation

npm install -g @iamasek/optim
# or
yarn global add @iamasek/optim

Usage

Basic Usage

# Optimize images in current directory
optim

# Optimize specific directory
optim ./images

# Recursive optimization
optim ./images -r

Advanced Options

# Custom quality and max width
optim ./images -q 85 -w 1920

# Output to different directory
optim ./images -o ./optimized

# Dry run (preview without changes)
optim ./images --dry-run

# Verbose output (show all processed files)
optim ./images -v

# Custom concurrency (number of parallel workers)
optim ./images -c 4

All Options

Options:
  -q, --quality <number>      WebP quality (1-100) (default: 82)
  -w, --width <number>        Max width in pixels (default: 1920)
  -o, --output <path>         Output directory (default: in-place)
  -r, --recursive             Process subdirectories
  -c, --concurrency <number>  Concurrent files to process (default: CPU cores - 1)
  --dry-run                   Preview without making changes
  -v, --verbose               Show detailed output
  -h, --help                  Display help

Programmatic Usage

You can also use @iamasek/optim as a library in your Node.js projects:

import { optimizeImage, processFiles, scanDirectory } from '@iamasek/optim';

const files = await scanDirectory('./images', { recursive: true });

const summary = await processFiles(files, './images', {
  quality: 82,
  maxWidth: 1920,
  outputDir: './optimized',
  recursive: true,
  preserveNames: false,
  overwrite: true,
  dryRun: false,
  verbose: false,
  concurrency: 4,
});

console.log(`Saved ${summary.totalSavedBytes} bytes`);

How It Works

1. Scans directory for images (jpg, jpeg, png, gif, tiff, webp, avif)
2. Processes in parallel with configurable concurrency
3. Smart optimization:
   • Generates WebP version at specified quality
   • For PNG with transparency, also generates optimized PNG
   • Compares file sizes and picks the smaller one
   • Skips conversion if result would be larger than original
4. Real-time progress with ASCII progress bars
5. Detailed summary showing total savings and statistics

Output Example

  optim v1.0.0

  Scanning /path/to/images...
  Found 124 images (45.2 MB)
  Quality: 82 | Max width: 1920px | Workers: 7


  Overall   ██████████████████████████████  85% (105/124)

  photo1.jpg            ████████████████████  100%
  banner.png            ████████████░░░░░░░░   65%
  logo.svg              ██████░░░░░░░░░░░░░░   30%


  ✓ Complete!

  Files:     118 optimized, 5 skipped, 1 errors
  Size:      45.2 MB → 18.7 MB
  Saved:     26.5 MB (58% reduction)

Algorithm Details

Quality/Speed Balance

• WebP Quality: Default 82% provides excellent quality with significant size reduction
• Max Width: Default 1920px covers most modern displays
• Parallel Processing: Uses CPU cores - 1 for optimal performance
• Smart Format Selection: Preserves PNG for small transparent images (logos, icons)

Optimization Strategy

For each image:
1. Read metadata (width, height, format, transparency)
2. Resize if width > maxWidth (preserving aspect ratio)
3. Generate WebP at specified quality
4. If PNG with alpha channel:
   - Also generate optimized PNG (compression level 9)
5. Compare file sizes:
   - Pick smaller of WebP vs original format
   - Skip if result >= original size (no degradation)
6. Write optimized file

License

MIT

Author

iamasek