imgsmith

> Forge optimized images for the modern web


imgsmith is a powerful image optimization tool that uses native CLIs (ImageMagick, WebP, AVIF) to convert and optimize images with intelligent format recommendations based on image analysis.

Features

- 🎯 Intelligent Format Selection - Automatically analyzes images and recommends the best format
- 🚀 Multiple Usage Modes - CLI, Library, or Vite Plugin
- 🔍 Image Analysis - Classifies images as photo, graphic, screenshot, or mixed content
- ⚡ Batch Processing - Optimize entire directories with configurable concurrency
- 📊 Core Web Vitals - Optimized for LCP and CLS performance metrics
- 🌐 Cross-Platform - Works on Linux, macOS, and Windows
- 💪 TypeScript - Fully typed with strict mode enabled

Installation

``bash
npm install @mrofisr/imgsmith
`

$3

imgsmith requires the following CLI tools to be installed:

Ubuntu/Debian:
`bash
sudo apt-get install imagemagick webp libavif-bin
`

macOS:
`bash
brew install imagemagick webp libavif
`

Windows:
`bash
choco install imagemagick webp
`

Verify installation:
`bash
npx imgsmith doctor
`

CLI Usage

$3

`bash


Auto-detect best format

imgsmith convert photo.jpg

Specific format

imgsmith convert photo.jpg photo.webp -f webp -q 85

Show size comparison

imgsmith convert image.png --compare
`

$3

`bash
imgsmith analyze photo.jpg
`

Output:
`
Image Information:
File: photo.jpg
Format: JPEG
Size: 2.4 MB
Dimensions: 1920x1080
Type: photo
Transparency: No
Animation: No

Recommendation:
✓ Format: AVIF
Reason: AVIF provides 50% better compression than JPEG for photos
`

$3

`bash


Optimize all images in directory

imgsmith optimize ./images

Recursive with custom settings

imgsmith optimize ./assets -r -f webp -q 80 -c 8
`

Library Usage

$3

`typescript
import { convert } from '@mrofisr/imgsmith';

// Auto-detect best format
const result = await convert('photo.jpg');
console.log(result.format); // "avif"
console.log(result.savingsPercent); // 52.3

// Specific format
const result2 = await convert('image.png', 'image.webp', {
format: 'webp',
quality: 85
});
`

$3

`typescript
import { convertMany } from '@mrofisr/imgsmith';

const files = ['photo1.jpg', 'photo2.jpg', 'logo.png'];
const results = await convertMany(files, {
format: 'auto',
concurrency: 4
});

console.log(results); // Array of ConvertResult
`

$3

`typescript
import { analyzeImage } from '@mrofisr/imgsmith';

const analysis = await analyzeImage('photo.jpg');
console.log(analysis.imageType); // "photo"
console.log(analysis.recommendation.format); // "avif"
console.log(analysis.recommendation.reason); // "AVIF provides 50%..."
`

$3

`typescript
import { OPTIMIZATION_RULES, CWV_GUIDELINES } from '@mrofisr/imgsmith';

console.log(OPTIMIZATION_RULES.photo.primary); // "avif"
console.log(CWV_GUIDELINES.lcp.maxSize); // 153600 (150KB)
`

Image Classification

imgsmith automatically classifies images into types:

- Photo: High color count, continuous tones → AVIF recommended
- Graphic: Low color count, flat colors, sharp edges → WebP recommended
- Screenshot: Low color ratio, text-heavy → WebP recommended
- Mixed: Everything else → WebP recommended

API Reference

$3

Convert a single image.

Parameters:
- input: string - Input file path
- output?: string - Output file path (optional)
- options?: ConvertOptions
- format?: "webp" | "avif" | "jpeg" | "png" | "auto" (default: "auto")
- quality?: number - Quality 1-100
- preserveOriginal?: boolean

Returns: Promise

$3

Convert multiple images in parallel.

Parameters:
- files: string[] - Array of input file paths
- options?: ConvertOptions & { concurrency?: number }
- concurrency?: number - Parallel conversions (default: 4)

Returns: Promise

$3

Analyze an image and get format recommendation.

Parameters:
- filePath: string - Input file path

Returns: Promise

$3

Get recommended format for an image.

Parameters:
- filePath: string - Input file path

Returns: Promise

Core Web Vitals

imgsmith optimizations are aligned with Google's Core Web Vitals:

- LCP (Largest Contentful Paint): Target < 150KB for hero images
- CLS (Cumulative Layout Shift): Preserves image dimensions
- Preferred Formats: AVIF and WebP for modern browsers

TypeScript Support

imgsmith is written in TypeScript with strict mode enabled and includes comprehensive type definitions:

`typescript
import type {
ImageFormat,
ImageType,
ConvertOptions,
ConvertResult,
AnalyzeResult,
FormatRecommendation,
} from '@mrofisr/imgsmith';
`

Development

`bash


Install dependencies

npm install

Build

npm run build

Run tests

npm test

Watch tests

npm run test:watch

Coverage

npm run test:coverage
``

License

MIT © abdurrofi

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

Built with:
- ImageMagick - Image manipulation
- WebP - WebP encoding
- libavif - AVIF encoding
- Commander.js - CLI framework
- Vitest - Testing framework