pixcrush is a CLI tool that converts PNG and JPG images to optimized WebP, compresses them, and safely rewrites your source code references so nothing breaks.
Most real-world React and Next.js codebases have hundreds of PNG and JPG images sitting in /public or scattered across the repo. Converting them to modern formats is boring, risky, and time-consuming because you also have to update imports and src paths everywhere.
pixcrush automates this entire migration safely and repeatably.
Run once with no install required:
npx pixcrush .Or install globally for repeated use:
npm install -g pixcrush
pixcrush .If you don't pass any flags, pixcrush will ask you two quick questions before running.
| Flag | Description |
|---|---|
--dry-run |
Preview what would change without writing any files |
--delete-originals |
Delete original .png/.jpg files after conversion |
--quality <number> |
WebP compression quality, 1-100 (default: 80) |
--help |
Show usage info |
--version |
Show version |
# Preview what would happen with no files modified
pixcrush . --dry-run
# Convert images and remove the originals afterwards
pixcrush . --delete-originals
# Convert at a higher quality
pixcrush . --quality 90
# Non-interactive full run
pixcrush . --delete-originals --quality 85- Safe AST rewrites - Uses Babel to update imports and JSX src attributes to .webp without reformatting your files.
- Smart compression - Skips conversion if the resulting WebP would be larger than the original.
- Next.js and Turborepo support - Resolves deeply nested
apps/web/public/paths so absolute image links likesrc="/images/hero.png"are matched correctly. - Orphan detection - Reports any image that is never referenced in your source code.
- Garbage collection - With
--delete-originals, also removes unused orphaned images automatically. - SEO safe - Ignores framework metadata assets like
favicon*.png,apple-icon*.png,opengraph-image*.png, and PWA manifest icons so critical metadata images are never touched.
- Scan - Discovers all
.png/.jpgand.js/.ts/.jsx/.tsxfiles usingfast-glob. - Analyze - Parses your source code with Babel AST to identify which images are actually used.
- Convert - Compresses used images to WebP using
sharp(in-memory, only writes if smaller). - Rewrite - Updates import paths and
srcattributes in your source code. - Report - Prints a summary of images converted, space saved, files updated, and any warnings.
- Dynamic image paths like
`images/${name}.png`are detected and warned about but not automatically rewritten. - CSS files are not parsed. Only
.js,.ts,.jsx, and.tsxare supported.
Run with DEBUG_CRUSH=1 to see verbose path resolution output:
DEBUG_CRUSH=1 pixcrush .Built by Karishma Garg — Product Engineer
- GitHub: @karishma-dev
- Portfolio: karishma.dev
MIT. See LICENSE for details.