Storage Planning for a WebP Migration

A WebP migration can reduce page weight while increasing storage complexity. That sounds contradictory, but it is common. Teams keep originals, generate WebP versions, add responsive sizes, create fallbacks, upload to a CMS, and then push the same files to a CDN. Without a storage plan, nobody knows which files are source material, which are generated, and which can be deleted.

The goal of storage planning is not to save every byte in the asset library. The goal is to make the image pipeline understandable and recoverable. A real migration plan measures source bytes, generated bytes, temporary headroom, fallback copies, CMS derivatives, CDN copies, and rollback storage instead of declaring success from one JPEG-to-WebP comparison.

Separate Originals From Generated Files#

Original files should live in a controlled source location. Generated files should live somewhere else. This avoids the most damaging mistake in image optimization: deleting or overwriting the source because an output exists.

A small project can use a simple folder structure:

images/
  originals/
  resized/
  optimized/
  published/

The originals folder contains the highest-quality approved source files. The resized folder contains working copies at web dimensions. The optimized folder contains WebP, AVIF, JPEG, or PNG outputs after compression. The published folder contains only files that are actually referenced by the site.

Estimate Variant Growth#

One source image rarely produces one output. A responsive website may need several widths and more than one format:

product-chair.jpg
product-chair-480.webp
product-chair-960.webp
product-chair-1400.webp
product-chair-480.jpg
product-chair-960.jpg
product-chair-1400.jpg

That is not necessarily waste. It may be correct delivery. But the team should estimate variant growth before converting thousands of files.

For planning, count:

• number of source images
• number of widths per image
• number of output formats
• whether fallbacks are required
• whether the CMS creates its own derivatives
• whether the CDN stores transformed copies

This gives a more realistic storage picture than comparing one JPEG with one WebP.

A simple planning formula is:

peak working storage =
  originals
  + resized working files
  + generated WebP or AVIF outputs
  + fallback formats
  + reports and manifests
  + temporary write headroom
  + rollback copy of previously published files

Do not size the job from expected savings alone. Some already-optimized files may save little, and a few outputs can even be larger than their source after re-encoding.

Keep a Manifest#

A manifest maps each source to its generated outputs. It can be a JSON file, spreadsheet, database table, or build artifact. The format matters less than the discipline.

At minimum, record:

• source path
• source hash or last modified date
• output paths
• output dimensions
• output format
• conversion settings
• review status

The manifest helps answer practical questions: Can this WebP be regenerated? Which source created it? Is this file used on the site? Which generated files should be deleted after a layout change?

If you use GetWebP CLI, capture both the conversion report and a manifest:

getwebp ./images/originals --recursive --dry-run

getwebp ./images/originals \
  --recursive \
  -o ./images/optimized \
  --quality 82 \
  --manifest ./images/reports/manifest.json \
  --json > ./images/reports/conversion.ndjson

The NDJSON report is the run evidence. It includes convert.completed, convert.truncated, per-file outputPath, originalSize, newSize, savedRatio, quality, qualityMode, status, and errors. The manifest is useful for successful generated outputs and fingerprints, but it should not be treated as proof that every intended file converted.

You can extract a storage table from the report:

jq -r '
  select(.type == "convert.completed")
  | .data.results[]
  | [.status, .file, (.outputPath // ""), (.originalSize // ""), (.newSize // ""), (.savedRatio // ""), (.error // "")]
  | @tsv
' ./images/reports/conversion.ndjson > ./images/reports/storage-results.tsv

GetWebP's CLI command reference documents the flags used above, and the JSON output reference documents the size fields.

Do Not Let CMS Derivatives Hide the Source#

Many CMS platforms create additional image sizes during upload. That can be useful, but it can also hide the difference between your approved output and the final served file.

After upload, inspect what the CMS created. Confirm whether it generated extra JPEG, WebP, or thumbnail files, and whether those files follow your quality expectations. If the CMS re-encodes an already optimized file, the final result may not match your local review.

Storage planning should include the CMS media library, not only the local project folder.

Track CMS and delivery copies separately from source control:

Layer            Example                        Cleanup owner
source archive   images/originals               design/content
generated build   images/optimized              developers
CMS derivatives  uploads/...-scaled.webp        CMS owner
CDN cache         transformed edge objects       operations
rollback set      pre-migration published URLs   release owner

This avoids deleting a local file and assuming the public system is clean.

Plan Rollback Storage#

Rollback requires both source files and old published references. If a migration introduces visible artifacts, broken links, or CMS compatibility issues, the team should be able to return to the previous image set without restoring an entire server backup.

Keep the pre-migration published folder or export a list of old image URLs. Store it with the migration notes. If a CDN cache needs purging, record that as part of rollback too.

Rollback storage should include the previous references, not only the previous files:

restore file: /images/products/chair.jpg
remove file:  /images/products/chair.webp
restore in:   product-card component and CMS media record
cache action: purge /images/products/chair*

Define Retention Rules#

Not every generated file needs to live forever. Once a migration is stable, you may delete QA candidates, failed settings, duplicate exports, and unused variants. But retention should follow rules:

• never delete originals without a separate archival decision
• delete generated files only if they can be recreated
• keep migration manifests with the project
• keep rejected examples until the setting decision is settled
• review CMS and CDN copies before assuming cleanup is complete

Google's WebP documentation explains the format, while MDN's responsive images guide explains why multiple dimensions may be needed for one visual asset.

Storage Planning Makes Optimization Safer#

A clean storage plan makes WebP migration less fragile. Designers can find originals, developers can regenerate outputs, editors can upload only approved files, and operations teams can distinguish generated assets from archived source material.

The end result is not just smaller web pages. It is an image workflow that remains understandable after the first migration sprint ends.