Manifest and responsive images

Understand imageforge.json

Turn generated files into reliable application image metadata.

Entry contract

Each input-relative source key records dimensions, aspect ratio, original size, source/options hash, blurDataURL, and one output per format. Responsive runs also record ordered variants; outputs.<format> points to the largest effective variant.

Representative manifest

This abbreviated 1.0 document shows one responsive WebP entry. Actual hashes, sizes, dimensions, timestamps, paths, and candidate counts come from the source and effective options.

{
  "version": "1.0",
  "generated": "2026-02-08T00:00:00.000Z",
  "images": {
    "hero.jpg": {
      "width": 1920,
      "height": 1280,
      "aspectRatio": 1.5,
      "blurDataURL": "data:image/png;base64,...",
      "originalSize": 345678,
      "outputs": {
        "webp": { "path": "hero.w640.webp", "size": 17654 }
      },
      "variants": {
        "webp": [
          { "width": 320, "height": 213, "path": "hero.w320.webp", "size": 9012 },
          { "width": 640, "height": 427, "path": "hero.w640.webp", "size": 17654 }
        ]
      },
      "hash": "abc123..."
    }
  }
}

Path contract

Manifest keys and output paths use POSIX separators and are relative to the input directory. If public/images is mounted at /images, hero.webp maps to /images/hero.webp. An external out-dir may produce ../ segments, so resolve URLs deliberately.

Freshness contract

Published version 0.1.10 check mode evaluates source hashes, options, cache entries, expected derivative files, and imageforge.json.

JSON run-report contract

The --json flag writes a machine-readable run report to stdout with effective options, per-image status, summary counters, size totals, responsive variant widths when present, and a remediation command for failed checks. Keep diagnostics on stderr separate from the JSON consumer.

imageforge ./public/images --json > imageforge-report.json

Versioning boundary

Published CLI 0.1.10 identifies the manifest format as 1.0, but it does not publish standalone JSON Schema files or a separate backward-compatibility guarantee for every manifest and run-report field. Pin the CLI exactly, validate the version field, and review manifest/report changes during upgrades before treating fields as a long-lived external API.