ezsqueeze

A simple, efficient file compression CLI and library. Compresses images and audio files in bulk, with caching so repeated runs only process changed files.

Install

npm install -g ezsqueeze
# or
yarn global add ezsqueeze

CLI Usage

# Run with defaults (compresses .png and .mp3 files in the current directory)
ezsqueeze

# Run with a config file
ezsqueeze ezsqueeze.config.js

Output is written to ./ezsqueezed/, mirroring the original directory structure.

Defaults

When run without a config file:

| Format | Treatment | | ------ | ----------------------------------------------- | | .png | Compressed with sharp — level 9, palette mode | | .mp3 | Re-encoded with ffmpeg at 64 kbps |

Ignored by default: node_modules/**, dist/**, .git/**

Config File

Create a ezsqueeze.config.js to customize behaviour:

const { getPngTransformer, getMp3Transformer } = require('ezsqueeze')

/** @type {import('ezsqueeze').Config} */
module.exports = {
  // Only process files matching these glob patterns
  patterns: ['assets/**/*.png', 'audio/**/*.mp3'],

  // Exclude these paths from the walk
  ignore: ['node_modules/**', 'dist/**', '.git/**', 'vendor/**'],

  // Where to write compressed files (default: ./ezsqueezed)
  outputDir: './out',

  // Where to store the content-hash cache (default: ./.ezsqueeze-cache)
  cacheDir: './.cache',

  // Max number of files processed in parallel (default: 1)
  maxConcurrency: 4,

  // Override or extend the built-in transformers
  transformers: {
    '.png': getPngTransformer({ compressionLevel: 9, palette: true }),
    '.mp3': getMp3Transformer({ bitrate: 128 }),
  },
}

Config options

| Option | Type | Default | Description | | ---------------- | ----------------------------- | ------------------------------------------- | ---------------------------- | | patterns | string[] | all transformer extensions | Glob patterns to include | | ignore | string[] | ['node_modules/**', 'dist/**', '.git/**'] | Glob patterns to exclude | | outputDir | string | ./ezsqueezed | Where to write output | | cacheDir | string | ./.ezsqueeze-cache | Where to store the cache | | maxConcurrency | number | 1 | Parallel file limit | | transformers | Record<string, Transformer> | png + mp3 | Extension-to-transformer map |

Custom Transformers

A transformer is just an async function (inputPath, outputPath) => Promise<void>. You can add support for any format:

module.exports = {
  transformers: {
    '.jpg': async (input, output) => {
      const sharp = require('sharp')
      await sharp(input).jpeg({ quality: 75 }).toFile(output)
    },
    '.wav': async (input, output) => {
      // your ffmpeg / other logic here
    },
  },
}

Caching

Files are hashed (SHA-1) before processing. If a file with the same hash was already processed, the cached result is copied directly — no re-encoding. Delete .ezsqueeze-cache to force a full reprocess.

Programmatic Use

import { run } from 'ezsqueeze'

await run('./ezsqueeze.config.js')

License

MIT