How to migrate a client site to WebP without breaking layouts

Scope the roll-out before touching files

Migrating a client site to WebP is a batch job, not a set of one-off downloads. Before converting anything, decide three things:

1. Which images need converting (photos and gradients win big; flat logos and line art may stay PNG or SVG).
2. Where the files are served from (a static images/ folder, a CMS media library, or a CDN).
3. Whether the URLs can stay the same or need markup changes.

If the site serves images from a folder path, the cleanest migration keeps filenames and converts in place so no markup changes. If a CMS rewrites URLs, you handle conversion at the library level. The migration pack turns the whole batch into one controlled pass with a manifest, which is exactly what a WebP roll-out needs.

Convert JPG to WebP in one controlled pass

For a folder-based site, drop the image library into the migration pack and run a WebP conversion preset. The output keeps your naming convention (or rewrites to .webp consistently) and the manifest lists every file that changed.

The useful target is a web-quality lossy WebP, typically quality 80 to 82, not a lossless conversion. Photos converted losslessly stay needlessly large and forfeit the whole reason for the move. WebP at 82 usually matches a JPG at the same visual quality at a fraction of the weight.

Keep the original JPGs in a backup until the client signs off. Roll-back is then a re-upload, not a re-conversion.

Keep URLs stable or update markup deliberately

Two common layouts:

• Stable path, same filename: original hero.jpg becomes hero.webp served at the same directory. Any markup that hard-codes .jpg still breaks, so you update the reference once. If your platform rewrites images at serve time, this layer handles it and nothing else changes.
• New filenames: the manifest gives you the mapping, so a small script can rewrite references in the generated HTML. This is the safer choice for hand-built sites because the old files stay untouched until the swap is confirmed by an update checklist.

The migration manifest handoff guide covers wiring this mapping into a static site generator build so the roll-out is repeatable across client projects.

Verify with two checks

After the swap, confirm two things rather than assuming success:

• Rendering: load every page type (home, article, product, image gallery) at desktop and mobile widths and check no image is missing. A missing reference shows up as a broken image, which the manifest-based rewrite should make impossible.
• Page weight: measure the total image transfer on a few template pages before and after. You are aiming for a clear drop. If one page barely moved, check whether it still references old JPGs or oversized hero widths.

The responsive image pack setup also pairs with a WebP move, because once files are lighter a width set keeps them from being stretched above their breakpoint. Between the two, a typical agency migration cuts image weight by 60 to 80 percent with no visible change.