ImageForge

ImageForge is a desktop and CLI image optimizer for converting large PNG/JPG/WebP/AVIF assets into production-ready WebP/AVIF images using Sharp.

It is designed for frontend developers who need fast, reliable image compression, resizing, aspect-ratio normalization, and batch optimization.

Screenshot

The screenshot path is reserved for the first public release image.

Why This Project Exists

Frontend projects often collect large design exports that are too heavy for production. ImageForge provides a focused workflow for turning those folders into smaller, consistent, frontend-ready assets without deleting originals or requiring a cloud service.

It is especially useful for service cards, hero images, illustration-heavy pages, UI graphics, and content that includes readable text or detailed document-style elements.

Features

• Electron desktop app for Windows
• CLI for scriptable batch conversion
• Shared Sharp optimizer used by both desktop and CLI
• WebP, AVIF, both, and auto output modes
• Batch processing for png, jpg, jpeg, webp, and avif
• Aspect-ratio normalization such as 4:3, 16:9, and 1:1
• Cover, contain, and inside fit modes
• Built-in presets for common frontend use cases
• Safe cancellation after the current image finishes
• Per-image logs and final summary
• Existing outputs are skipped unless overwrite is enabled
• Originals are never deleted

Installation

npm install

Desktop App Usage

Run the desktop app in development:

npm run dev

Run the desktop app from a production renderer build:

npm start

Workflow:

1. Click Choose Folder.
2. Select a folder containing supported images.
3. Choose a preset or edit advanced settings.
4. Click Convert.
5. Open the generated webp folder from the summary card.

The desktop app requires the user to choose a folder. It creates a webp folder inside the selected folder.

CLI Usage

The CLI command is:

imageforge

Run through npm:

npm run cli

By default, the CLI uses the current working directory:

npm run cli

Pass a folder explicitly:

npm run cli -- --input "C:\path\to\your-images"

Common examples:

npm run cli -- --format webp
npm run cli -- --format avif
npm run cli -- --format auto
npm run cli -- --width 1600 --aspect-ratio 4:3
npm run cli -- --width 1400 --aspect-ratio 4:3 --target-max-kb 500
npm run cli -- --fit cover
npm run cli -- --fit contain
npm run cli -- --recursive
npm run cli -- --dry-run

Presets

ImageForge includes these presets:

• Web App Hero: 1920px, 16:9, cover, WebP, 500-900KB
• Service Card 4:3: 1600px, 4:3, cover, WebP, 400-700KB
• Maximum Quality: 1920px, 4:3, contain, WebP, 700-1200KB
• High Compression: 1400px, 4:3, cover, WebP, 250-500KB
• Transparent Assets: 1200px, 1:1, contain, WebP, 200-600KB
• Custom: manual settings

Selecting a preset updates the advanced settings. Editing any setting switches the UI to Custom.

Recommended Settings

Service-card images:

format: webp
width: 1600
aspect ratio: 4:3
fit: cover
quality: 90
min quality: 70
target max KB: 700

Hero images:

format: webp
width: 1920
aspect ratio: 16:9
fit: cover
quality: 90
min quality: 72
target max KB: 900

Use contain when every edge of the original artwork must be preserved. Use cover when consistent card or hero dimensions matter more than preserving all edges.

WebP vs AVIF

WebP is the best default for compatibility, quality, and encoding speed. It is a practical choice for most frontend applications.

AVIF is often smaller, but slower to encode and should be visually reviewed, especially for text-heavy images or detailed service-card graphics.

The auto mode prefers WebP unless AVIF is meaningfully smaller while keeping acceptable quality.

Cover vs Contain

cover fills the target ratio and removes empty bars, but may crop edges.

contain preserves the full image, but may add padding.

inside resizes within the target dimensions without forcing a padded canvas.

Transparent images preserve transparency where possible. For non-transparent images, contain padding uses the selected background color.

Cancellation Behavior

Click Cancel while conversion is running to request cancellation.

ImageForge stops safely after the current image finishes. It does not interrupt file writes, does not corrupt partial outputs, and keeps files already converted. The final summary shows cancelled: true and the number of processed images.

Development Commands

npm run dev
npm run build
npm start
npm run cli

Build Windows Executables

Build the renderer and package Windows outputs:

npm run dist

Build output is written to:

release/

Configured Windows targets:

• nsis
• portable

No custom signing certificate is configured. The Windows config disables executable signing/editing so local packaging can run without symlink privileges.

Troubleshooting

If no images are found, confirm the selected folder contains supported files directly or enable recursive scanning.

If output files are skipped, enable overwrite or delete the existing files in the generated webp folder.

If AVIF conversion feels slow, use WebP for faster batch processing.

If important text or document details are cropped, switch from cover to contain.

If packaging fails after dependency changes, run npm install and then npm run dist again.

License

MIT License. See LICENSE.