asset_shrink 0.1.0

A zero-history, quality-gated Flutter and Dart dev-time asset compressor (PNG/JPEG) with native CLI and pure-Dart fallback.

asset_shrink

A zero-history, quality-gated dev-time asset compressor for Flutter and Dart projects.

asset_shrink compresses PNG and JPEG images in place—retaining the exact file path, format, and pixel dimensions so you never have to adjust your asset references or code.

---

Why asset_shrink?

• Real World Savings: Compresses asset payloads by 50% to 80%+ (e.g. 473 KB PNG down to 109 KB with zero noticeable visual difference).
• Zero History / Manifest-Free: Decides purely from each file's current bytes on disk. Re-runs are always safe and idempotent without generating pesky .cache or .manifest files in your repo.
• Strict Size Invariant: A file is only ever modified if the optimized result is strictly smaller. If optimization doesn't yield a size reduction, the original is left 100% byte-for-byte untouched.
• Dual-Tier Engine: Uses native pngquant + oxipng + jpegoptim when available on PATH for state-of-the-art compression; gracefully falls back to a pure-Dart lossless pass when native tools are absent.
• Batch Fault Tolerance: Corrupt or tiny placeholder files never crash the run; errors are isolated per file and reported in the final summary.

---

Getting Started

1. Add as a Dev Dependency

Add asset_shrink to your pubspec.yaml:

dev_dependencies:
  asset_shrink: ^0.1.0

2. Run the Compressor

Run the command in your project root:

dart run asset_shrink

To preview the compression results without writing changes to disk:

dart run asset_shrink --dry-run

---

Native Tools (Recommended)

asset_shrink works out of the box with zero native dependencies via pure Dart. However, installing native CLI utilities unlocks palette quantization and maximum compression gains:

Tool	Format	Purpose
pngquant	PNG	SSIM-gated palette quantization
oxipng	PNG	Lossless DEFLATE/chunk optimization
jpegoptim	JPEG	Quantization-aware quality & EXIF stripper

Install Native Tools

macOS (Homebrew):

brew install pngquant oxipng jpegoptim

Linux (Debian / Ubuntu):

sudo apt-get update && sudo apt-get install -y pngquant oxipng jpegoptim

Windows (winget / scoop):

winget install pngquant oxipng jpegoptim

---

Configuration

Configure asset_shrink directly in your pubspec.yaml:

asset_shrink:
  # Directory to scan for assets (default: 'assets')
  assets_dir: assets

  # PNG compression quality range (default: '90-100')
  png_quality: "90-100"

  # JPEG max quality level 1-100 (default: 90)
  jpg_quality: 90

  # Files or directories to ignore (glob patterns)
  exclude:
    - "assets/do_not_compress/**"
    - "assets/icons/pixel_art.png"

---

CLI Reference

dart run asset_shrink [path] [options]

Options:
-q, --quality        PNG compression quality range (e.g. 90-100, 65-80)
-j, --jpg-quality    JPEG compression quality (1-100, default: 90)
-n, --dry-run        Simulate compression without modifying any files
-v, --verbose        Show verbose output for all processed files
-h, --help           Show help message

---

License

MIT License. See LICENSE for details.