Ship smaller images automatically.

ImageForge CLI converts JPG/PNG assets to WebP and AVIF at build time, generates blurDataURL placeholders, writes imageforge.json, and keeps reruns deterministic with hash-based caching.

$npm install -g @imageforge/cli

$npx @imageforge/cli ./public/images

Use global install for repeated runs, npx for one-off execution.

View docs on GitHub

terminal

$ imageforge ./public/images -f webp,avif

imageforge v0.1.5

Run started at (example): 2026-02-11T09:30:00.000Z

Build-time optimization pass for 12 files

Formats: webp,avif Blur placeholders: enabled

Stale outputs · missing placeholders · scripts only one person understands

How it works

Run

Point ImageForge at your source directory. It converts files to WebP/AVIF and generates blurDataURL placeholders.

imageforge ./public/images -f webp,avif

Cache

Future runs reuse hash-based cache data so only modified images are processed.

imageforge ./public/images --concurrency 4
# example: 3 processed, 47 cached

Ship

Consume imageforge.json in app code for dimensions, format outputs, and placeholders.

{
  "generated": "2026-02-11T09:30:00.000Z",
  "images": {
    "hero.jpg": {
      "blurDataURL": "data:image/png;base64,iVBOR...",
      "outputs": {
        "webp": { "path": "hero.webp", "size": 98765 },
        "avif": { "path": "hero.avif", "size": 65432 }
      }
    }
  }
}

Features

WebP + AVIF

Convert source images to modern formats with deterministic output paths.

-f webp,avif

Blur placeholders

Generate blurDataURL values and dimensions for fast progressive rendering in Next.js.

--blur

Hash cache

Content and options hashing skips unchanged images so reruns stay fast and predictable.

--cache

CI guard

Use --check to exit non-zero when images need processing in CI.

--check

Bounded concurrency

Control parallel processing with --concurrency for stable local and CI resource usage.

--concurrency

JSON output

Use --json to emit a structured run report to stdout for CI logs and automation.

--json

Actual run (example) - 12 source images, single command

Input

8.4 MB

12 JPEGs + PNGs

Output

1.9 MB

WebP/AVIF derivatives

Saved

77%

smaller on disk

Time

2.1s

example run duration

Manifest output

Every run writes imageforge.json with source dimensions, format outputs, blurDataURL, and cache hash metadata. Example timestamp: 2026-02-11T09:30:00.000Z.

imageforge.json

{
  "version": "1.0",
  "generated": "2026-02-11T09:30:00.000Z",
  "images": {
    "hero.jpg": {
      "width": 1200,
      "height": 800,
      "aspectRatio": 1.5,
      "blurDataURL": "data:image/png;base64,iVBOR...",
      "originalSize": 345678,
      "outputs": {
        "webp": { "path": "hero.webp", "size": 98765 },
        "avif": { "path": "hero.avif", "size": 65432 }
      },
      "hash": "a1b2c3d4e5f67890"
    }
  }
}

CI enforcement with --check

Use --check in CI to fail when source images need processing and keep output deterministic across branches.

Failing run

bash

$ imageforge ./public/images --check

[1/3] cached logo.png
[2/3] needs processing hero.jpg
[3/3] needs processing new-banner.png

2 image(s) need processing.
Run: imageforge ./public/images -f webp,avif
Exit code: 1

Passing run

bash

$ imageforge ./public/images --check

[1/3] cached logo.png
[2/3] cached hero.jpg
[3/3] cached new-banner.png

All images up to date.
Exit code: 0

Next.js integration

Import imageforge.json and feed blurDataURL and dimensions into next/image.

lib/imageforge.ts

// lib/imageforge.ts
import manifest from "../imageforge.json";

export function getImageMeta(src: string) {
  return manifest.images[src];
}

// app/page.tsx
import Image from "next/image";
import { getImageMeta } from "@/lib/imageforge";

const hero = getImageMeta("hero.jpg");
const heroSrc = "/images/hero.jpg";

<Image
  src={heroSrc}
  alt="Hero"
  width={hero.width}
  height={hero.height}
  placeholder="blur"
  blurDataURL={hero.blurDataURL}
/>;

Keep image optimization boring and reliable.

Ship smaller images automatically with deterministic outputs, CI guardrails, and machine-readable run reports.

$npm install -g @imageforge/cli

GitHub·npm·@imageforge/cli v0.1.5·Node >= 22