Lessbytes

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, instead of you setting a fixed number
• Can try multiple output formats and keep whichever is smallest
• 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, 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, or a URL string.

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
});

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

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

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
--suffix <str>	Suffix for output filename	.min
--keep-larger	Save even if the result is bigger	off
--dry-run	Simulate compression without writing files	off
-w, --watch	Watch input directory for new assets	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