Lessbytes

A tool for compressing images. It picks the quality level for you and keeps the smallest format that still looks fine.

Available as a CLI tool and a JS library (browser + Node).

What it does

• Compresses JPEG, PNG, WebP, and AVIF images
• Automatically picks a quality level via linear sRGB SSIM, instead of fixed guessing
• Can try multiple output formats and keep whichever is smallest
• Accepts Files, Blobs, HTMLImageElements, ArrayBuffers, Uint8Arrays, and ImageData
• Can process a whole folder of images at once
• If compressing doesn't actually save space, it keeps the original file

Install

npm install lessbytes

Browser, no build step:

<script src="https://unpkg.com/lessbytes"></script>
<script>
  lessbytes.compress(file).then(r => console.log(`${(r.ratio * 100).toFixed(1)}% smaller`));
</script>

API

// ESM / bundlers
import { compress, compressBatch, computeSSIM, isFormatSupported } from 'lessbytes';

// CommonJS
const { compress } = require('lessbytes');

// Browser <script> tag — exposes a global `lessbytes`

compress(input, options?)

input can be a File, Blob, HTMLImageElement, URL string, ArrayBuffer, Uint8Array, or ImageData.

const result = await compress(file, {
  format: 'webp',         // 'webp' | 'auto' | 'jpeg' | 'png' | 'avif'
  maxWidth: 1920,          // resizes down if larger, never upscales
  maxHeight: null,
  targetSize: 100 * 1024,  // optional byte limit, e.g. for upload restrictions
  background: '#ffffff',   // fill color used if flattening transparency
  keepSmallest: true,      // return original if compression makes it bigger
  perceptualGamma: true   // use linear sRGB luma calculations (default: true)
});

result.blob     // compressed image
result.format   // e.g. 'webp'
result.ratio    // e.g. 0.84 (file is 84% smaller)
result.toFile('name.webp') // wraps result.blob as a File

Example, upload handler:

input.addEventListener('change', async () => {
  const { blob, toFile } = await compress(input.files[0], { maxWidth: 1920 });
  preview.src = URL.createObjectURL(blob);
  formData.append('photo', toFile('photo.webp'));
});

compressBatch(inputs, options?)

Compress multiple files, with a progress callback.

const results = await compressBatch(files, {
  concurrency: 3,
  maxWidth: 1600,
  onProgress: (done, total, last) => {
    console.log(`${done}/${total} done`);
  }
});

isFormatSupported(mime)

Returns true/false for whether the current browser can encode that format (mainly useful for checking AVIF support before showing it as an option).

CLI

npm install -g lessbytes

lessbytes <files...|dir> [options]

Requires sharp. If it's missing, the CLI prints the install command needed.

Note: npx lessbytes is not supported — install it globally first.

Basic usage

lessbytes photo.jpg                    # writes photo.min.webp next to it
lessbytes *.png -o out/                # compress a batch into a folder
lessbytes ./assets -r -o build/img     # compress a folder, including subfolders
lessbytes ./src/img -w                 # watch folder and auto-compress new assets

More examples

lessbytes hero.png --format webp --quality 80   # fixed quality, no auto-search
lessbytes banner.jpg --max-size 100kb           # keep file under a size limit
lessbytes huge.jpg --max-width 1920             # resize down, keep aspect ratio
lessbytes icon.png --keep-larger                # save even if result is bigger
lessbytes ./photos --dry-run                    # simulate compression size report

Interactive mode

Run with no arguments for a guided prompt:

lessbytes

  Image file or folder › photo.jpg

  Output format
    1  Auto (default)
    2  WebP
    3  AVIF
    4  JPEG
    5  PNG
  › 1

  Compression mode
    1  Smart — auto quality (default)
    2  Target file size
    3  Fixed quality
  › 1

  Max width in px (blank = no limit) › 1920
  Output path (blank = beside source) › build/img

Flags

| Flag | Description | Default | |---|---|---| | -o, --output <path> | Output file or folder | next to source, *.min.* | | -f, --format <fmt> | auto, jpeg, webp, png, avif | webp | | -q, --quality <1-100> | Fixed quality, skips auto mode | — | | --max-size <size> | Size limit, e.g. 100kb, 1.5mb | — | | --max-width <px> | Max width, keeps aspect ratio | — | | --max-height <px> | Max height, keeps aspect ratio | — | | -r, --recursive | Include subfolders | off | | -w, --watch | Watch directory for changes | off | | --dry-run | Simulate size reduction without saving | off | | --suffix <str> | Suffix for output filename | .min | | --keep-larger | Save even if the result is bigger | off | | -s, --silent | Only print errors | off | | -i, --interactive | Force interactive prompt | off | | --logo | Print logo and exit | — | | -h, --help | Show help | — | | -v, --version | Show version | — |

Format notes

• webp (default): converts everything to WebP.
• auto: tries several formats per image, keeps the smallest. Skips AVIF if unsupported.
• Any other format: only that one is used. JPEG flattens transparency onto a background color (white by default).

--max-size behavior

It first adjusts quality to try to hit the limit. If that's not enough, it also shrinks the image dimensions and tries again. If the target still can't be reached, it saves the smallest version possible and marks it ⚠ over target.

Output example

lessbytes v1.2.3  compressing 1 image
  ✓ photo.jpg   235.8 KB → 36.9 KB   -84%   webp q93

Done. 235.8 KB → 36.9 KB  (84.4% smaller)

If resized, it shows the scale (e.g. 60% scale). If compression didn't help, it shows kept original.

Exit codes

| Code | Meaning | |---|---| | 0 | Ran successfully | | 1 | Bad input, no images found, sharp missing, or everything failed |

Partial failures (some images succeed, some don't) still exit 0 — check individual rows for errors.

Compatibility

• Node: 16+ for the CLI
• Browser: works anywhere Canvas is supported; AVIF is used if available, otherwise falls back to WebP or JPEG
• Bundlers: ships ESM, CommonJS, and UMD — works with Vite, webpack, Rollup, esbuild, or a plain <script> tag

License

MIT © Dev