Use a migration manifest to hand optimised images to a build

What the migration manifest records

The migration pack writes a manifest that maps each source image to its optimised outputs. For WebP or width-variant work, a row records the source filename, the generated variants (format and width), the output filename, and any files that failed or were skipped. That single JSON file is the contract between the optimisation step and the build.

Because the mapping is data, not a manual list, a second site is configured rather than re-done: point the pack at a new folder, run the same preset, and a matching manifest comes out.

Wiring it into a static site generator

A static site generator consumes the manifest at build time. For each source image referenced in content, the generator looks up the optimised output and emits the correct markup, including WebP references and srcset variants for responsive packs.

This matters most on hand-built sites. Without the manifest the output filenames are guesswork; with it, the build is deterministic. The same content that referenced hero.jpg now emits hero.webp plus the width family, with no manual find-and-replace. That is the difference between a one-time migration and a repeatable image pipeline.

Using it in CI

In a CI pipeline the manifest becomes the verification layer. After the optimisation step runs, a build script checks that:

• every source in the content tree has a manifest row,
• no output file is missing,
• and the roll-out log lists what changed for the change note.

A CI job that fails on a missing mapping catches a bad reference before it ships, which is far cheaper than fixing broken images live.

Keeping the pipeline repeatable

The reason the manifest pattern scales across an agency is that it removes the manual step. Client A and client B both produce a manifest; the build script that consumes one consumes the other. New developers do not need to learn the image workflow by heart, because the pack plus manifest does the bookkeeping.

Start with the migration pack on one real client site. Once the manifest feeds a build successfully, the same setup carries into the next project as a saved configuration rather than fresh custom work.