aibot88 Image Optimization Pipeline Config
Coverage
- The format-negotiation table — which output formats the pipeline produces (AVIF + WebP + JPEG fallback is the canonical shape) and the priority order browsers should request
- Srcset breakpoints — the widths the pipeline emits per image role (hero, content, thumbnail) and how those align with the site's CSS layout breakpoints
- Per-format compression quality — JPEG at 80, WebP at 75, AVIF at 65 is a defensible default; anything more aggressive needs visual A/B verification
- Transparency preservation — the pipeline must detect alpha channels in source PNGs and disable lossy formats (or fall back to lossless WebP / AVIF) for those specific images
- Idempotency — the pipeline must not reprocess already-optimized outputs on every build (cache invalidation by source-file hash, not timestamp)
- Source-format coverage — what the pipeline accepts as input (PNG, JPEG, WebP source) and what it explicitly rejects (HEIC, RAW, video formats)
Philosophy
A build-time image pipeline is a config-defined contract between the source-of-truth images in content/ and the bandwidth-optimized variants the browser receives. Bugs here are silent: a misconfigured srcset doesn't crash the build, it just sends a 4MB hero image to a phone. The discipline is to encode every choice — breakpoints, formats, quality, transparency rules — explicitly in the config, with a comment naming the constraint that drove each choice. Pipeline behavior should be derivable from the config without reading the build script.
Key Files
| File | Purpose |
|---|---|
lib/images/pipeline.config.ts |
The canonical config: breakpoints, formats, quality settings, source-format allowlist |
scripts/build-images.ts |
The build entrypoint that reads the config and walks content/ — should be a thin runner with no embedded policy |
lib/images/format-negotiation.ts |
The runtime helper that maps a request's Accept: header to the right pre-built variant |
Verification
Before merging any change to the pipeline config:
- Every output format has an explicit quality setting; no relying on library defaults
- Srcset breakpoints match (or are a documented superset of) the site's CSS layout breakpoints
- PNG sources with an alpha channel route to lossless or alpha-preserving lossy formats (WebP-lossless, AVIF) — never to JPEG
- The pipeline skips already-optimized outputs by source-hash comparison; running the build twice in a row is a no-op on the second run
- An end-to-end test under
__tests__/images/exercises a fixture image of each accepted format and asserts the expected variant set is produced - The format-negotiation helper has a fallback path for clients that send no
Accept:header (or one that lists no supported format)
Do NOT Use When
| Use instead | When |
|---|---|
| (a frontend image-rendering skill) | The task is choosing the right <picture> / <img srcset=...> markup at the component level |
debugging |
A specific image is failing to optimize and you need to reproduce from build logs |
documentation |
The task is writing a contributor doc explaining how the pipeline works |
refactor |
The task is restructuring the pipeline code without changing the config contract |