Wiring pre-build image optimization into Astro and Next.js

The static asset problem in modern frameworks

Static site generators deliver fast pages by rendering HTML at build time. Astro and Next.js handle code bundling efficiently. Yet image assets often get overlooked. Developers drop full-resolution PNG, JPG, WebP, and AVIF files into static asset folders. The framework copies them straight into final build exports without reducing file size.

Framework-specific image components can optimize files during server runtime or demand custom server configurations. For static exports—such as running next export or generating static Astro builds—runtime image processing is not an option. Compression must happen before deployment. Handling asset optimization manually through desktop tools or browser interfaces creates friction. Teams forget to run images through compression tools, leading to bloated deployments.

Automating image optimization directly within npm scripts solves this problem. By linking terminal compression tools to build commands, image assets shrink automatically whenever you prepare a static release. For a detailed breakdown on managing folder structures and format safety, see our analysis on optimizing raw asset directories before static site deployment.

Wiring @pipic/cli into package lifecycle scripts

The open-source command-line tool published on npm as @pipic/cli provides a straightforward way to process images inside terminal environments. It supports JPG, PNG, WebP, and AVIF formats while preserving original dimensions and keeping file formats intact. The CLI sends only the target images to the processing endpoint, collecting zero system telemetry. Files are deleted from servers immediately after processing finishes.

To integrate terminal compression into an Astro or Next.js project, add the CLI package to your development dependencies:

npm install -D @pipic/cli

Once installed, configure your package.json file to execute a pre-build hook. Standard npm behavior automatically triggers any script prefixed with pre prior to running the main script. For instance, running npm run build will execute prebuild first.

Add the pre-build hook to your project configuration:

"scripts": {
  "prebuild": "pipic public/images",
  "build": "astro build"
}

In Next.js, the setup follows the exact same pattern:

"scripts": {
  "prebuild": "pipic public/static-assets",
  "build": "next build"
}

When the pre-build command runs, the tool processes images in place or targets specified subdirectories. Format choices remain untouched: PNG files output as PNG, and AVIF files output as AVIF. The relative paths referenced inside components remain intact, preventing broken assets during static HTML rendering. Readers interested in terminal flag options and setup steps can review automating static asset compression from the command line.

Architectural trade-offs and CI quotas

Integrating network-dependent asset steps into local build chains introduces explicit trade-offs. Engineers must weigh pipeline speed, execution limits, and deployment workflows before locking pre-build commands into continuous integration server scripts.

1. Rate limits and quota management

The free tier for @pipic/cli allows processing for up to 100 images per month. Upgrading to a Pro account expands this allowance to 5,000 images per month. If a continuous integration pipeline triggers npm run build on every code commit across a large team, the free tier budget will exhaust rapidly.

2. Selective build hooks vs manual triggering

To avoid hitting monthly thresholds needlessly during minor code changes, isolate asset compression from standard commit checks. Instead of running pipic on every standard build trigger, decouple asset processing into a standalone npm script:

"scripts": {
  "compress:assets": "pipic public/images",
  "build": "astro build"
}

Developers run npm run compress:assets explicitly when adding new media to raw asset directories. The compressed files are then committed directly to version control. Build servers execute npm run build without re-running compression over unedited files, saving monthly quota limits and shortening continuous integration compile times.

3. Processing speed and network dependencies

Every image send requires network transport and server processing time. For large media folders, executing a full compression sweep adds time to build runs. Because files are deleted immediately after compression, local caching strategies or selective directory targets should be configured to prevent unnecessary network calls for assets that have already been optimized.

Evaluating the pre-build stack

Using npm lifecycle hooks alongside command-line tools offers a structured mechanism for controlling media asset footprints. Static site exports stay lightweight without requiring developers to manually manipulate images or write complex framework plugins. Setting up dedicated build scripts ensures file paths remain stable, network telemetry stays clear, and public assets remain lean for end users.