Image Optimization Pipeline Config
Concept of the skill
What it is: The build-time contract for turning source images into responsive, compressed, format-specific outputs.
Mental model: The pipeline is a deterministic compiler stage: source image plus config produces a known set of artifacts.
Why it exists: Image quality, file size, and fallback support have to be reviewed before they become user-visible performance or fidelity regressions.
What it is NOT: It is not runtime <picture> markup, layout design, or incident debugging after a build fails.
Adjacent concepts: Responsive breakpoints, format negotiation, compression quality, transparency preservation.
One-line analogy: It is the recipe card the image build step follows for every asset.
Common misconception: Smaller output is always better; preserving transparency, fallback coverage, and layout fit are part of correctness.
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 of the skill
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:
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 |
1---2name: image-optimization-pipeline-config3description: Use when authoring or reviewing the build-time image pipeline config — defining responsive srcset breakpoints, picking output formats (AVIF / WebP / JPEG fallback), tuning compression quality per format, and ensuring the pipeline never produces a lossy artifact for source PNGs with transparency. Activate this skill whenever the task touches `lib/images/pipeline.config.ts`, `scripts/build-images.ts`, or any code path that resizes or recompresses content images. Do NOT use for runtime image rendering choices (use a frontend skill) or for chasing a specific build failure (use debugging).4license: MIT5---67# Image Optimization Pipeline Config89## Concept of the skill1011**What it is:** The build-time contract for turning source images into responsive, compressed, format-specific outputs.12**Mental model:** The pipeline is a deterministic compiler stage: source image plus config produces a known set of artifacts.13**Why it exists:** Image quality, file size, and fallback support have to be reviewed before they become user-visible performance or fidelity regressions.14**What it is NOT:** It is not runtime `<picture>` markup, layout design, or incident debugging after a build fails.15**Adjacent concepts:** Responsive breakpoints, format negotiation, compression quality, transparency preservation.16**One-line analogy:** It is the recipe card the image build step follows for every asset.17**Common misconception:** Smaller output is always better; preserving transparency, fallback coverage, and layout fit are part of correctness.1819## Coverage2021- The format-negotiation table — which output formats the pipeline produces (AVIF + WebP + JPEG fallback is the canonical shape) and the priority order browsers should request22- Srcset breakpoints — the widths the pipeline emits per image role (hero, content, thumbnail) and how those align with the site's CSS layout breakpoints23- Per-format compression quality — JPEG at 80, WebP at 75, AVIF at 65 is a defensible default; anything more aggressive needs visual A/B verification24- 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 images25- Idempotency — the pipeline must not reprocess already-optimized outputs on every build (cache invalidation by source-file hash, not timestamp)26- Source-format coverage — what the pipeline accepts as input (PNG, JPEG, WebP source) and what it explicitly rejects (HEIC, RAW, video formats)2728## Philosophy of the skill2930A 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.3132## Key Files3334| File | Purpose |35|---|---|36| `lib/images/pipeline.config.ts` | The canonical config: breakpoints, formats, quality settings, source-format allowlist |37| `scripts/build-images.ts` | The build entrypoint that reads the config and walks `content/` — should be a thin runner with no embedded policy |38| `lib/images/format-negotiation.ts` | The runtime helper that maps a request's `Accept:` header to the right pre-built variant |3940## Verification4142Before merging any change to the pipeline config:4344- [ ] Every output format has an explicit quality setting; no relying on library defaults45- [ ] Srcset breakpoints match (or are a documented superset of) the site's CSS layout breakpoints46- [ ] PNG sources with an alpha channel route to lossless or alpha-preserving lossy formats (WebP-lossless, AVIF) — never to JPEG47- [ ] The pipeline skips already-optimized outputs by source-hash comparison; running the build twice in a row is a no-op on the second run48- [ ] An end-to-end test under `__tests__/images/` exercises a fixture image of each accepted format and asserts the expected variant set is produced49- [ ] The format-negotiation helper has a fallback path for clients that send no `Accept:` header (or one that lists no supported format)5051## Do NOT Use When5253| Use instead | When |54|---|---|55| (a frontend image-rendering skill) | The task is choosing the right `<picture>` / `<img srcset=...>` markup at the component level |56| `debugging` | A specific image is failing to optimize and you need to reproduce from build logs |57| `documentation` | The task is writing a contributor doc explaining how the pipeline works |58| `refactor` | The task is restructuring the pipeline code without changing the config contract |
jacob-balslev