Module cache 

Image processing cache for incremental builds.

AVIF encoding is the bottleneck of the build pipeline — a single image at three responsive sizes can take several seconds through rav1e. This module lets the process stage skip encoding when the source image and encoding parameters haven’t changed since the last build.

Design

The cache targets only the expensive encoding operations (create_responsive_images and create_thumbnail). Everything else — dimension reads, IPTC metadata extraction, title/description resolution — always runs. This means metadata changes (e.g. updating an IPTC title in Lightroom) are picked up immediately without a cache bust.

Cache keys

The cache is content-addressed: lookups are by the combination of source_hash and params_hash, not by output file path. This means album renames, file renumbers, and slug changes do not invalidate the cache — only actual image content or encoding parameter changes do.

• source_hash: SHA-256 of the source file contents. Content-based rather than mtime-based so it survives git checkout (which resets modification times). Computed once per source file and shared across all its output variants.

• params_hash: SHA-256 of the encoding parameters. For responsive variants this includes (target width, quality). For thumbnails it includes (aspect ratio, short edge, quality, sharpening). If any config value changes, the params hash changes and the image is re-encoded.

A cache hit requires:

1. An entry with matching source_hash and params_hash exists
2. The previously-written output file still exists on disk

When a hit is found but the output path has changed (e.g. album renamed), the cached file is copied to the new location instead of re-encoding.

Storage

The cache manifest is a JSON file at <output_dir>/.cache-manifest.json. It lives alongside the processed images so it travels with the output directory when cached in CI (e.g. actions/cache on dist/).

Bypassing the cache

Pass --no-cache to the build or process command to force a full rebuild. This loads an empty manifest, so every image is re-encoded. The old output files are overwritten naturally.

Structs

CacheEntry

A single cached output file.

CacheManifest

On-disk cache manifest mapping output paths to their cache entries.

CacheStats

Summary of cache performance for a build run.

Functions

hash_file

SHA-256 hash of a file’s contents, returned as a hex string.

hash_responsive_params

SHA-256 hash of encoding parameters for a responsive variant.

hash_thumbnail_params

SHA-256 hash of encoding parameters for a thumbnail.

hash_thumbnail_variant_params

SHA-256 hash of encoding parameters for a named thumbnail variant.

manifest_path

Resolve the cache manifest path for an output directory.