Move image compression out of your static-site build

When a static-site build feels slow, image processing is an easy suspect. A generator may spend time handling assets alongside templates, styles and code. Moving compression into a separate, explicit step makes that work easier to see and control. It does not guarantee a faster end-to-end run: PiPic’s CLI sends the requested images for compression, so network and service time still count.

The useful distinction is where the work happens in your pipeline. Instead of letting a bundler repeatedly transform source images as part of its build, run compression before the generator. Then measure both the compression step and the full run. If image handling was a real bottleneck, the build stage may get shorter; whether the overall pipeline improves depends on your files, build setup and connection.

Make the sequence explicit

Start with a small test branch. Keep the original assets in a source directory, and choose a separate output directory for compressed files. PiPic’s CLI supports writing to a fresh directory or replacing files in place atomically. A separate directory is easier to review and roll back. In-place replacement is simpler, but it makes source control and recovery choices more important.

Install the open-source CLI published as @pipic/cli using its current documentation. Do not guess at command flags or invent a wrapper around an undocumented invocation. In your package scripts, put the documented compression command in an npm prebuild script and the static generator’s normal command in build. That gives the team a visible order: prepare images, then build the site.

Point the generator at the compressed output only after checking how your project resolves asset paths. If it still reads the original folder, the compression step may run without changing the generated site. If both the CLI and generator optimize the same files, you may pay for duplicate work. Where the generator allows it, avoid running a second image-optimization pass on already prepared assets; verify output rather than assuming that configuration has taken effect.

Set boundaries before adding it to CI

PiPic compresses JPG, PNG, WebP and AVIF, with a limit of 8 MB per file. Its CLI tier includes 100 free images per month; the Pro plan covers 5,000 per month. Count the files that the script will actually process, including repeated CI runs. A full-folder pass on every commit can use the allowance quickly, especially if the pipeline has no way to skip unchanged assets.

That is a trade-off, not a reason to compress less carefully. Decide whether the pipeline should process the complete image set or only assets changed since the previous run. The latter needs reliable change tracking and is project-specific; it is not a PiPic feature to assume. If your build cannot identify changed assets safely, use a predictable full pass and check the monthly count before making it mandatory.

The CLI is designed for scripts and CI to run unattended after sign-in once. Keep whatever authentication material your setup requires out of the repository and limit access according to your organization’s normal CI practices. PiPic says the CLI sends the image requested for compression, not information about the repository or machine. That does not remove your own duty to decide whether an image is appropriate to send for processing.

Check output and timing

Run the step on representative assets before merging it. Compare file sizes, dimensions and visual appearance, including transparency where it matters. PiPic keeps the same format and dimensions, and says its defaults aim for near-invisible quality loss; inspect fine edges, gradients and photographic detail in your own output. Keep source files available until the review is complete.

Record three timings: compression alone, the generator build alone, and the full sequence. Repeat with the same input set. A shorter generator phase is useful, but it is not a win if compression adds more time than it removes. Local development may benefit from running the image step only when assets change, while CI can run it when image inputs are updated. That split avoids making every code-only edit wait on image processing.

For occasional batches, the browser workflow may be simpler; recurring scripted work is where a CLI can fit. The practical choice depends on cadence, quotas and whether the team wants a repeatable pipeline, as discussed in choosing between browser and CLI compression by workflow. Treat the npm prebuild image script as a measured boundary, not a magic speed switch: keep inputs clear, preserve a recovery path, and judge it by the complete build time.