Next.js

Use ImageForge CLI with Next.js

Connect manifest output to next/image or a responsive picture element.

1. Add a repository-backed source

This example starts with public/images/hero.jpg in a Next.js project. Install an exact CLI version in the project so the lockfile selects the same implementation locally and in CI.

pnpm add --save-dev --save-exact @imageforge/cli@0.1.10

2. Generate and inspect

Generate responsive candidates, then review imageforge.json and the new files under public/images before changing application markup.

pnpm exec imageforge ./public/images --formats webp,avif --widths 320,640,960,1280

3. Serve the generated file

Read dimensions, blur data, and output paths from imageforge.json. Point src at a generated derivative—not the original source—and set unoptimized so Next.js does not transform the pre-generated file again.

import Image from "next/image";
import manifest from "../../imageforge.json";

const hero = manifest.images["hero.jpg"];

<Image
  src={`/images/${hero.outputs.webp.path}`}
  width={hero.width}
  height={hero.height}
  alt="Product dashboard"
  placeholder="blur"
  blurDataURL={hero.blurDataURL}
  unoptimized
/>;

4. Add responsive variants

Use manifest variants to build srcset values for a native picture element. Supply a sizes value that reflects the rendered layout; otherwise browsers can download a larger candidate than necessary.

Static imports already give Next.js intrinsic dimensions and optional blur metadata for supported local images. ImageForge is most useful when you need committed derivatives, controlled width sets, framework-independent metadata, or CI freshness enforcement.

const avif = hero.variants?.avif ?? [];
const webp = hero.variants?.webp ?? [];
const srcSet = (items: typeof avif) =>
  items.map(({ path, width }) => `/images/${path} ${width}w`).join(", ");

<picture>
  <source
    type="image/avif"
    srcSet={srcSet(avif)}
    sizes="(min-width: 1024px) 50vw, 100vw"
  />
  <source
    type="image/webp"
    srcSet={srcSet(webp)}
    sizes="(min-width: 1024px) 50vw, 100vw"
  />
  <img
    src="/images/hero.jpg"
    width={hero.width}
    height={hero.height}
    alt="Product dashboard"
  />
</picture>;

5. Verify the integration

Run the application, inspect the rendered image request, and confirm it resolves to a generated path under /images rather than /_next/image. Test the actual sizes breakpoints so the browser does not select an unnecessarily large candidate.

Published version 0.1.10 exits with code 1 when source, cache, output, or manifest state is stale. Check mode does not write project state. Review and commit imageforge.json with the generated files so CI validates the exact generated state.

pnpm exec imageforge ./public/images --formats webp,avif --widths 320,640,960,1280 --check

Troubleshoot the first render

A missing manifest key means the lookup string does not match the input-relative POSIX path. A 404 usually means the manifest-relative output path was mapped to the wrong public URL. If requests still use /_next/image, confirm the rendered Image has unoptimized enabled or use the native picture example.

Keep width, height, and alt on the rendered image
Use a sizes value that matches the layout
Do not send an already-generated derivative through a second optimizer
Keep generation and CI check options identical