Use changed paths to protect monorepo image quotas

A monorepo can contain thousands of images, but a commit usually changes only a handful. Sending every package’s assets through compression on every build is wasteful, and it makes a monthly image allowance hard to manage. The practical fix is to make the changed-file list the input to the compression step.

PiPic’s open-source CLI, published as @pipic/cli on npm, fits this job when a team wants compression in scripts or CI. Its free CLI tier covers 100 images per month; Pro covers 5,000. Those are monthly limits, not a reason to reprocess an entire repository. The orchestration around the CLI should decide which paths are eligible and when the job runs.

1. Define the image boundary

Start with an explicit policy for what the job can touch. PiPic supports JPG, PNG, WebP and AVIF, with files up to 8 MB each. Match those formats and limits in the repository script before submitting anything. Leave other formats, oversized images and files outside the intended asset directories for a separate review or workflow.

In a monorepo, that policy might include image directories in the web packages but exclude test fixtures, documentation screenshots or checked-in source artwork. Keep the package paths in one maintainable list rather than assuming every directory named “assets” has the same purpose. A false positive can consume quota or alter a file that was never meant for web delivery.

2. Build the input from the diff

Have the script compare the current change with the appropriate base revision, then pass only added or modified image paths through the eligibility checks. For pull-request CI, the comparison should cover the branch’s changes against its target, not just the last commit. Otherwise, a series of commits can leave earlier changed images out of the selected set.

Handle file states deliberately. Ignore deleted paths, since there is nothing to compress. For renames, use the current path and confirm that it exists in the checkout. Decide whether the workflow includes untracked files for local development; a committed-change diff will not find files that have not been added to version control. These details prevent both missed assets and accidental full-repository runs.

This is related to, but not the same as, a pre-commit check. A local hook can catch a changed image before it enters shared history, while CI can apply a consistent policy to a pull request. The practical cautions in handling staged files and failures in a pre-commit workflow still apply: define the input precisely and make failures visible rather than silently skipping work.

3. Keep the compression step narrow

Once the script has a filtered list, invoke the CLI on those paths rather than asking it to walk every package. The exact invocation belongs in the team’s script and should follow the CLI documentation; don’t hard-code assumptions about flags or output behavior into a repository guide. PiPic supports in-place replacement or writing to a fresh directory, so choose one approach and make the resulting files easy to review.

In-place replacement keeps the workflow compact, but it changes tracked files and can surprise a developer who expected CI to be read-only. A fresh output directory avoids overwriting the source during processing, but the team must then decide how optimized files become the package’s published assets. In either case, inspect the resulting diff and test the site. PiPic says dimensions remain unchanged and the original format is preserved, but visual review is still sensible for prominent images and fine detail.

4. Budget the shared monthly allowance

In a monorepo, several packages and pipelines may draw from the same CLI tier. Track the number of eligible paths submitted by each job and set a per-run ceiling in the surrounding script. That counter is a planning tool, not a substitute for the service’s own quota accounting: check how the CLI reports actual usage before relying on your estimate.

Run compression only when the relevant image paths change. A documentation-only edit should not trigger it, and a build that scans every package should not quietly resubmit unchanged files. If several jobs can run at once, coordinate them or budget conservatively; otherwise, concurrent branches can use the shared allowance faster than a single job’s limit suggests.

The free tier’s 100 images per month can suit a small, low-volume workflow. A team with frequent asset changes may need the 5,000-image Pro tier, or a stricter policy for which images are compressed in CI. Don’t treat a tier upgrade as a fix for a script that resubmits the whole repository.

5. Make misses and limits explicit

Log the selected paths and report skipped files by reason: unchanged, unsupported format, too large, or outside the approved package paths. If there are no eligible changes, finish without invoking compression. If a selected file exceeds the service limit, fail clearly or route it to a documented manual process instead of dropping it without notice.

The CLI sends the requested image for compression, and PiPic says it deletes files from its servers immediately after processing. That is useful context for teams evaluating the workflow, but it does not remove the need to follow their own rules for sensitive assets.

Diff-based image compression is a small piece of monorepo asset optimization, not a universal image policy. It reduces unnecessary submissions and makes quota use easier to reason about. The trade-off is that the repository now owns the selection logic: maintain the package boundaries, test how the diff is formed, and review the files the script changes.