lab-minify

lab-minify is a Node.js CLI for minifying image files in place with backups.

lab-minify ./img
lab-minify photo.jpg

It optimizes the original files, keeps the same image formats, and creates a backup folder before replacing files. The target can be a directory or a single image file.

Features

• Optimizes JPEG, PNG, WebP, and AVIF files.
• Accepts a directory or a single image filename as the target.
• Keeps the same format; it does not generate WebP or AVIF copies.
• Creates backups beside the target directory, or in one shared folder for single-file targets.
• Preserves nested folder structure inside the backup folder.
• Replaces originals only when the optimized output is smaller by default.
• Supports dry runs, recursive scans, and safe, balanced, and aggressive presets.
• Shows live progress in interactive terminals while files are processed.
• Skips SVG, GIF, ICO, XML, .filepart, and unknown file types.

Requirements

• Node.js 20 or newer
• npm 10 or newer

Install

Install globally if you want to run lab-minify from any project:

npm install -g lab-minify

Or run it without a global install:

npx lab-minify ./img

Usage

lab-minify ./img
lab-minify photo.jpg
lab-minify D:\absolute\path\to\photo.jpg
lab-minify /img/logo.png
lab-minify ./img --dry-run
lab-minify ./img --preset safe
lab-minify ./img --preset balanced
lab-minify ./img --preset aggressive
lab-minify ./img --no-recursive

Targets can be relative or absolute paths. On Windows, a leading-slash path like /img/logo.png falls back to the current folder when the drive-root path does not exist, so it works like ./img/logo.png. Quote paths that contain spaces.

Commands run immediately using the default options. Append flags when you want to change the defaults.

Options

| Option | Description | | --- | --- | | --dry-run | Optimizes in memory and prints estimated savings without writing files. | | --preset safe | Uses lighter compression. | | --preset balanced | Uses the default compression balance. | | --preset aggressive | Uses stronger compression with a higher chance of visible quality loss. | | --no-recursive | Only processes files directly inside the target folder. | | --formats jpg,png | Limits optimization to selected formats. | | --no-backup | Replaces files without creating backups. | | --replace-even-if-larger | Replaces files even if the optimized result is larger. |

Dry Runs

Use --dry-run before modifying a folder:

lab-minify ./img --dry-run

Dry runs scan files, optimize in memory, and print estimated savings. They do not replace files, create temporary files, or create backup folders.

Backup Behavior

For this command:

lab-minify ./img

The backup folder is created beside the target folder:

img-minify-bak

If that folder already exists, lab-minify creates a timestamped folder:

img-minify-bak-YYYYMMDD-HHMMSS

Only files that are actually replaced are backed up.

For a single-file target:

lab-minify photo.jpg

The backup folder is shared for single-file targets in the same folder:

single-files-minify-bak

If the same filename is backed up again, lab-minify keeps the backup in that same folder with a timestamped filename instead of creating another top-level backup folder.

Optimization Behavior

• JPEG files are normalized with Sharp and compressed with Sharp's mozjpeg-compatible encoder options.
• PNG files are normalized with Sharp and compressed with zlib plus palette quantization where the selected preset allows it.
• WebP and AVIF files are optimized with Sharp.
• Temporary files are written beside the original and then moved into place after successful optimization.
• Animated images are skipped to avoid dropping frames.