Image Optimizer CLI

A fast and flexible CLI tool for optimizing images, converting formats and resizing images based on filename instructions or project configuration.

• Features
• Installation
• Usage
• Configuration
• CLI Options
• Supported Formats
• Filename Instructions
• SVG Support
• Configuration Priority
• Folder Structure
• Processing Statistics
• Example Workflow
• Requirements
• License

Features

• 🚀 Optimize JPEG, PNG, WebP, AVIF and SVG images
• 📁 Recursive directory scanning
• 📂 Preserve folder structure
• 🖼 Convert images to multiple formats
• 📏 Resize images directly from filename
• 📉 Configurable compression quality
• ⚙️ Project configuration file
• 💻 CLI arguments
• 🔍 Dry-run mode
• 🧹 Clean output directory
• 📊 Processing statistics
• ⚡ Powered by Sharp

Installation

# Global
npm install -g image-optimizer-cli

# Using npx
npx image-optimizer-cli ./images

# Local
npm install image-optimizer-cli
# or
npm install
npm link

Usage

image-optimizer [input-directory] [options]

The input directory can be provided either:

• as the first CLI argument;
• in the configuration file (inputDir).

Examples

Optimize images:

image-optimizer ./images

Save into another directory:

image-optimizer ./images \
    --output ./dist

Convert every image to WebP:

image-optimizer ./images \
    --format webp

Change quality:

image-optimizer ./images \
    --quality 70

Dry run:

image-optimizer ./images \
    --dry-run

Use custom configuration:

image-optimizer \
    --config ./configs/image-optimizer.config.ts

Configuration

Create a file:

image-optimizer.config.ts

Example:

import { defineConfig } from 'image-optimizer'

export default defineConfig({
    inputDir: './assets',
    outputDir: './public/assets',
    quality: 80,
    clean: true,
    outputs: {
        jpg: ['jpeg', 'webp'],
        jpeg: ['jpeg', 'webp'],
        png: ['png', 'webp'],
        webp: ['webp'],
        avif: ['avif'],
        svg: ['svg'],
    },
})

With this configuration:

logo.png

becomes

logo.png
logo.webp

without adding any filename instructions.

CLI Options

| Option | Description | | --------------- | ---------------------------------------- | | -c, --config | Path to configuration file | | -o, --output | Output directory | | -q, --quality | Compression quality (1–100) | | -f, --format | Force output format | | --dry-run | Show processing without writing files | | --clean | Clean output directory before processing |

Supported Formats

• JPG
• JPEG
• PNG
• WebP
• AVIF
• SVG
• TIFF

Filename Instructions

Filename instructions always override both CLI arguments and configuration.

Example:

logo[120].png
↓
logo.png

Resize

| Instruction | Result | | ------------------ | ---------------------------- | | logo[120].png | width = 120px | | logo[120x80].png | width = 120px, height = 80px | | logo[w=120].png | width = 120px | | logo[h=80].png | height = 80px | | logo[50%].png | resize to 50% | | logo[2x].png | scale ×2 |

Format Conversion

Convert:

photo[webp].png
↓
photo.webp

Keep original:

photo[+webp].png
↓
photo.png
photo.webp

Generate multiple formats:

photo[+webp,+avif].png
↓
photo.png
photo.webp
photo.avif

Resize + convert:

photo[320.webp].png
↓
photo.webp # width 320px

Resize + keep original:

photo[320.+webp].png
↓
photo.png
photo.webp

Both images will be resized.

Per-image quality:

photo[q=60].jpg
or
photo[quality=60].jpg

SVG Support

SVG files are never rasterized.

Supported:

logo[24].svg
↓
<svg width="24px"/>

logo[24x24].svg
↓
<svg
    width="24px"
    height="24px"/>

Configuration Priority

Image Optimizer resolves settings using the following priority:

1. Filename instructions
2. CLI arguments
3. Configuration file
4. Default values

Example:

Configuration:

outputs: {
    png: ['png', 'webp']
}

Image:

logo.png
↓
logo.png
logo.webp

But:

logo[avif].png
↓
logo.avif

because filename instructions always have the highest priority.

Folder Structure

Input:

images
├── logo[120].png
├── hero.jpg
└── icons
    ├── menu[32].svg
    └── close.png

Configuration:

export default defineConfig({
    outputDir: './dist',
    outputs: {
        png: ['png', 'webp'],
        jpg: ['jpeg'],
    },
})

Output:

dist
├── logo.png
├── logo.webp
├── hero.jpeg
└── icons
    ├── menu.svg
    ├── close.png
    └── close.webp

The directory structure is always preserved.

Processing Statistics

Example output:

Found 42 image(s)

✓ logo.png      420 KB → 95 KB (-77%)
✓ logo.webp     420 KB → 62 KB (-85%)
✓ hero.jpeg     1.8 MB → 640 KB (-64%)

Summary
────────────────────────────
Processed: 63
Skipped:   0
Before:    24.7 MB
After:     10.2 MB
Saved:     14.5 MB

Example Workflow

Configuration:

export default defineConfig({
    inputDir: './assets',
    outputDir: './public/assets',
    outputs: {
        png: ['png', 'webp'],
        jpg: ['jpeg', 'webp'],
    },
})

Assets:

assets
├── logo.png
├── hero.jpg
├── avatar[50%].png
├── icon[32].svg
├── banner[+avif].jpg

Result:

public/assets
├── logo.png
├── logo.webp
├── hero.jpeg
├── hero.webp
├── avatar.png
├── avatar.webp
├── icon.svg
├── banner.jpg
└── banner.avif

Requirements

• Node.js 18+
• Sharp 0.33+

License

MIT