imgcrush

Interactive CLI to compress PNG/JPG images to WebP with smart quality tiers and automatic source code reference updates.

Quick start

# Run in any frontend project — no install needed
npx imgcrush

# Or install globally
npm install -g imgcrush
imgcrush

What it does

1. Scans your image directory and categorizes every image by type
2. Interviews you about quality settings, paths, and options
3. Converts PNG/JPG → WebP into a sibling images-compressed/ directory
4. Updates all source code references automatically
5. Verifies with your build command

Original images are never touched.

Quality tiers (smart defaults)

| Tier | Default | Files | |---|---|---| | Large / maps / glows | q 80 | Files with map, glow, bg, background, overlay, gradient in the name | | UI cards / screens | q 85 | Everything else | | Icons / badges / logos | q 90 | Files with badge, icon, logo, store, achievement in the name |

All tiers are configurable during the interview.

Requirements

One of:

• cwebp — brew install webp (recommended, handles alpha correctly)
• sharp — already installed as a project dependency (npm install sharp)

Node.js ≥ 18.

Files automatically skipped

| Pattern | Reason | |---|---| | *.svg | Already vector | | *.webp | Already WebP | | *.webm, *.mp4 | Video | | *.json | Lottie animations | | icon-192.png, icon-512.png, favicon.png | PWA icons — WebP has poor browser support for favicons | | .png files that contain SVG data | Detected by reading file header |

Interview flow

◆ Image directory to compress?         → public/images
◆ Output directory name?               → images-compressed
  Scan results ──────────────────────
  42 images to convert  (38.4MB)
    7 large/maps/glows
    28 UI cards/screens
    7 icons/badges/logos
  12 files will be skipped
  ────────────────────────────────────
◆ Quality settings?                    → Smart defaults / Single / Custom per tier
◆ Update image paths in source code?   → Yes
◆ Source code directory to scan?       → src/
◆ Verify with a build after?           → npm run build / custom / skip
◆ Dry run first?                       → No
◆ Proceed?                             → Yes

Rerunning for new images

imgcrush only touches files that need converting — if you add new images later, just run it again. Existing .webp files in the output directory are not regenerated (they are already skipped by the scanner).

Adding to a project as a script

{
  "scripts": {
    "optimize-images": "npx imgcrush"
  }
}