imglite v1.0.0

imglite

A powerful command-line tool for efficiently converting images to WebP and other modern formats.

Features

• Image Format Conversion

  • Convert PNG, JPEG, and JPG images to WebP (default), AVIF, JPEG, or PNG
  • Maintain image quality with configurable settings
  • Smart adaptive quality based on image content

• Processing Options

  • Batch processing with customizable concurrency
  • Process individual files or entire directories
  • Recursive directory scanning
  • Replace original files or keep both versions
  • Exclude specific directories or patterns
  • Configurable output directory

• Image Optimization

  • Resize images (fixed dimensions or percentage)
  • Set maximum width/height constraints
  • Space savings reporting

• Developer Experience

  • Git integration with staged files mode
  • Automatic pre-commit hook setup
  • Dry run mode to preview what would be processed
  • Configuration file support
  • Intelligent caching to avoid reprocessing
  • Progress visualization
  • Detailed reporting with file size savings

Installation

Global Installation

npm install -g imglite

Local Installation

npm install imglite

Usage

Basic Usage

Convert all images in the current directory to WebP:

imglite

Convert specific images:

imglite -i ./images/logo.png

Convert images in a specific directory:

imglite -i ./images

Advanced Usage

Process images with adaptive quality:

imglite -i ./images --adaptive-quality

Convert to AVIF format:

imglite -i ./images --format avif

Resize images to 50% of original size:

imglite -i ./images --resize 50%

Set maximum dimensions (preserving aspect ratio):

imglite -i ./images --max-width 1200 --max-height 800

Process 8 images concurrently:

imglite -i ./images -R --concurrency 8

Only process Git staged images:

imglite --staged

Preview what would be processed without making changes:

imglite -i ./images --dry-run

Options

Options:
  --input, -i           Directory or specific files to process    [string] [default: "."]
  --output, -o          Output directory (if not specified, files are placed alongside originals)
  --quality, -q         WebP quality (0-100)                      [number] [default: 80]
  --min-quality         Minimum quality for adaptive mode         [number] [default: 50]
  --max-quality         Maximum quality for adaptive mode         [number] [default: 90]
  --adaptive-quality    Automatically adjust quality based on image content
                                                                 [boolean] [default: false]
  --replace, -r         Replace original files instead of keeping both
                                                                 [boolean] [default: false]
  --recursive, -R       Recursively scan directories             [boolean] [default: false]
  --ext, -e             File extensions to process (comma-separated)
                                                 [string] [default: "png,jpg,jpeg"]
  --exclude, -x         Directories or patterns to exclude (comma-separated)
                                       [string] [default: "node_modules,dist,build,.git"]
  --format, -f          Output format (webp, avif, jpeg, png)
                                          [string] [choices: "webp", "avif", "jpeg", "png"]
                                                                   [default: "webp"]
  --concurrency, -c     Number of images to process concurrently  [number] [default: based on CPU cores]
  --resize              Resize images (format: WIDTHxHEIGHT, e.g. 800x600, or 50%)
  --max-width           Maximum width of output images            [number]
  --max-height          Maximum height of output images           [number]
  --staged              Only process Git staged image files       [boolean] [default: false]
  --dry-run             Show what would be processed without making changes
                                                                 [boolean] [default: false]
  --no-cache            Disable caching (always reprocess images) [boolean] [default: false]
  --cache-dir           Directory to store cache files            [string]
  --silent              Suppress all output except errors         [boolean] [default: false]
  --verbose             Show detailed processing information      [boolean] [default: false]
  --init                Initialize imglite with a git pre-commit hook
                                                                 [boolean] [default: false]
  --help                Show help                                 [boolean]

Git Integration

To set up imglite as a Git pre-commit hook:

imglite --init

This will automatically create a pre-commit hook that processes any staged image files before each commit.

Configuration File

You can create a configuration file to avoid typing the same options repeatedly. imglite will look for configuration in these locations:

• .imgliterc
• .imgliterc.json
• .imgliterc.js
• imglite.config.js
• ~/.imgliterc

Example configuration file (.imgliterc.json):

{
  "quality": 85,
  "recursive": true,
  "adaptiveQuality": true,
  "format": "webp",
  "exclude": ["node_modules", "dist", "build", ".git", "temp"]
}

Examples

Simple Conversion Workflow

# Convert all images in src/assets recursively
imglite -i src/assets -R

# Check the results
ls -la src/assets

Build Process Integration

Add to your package.json:

"scripts": {
  "optimize-images": "imglite -i src/assets -o dist/assets -R -q 85"
}

Then run:

npm run optimize-images

Adaptive Quality with Size Reporting

imglite -i ./photos --adaptive-quality --verbose

License

MIT