1
Run
Point ImageForge at your source directory to generate WebP/AVIF derivatives and blur placeholders at build time.
imageforge ./public/images -f webp,avifPre-generate responsive images. Verify them before deploy.
ImageForge is a build-time image optimization CLI for Next.js and other static web apps. It generates responsive WebP and AVIF derivatives, blurDataURL placeholders, and a hash-based cache. It writes imageforge.json and enforces freshness in CI with --check for a repeatable image freshness workflow.
$
npm install --save-dev --save-exact @imageforge/cli@0.1.10$
npx @imageforge/cli@0.1.10 ./public/images --dry-runPin a project dev dependency for repeatable runs; use the one-off preview command when you are evaluating the CLI.
illustrative terminal replay
$ imageforge ./public/images --formats webp,avif --quality 80 --blur
Benchmark CLI version: 0.1.9
Run started at (example): 2026-05-29T09:30:00.000Z
Build-time optimization pass for 200 files
Formats: webp,avif Blur placeholders: enabled
Illustrative CLI output; summary timings are tied to the linked approved benchmark snapshot.
Per-request billing · first-hit latency · external-service compliance risk
How it works
2
Check
Add --check in CI so stale outputs fail the pipeline with a generation command that preserves the effective options; review shell quoting before running it.
imageforge ./public/images -f webp,avif --check
# fails if outputs are stale3
Ship
Read imageforge.json inside your app for dimensions, blurDataURL, and stable output paths.
{
"generated": "2026-05-29T09: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 }
}
}
}
}Why teams choose ImageForge
Keep image optimization predictable with build-time outputs, CI checks, and structured metadata your app can consume directly.
Generate at build time
Generate stable WebP/AVIF paths before deploy without a runtime image transformation service.
-f webp,avif
CI guardrails by default
Use --check to fail CI when source images changed without regenerated outputs.
--check
Fast reruns with hash cache
Content and options hashing skips unchanged files, keeping local and CI reruns predictable.
--cache
Blur placeholders and metadata
Emit blurDataURL, dimensions, and output paths in imageforge.json for direct next/image usage.
--blur
Bounded parallelism
Set --concurrency to keep large catalogs under control without overloading build workers.
--concurrency
Machine-readable run output
Use --json for structured logs in CI pipelines and internal automation tooling.
--json
Evidence snapshot - 200 source images, P2 / batch-all
See benchmark details in Methodology or browse the full evidence page.
As of July 10, 2026 - owner ImageForge Maintainers (CLI + Growth)
Dataset
200 images
P2 / batch-all
Cold wall
72.49s
input 5.1 MB, generated 1.1 MB
Warm p50
134.8ms
1475.6 img/s
Speedup
534.82x
cold vs warm mean wall
Methodology
Headline benchmark numbers are sourced from a documented benchmark evidence record and are updated through approval-gated sync PRs.
View the full benchmark report for cold/warm charts, deltas, and run metadata.
Sample Set
200 source images with a combined input size of 5.1 MB. Output target formats are WebP and AVIF under profile P2.
Runtime Environment
CLI v0.1.9, Node 22, ubuntu-24.04, dataset 1.0.0, scenario batch-all.
Command and Options
imageforge ./public/images --formats webp,avif --quality 80 --blur
Benchmark evidence source: .github/workflows/benchmark-ci.yml. Sync path: automated nightly snapshot PR to imageforge-site with manual reviewer approval.
What the Headline Numbers Mean
78% is the size delta from 5.1 MB input to 1.1 MB generated outputs in this evidence snapshot. 72.5s is the associated run duration shown in the example output.
As of July 10, 2026. Owner: ImageForge Maintainers (CLI + Growth). Artifact: benchmark workflow.
CI enforcement with --check
Use --check in CI to fail when source, cache, or derivative state needs processing across branches. Published version 0.1.10 validates the manifest together with source, cache, and derivative state.
Failing run
bash
# Illustrative transcript
$ imageforge ./public/images --output imageforge.json --formats webp,avif --quality 80 --blur-size 16 --concurrency 4 --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 --output imageforge.json --formats webp,avif --quality 80 --blur-size 16 --concurrency 4
Exit code: 1Passing run
bash
# Illustrative transcript
$ imageforge ./public/images --output imageforge.json --formats webp,avif --quality 80 --blur-size 16 --concurrency 4 --check
[1/3] cached logo.png
[2/3] cached hero.jpg
[3/3] cached new-banner.png
All images up to date.
Exit code: 0Copy the complete workflow and generated-state policy from the CI integration guide.
Next.js-first integration
Import imageforge.json and point src to a generated derivative, and use its dimensions and blur data. The example bypasses a second Next.js runtime transformation. The manifest is framework-neutral JSON, but other framework adapters should be verified against their own image and asset conventions.
lib/imageforge.ts
// lib/imageforge.ts
import manifest from "../imageforge.json";
import type { ImageForgeEntry } from "@imageforge/cli";
const images = manifest.images as Record<string, ImageForgeEntry>;
export function getImageMeta(src: string): ImageForgeEntry {
const image = images[src];
if (!image) throw new Error(`ImageForge manifest entry not found: ${src}`);
return image;
}
// app/page.tsx
import Image from "next/image";
import { getImageMeta } from "@/lib/imageforge";
const hero = getImageMeta("hero.jpg");
const heroSrc = `/images/${hero.outputs.webp.path}`;
<Image
src={heroSrc}
alt="Product hero banner"
width={hero.width}
height={hero.height}
placeholder="blur"
blurDataURL={hero.blurDataURL}
unoptimized
/>;Need multiple candidates? The responsive picture guide builds AVIF and WebP srcsets from manifest variants with a layout-aware sizes attribute. For a framework-free path, follow the native HTML guide.
Who this is for
Next.js-first workflows are front and center, with the same manifest pattern usable in other frameworks and static pipelines.
cost-conscious teams
Profile: small product teams and agencies that need predictable hosting costs.
Pain: per-request optimization pricing grows faster than traffic budgets.
ImageForge fit: pre-generate optimized assets without a runtime transformation service or ImageForge usage fee.
npx @imageforge/cli@0.1.10 ./public/images -f webp,avif
CI/CD teams
Profile: engineering orgs that already enforce lint, typecheck, and formatting in pipeline gates.
Pain: unoptimized assets slip into deploys because image checks are manual.
ImageForge fit: add --check so stale images fail fast with an effective-option remediation command.
imageforge ./public/images --check
air-gapped/compliance teams
Profile: security-sensitive environments with strict data residency and egress controls.
Pain: external image APIs can violate compliance boundaries or security policy.
ImageForge fit: all processing is local in the build environment, with no third-party upload path.
imageforge ./secure-assets -f webp,avif --concurrency 4
Vercel-to-self-host migrations
Profile: teams moving to VPS, Kubernetes, or self-managed hosting for cost and control.
Pain: runtime image optimization becomes migration friction and infrastructure overhead.
ImageForge fit: generate static derivatives at build time and serve from any CDN or static host.
imageforge ./public/images --out-dir ./public/optimized
Honest limitations
ImageForge is optimized for reviewable build-time pipelines. These tradeoffs keep costs predictable and operations simple.
Responsive widths are target-based and bounded
In responsive width-set mode, requested widths are treated as targets. Effective generated widths can clamp to source dimensions and do not upscale.
Mitigation: Set width targets intentionally, inspect generated outputs, and keep width-set counts within the documented cap for your CLI version.
No runtime responsive resizing
ImageForge generates a fixed derivative set at build time. It does not resize images on-the-fly per request.
Mitigation: Generate the sizes you need ahead of time or pair outputs with a CDN strategy.
No bundled global CDN
ImageForge writes static assets and metadata, but it does not include global delivery infrastructure.
Mitigation: Deploy outputs behind Cloudflare, CloudFront, Fastly, or your existing CDN layer.
First run scales with catalog size
Large first-time catalogs can take minutes to process because work scales with source file count.
Mitigation: Hash caching keeps subsequent runs fast by processing only changed files.
Check the constraints against your workload in the when-to-use decision guide.
Choose the processing model that fits
ImageForge is a build-time pipeline, not a replacement for every managed media platform. Start with how your images arrive and who should own transformation and delivery.
Choose build-time generation
Use ImageForge for repository-backed assets, fixed responsive candidates, reviewable generated files, and CI freshness enforcement.
Choose a managed runtime
Keep a managed image service for dynamic uploads, arbitrary transformations, media management, signed URLs, or an integrated delivery control plane.
Compare the whole system
Include build compute, storage, delivery, cache behavior, transfer, and operational ownership—not only transformation pricing.
Build once. Ship pre-generated assets.
Preview with --dry-run, add --check in CI, and avoid a runtime transformation service. Build, storage, CDN, and egress costs still depend on your hosting setup.
$
npm install --save-dev --save-exact @imageforge/cli@0.1.10$
npx @imageforge/cli@0.1.10 ./public/images --dry-run