A local staging workflow for Strapi and Contentful image uploads

A headless CMS does not make oversized source images smaller just because they now live in a media library. Uploading the originals can add avoidable weight to asset storage and delivery. A useful middle step is to stage a copy of the media locally, compress it, inspect the results, then upload the approved files to Strapi or Contentful.

PiPic's open-source @pipic/cli gives that step a place in a developer workflow. It compresses images, and can replace files in place or write to a fresh directory. For a first pass, the fresh-directory route is the safer choice: the original files remain untouched while you check the output and decide what belongs in the CMS.

Start with a controlled staging folder

Keep three groups distinct: source originals, compressed candidates, and files approved for upload. The original folder is your rollback point. The candidate folder is disposable. The approved set is what goes into the CMS media library. This separation prevents a rushed compression run from becoming an irreversible edit to the only copy of a campaign shoot or product catalog.

Install @pipic/cli from npm using its documented instructions, then use its documented workflow to process a prepared folder into a fresh destination. The CLI supports developer workflows, but exact invocation details should come from its current documentation rather than a copied command that may not match your setup. PiPic supports JPG, PNG, WebP, and AVIF compression. Its browser tool's stated limit is 100 images per batch and 8 MB per image; do not assume that browser limit describes every CLI workflow.

Review before the CMS upload

1. Choose a representative sample. Include images with fine texture, transparency, gradients, and small text if those appear in the project. Compare the compressed candidates with their sources at the display sizes your site uses.
2. Check names and extensions. Keep a stable mapping between source files and candidates. PiPic describes same-format output, which helps avoid extension changes during this step. That matters when filenames are referenced in scripts or maintained in a separate content workflow. The trade-offs behind preserving extensions are covered in this comparison of in-format compression and format conversion.
3. Approve the whole set. Look for visual defects and confirm that the expected files are present. If an image does not pass review, use the original instead. Compression is not a substitute for checking the asset in context.
4. Upload approved candidates. Upload the reviewed files to the Strapi or Contentful media library, then use those assets when creating or updating content. Keep the source folder outside the upload path so it cannot be selected accidentally.

Fit the process to each CMS

For Strapi asset prep, make the compressed output the deliberate handoff between the design or content team and the media-library upload. For Contentful image optimization, use the same boundary: process locally first, then upload the approved source asset. Neither workflow requires changing the CMS itself. The practical gain is control over what enters the library, not a special integration between PiPic and either platform.

If a delivery layer later creates resized or transformed renditions, local compression only changes the uploaded source. Check the actual delivered image as well as the file you staged. A smaller source is useful, but it does not by itself prove that every page uses the right rendition or that a transformation has not changed the visual result.

Set limits and privacy expectations

PiPic says its CLI free tier covers 100 images per month, with a Pro tier covering 5,000. Count recurring imports before making compression a required release step; a large catalog migration can exceed a monthly allowance even if routine editorial uploads do not. For an occasional batch, local staging also makes it easy to pause and review rather than upload automatically.

The CLI sends the image being compressed over the network. PiPic says it sends no telemetry and that images are deleted immediately after processing. That is useful context, not a reason to skip your own data-handling review. Check whether your organization permits those assets to be processed by an external service before including client, embargoed, or otherwise sensitive media. For a closer look at the questions developers should ask about CLI telemetry and retention, see this review of command-line image tools.

Finally, preserve a simple rollback path. Keep originals until the CMS assets have been checked in their intended pages, and avoid overwriting source files until the team has accepted the result. This adds a review step and a second local folder to manage. In return, Strapi and Contentful receive a deliberate set of compressed assets rather than whatever happened to be in a raw upload directory.