Image Optimization for Web Projects Optimize images for web performance using modern tools. This skill provides scripts and workflows for compressing PNG and JPEG images while maintaining visual quality. When to Use This Skill Preparing images for production web deployment Reducing page load times Optimizing public/images directories Batch compressing screenshots, watercolors, photos Auditing image sizes before/after optimization Core Tool: Sharp Sharp is the fastest Node.js image processing library, built on libvips. Use it for all image optimization tasks. Install Sharp bun add -d sharp

or

npm install -D sharp Quick Start Workflow 1. Benchmark Current State Before optimization, measure baseline metrics:

Total size and count

du -sh public/images/ find public/images -type f \ ( -name ".png" -o -name ".jpg" -o -name "*.jpeg" \ ) | wc -l

Size by format

find public/images -name ".png" -exec du -ch { } + | tail -1 find public/images \ ( -name ".jpg" -o -name "*.jpeg" \ ) -exec du -ch { } + | tail -1

Top 20 largest files

find public/images -type f \ ( -name ".png" -o -name ".jpg" \ ) -exec ls -la { } \ ; | \ awk '{print $5, $9}' | sort -rn | head -20 | \ awk '{printf "%6.1fMB %s\n", $1/1048576, $2}' 2. Test on Single Image Always test optimization settings on one image first: bun run scripts/optimize-images.ts --file = public/images/largest-image.png --dry-run 3. Run Full Optimization After verifying settings work well: bun run scripts/optimize-images.ts 4. Verify Results

Compare before/after

du -sh public/images/

Visually inspect optimized images

Run production build

bun run build Optimization Settings PNG Optimization Sharp's PNG encoder with palette mode for maximum compression: sharp ( filePath ) . png ( { quality : 80 , // 1-100, lower = smaller compressionLevel : 9 , // 0-9, higher = more compression adaptiveFiltering : true , palette : true , // Use palette for smaller files } ) . toBuffer ( ) ; Recommended settings: Screenshots: quality 80, compression 9 Photos: quality 85, compression 9 Icons/logos: quality 90, compression 9 (preserve crispness) JPEG Optimization Sharp with mozjpeg for superior compression: sharp ( filePath ) . jpeg ( { quality : 80 , // 1-100, lower = smaller mozjpeg : true , // Use mozjpeg encoder } ) . toBuffer ( ) ; Recommended settings: Photos: quality 75-80 Screenshots: quality 80-85 Hero images: quality 85 The Optimization Script Copy scripts/optimize-images.ts to the project's scripts directory. The script: Recursively finds all PNG/JPEG images Applies compression settings Overwrites originals (only if smaller) Reports savings per file Shows total savings summary Script Usage

Dry run (see what would happen)

bun run scripts/optimize-images.ts --dry-run

Test single file

bun run scripts/optimize-images.ts --file = path/to/image.png

Full optimization

bun run scripts/optimize-images.ts Expected Savings Typical results for unoptimized web images: Image Type Typical Savings Screenshots (PNG) 40-60% Photos (JPEG) 20-40% Watercolors (PNG) 30-50% Icons (PNG) 10-30% Next.js Considerations Next.js provides automatic image optimization via next/image . However, optimizing source images still helps: Faster builds - Smaller source images = faster processing Fallback support - Non-Next.js imports still benefit Reduced storage - Smaller repo size CDN efficiency - Less data to cache/serve Keep source images optimized even when using next/image . Workflow Integration Pre-commit Hook (Optional) Add to .husky/pre-commit or git hooks:

Warn if large images are being committed

find public/images -name "*.png" -size +500k -exec echo "Warning: Large image: {}" \ ; CI/CD Check Add to build pipeline:

Fail if images exceed threshold

MAX_SIZE

79

MB

CURRENT

$( du -sm public/images | cut -f1 ) if [ " $CURRENT " -gt " $MAX_SIZE " ] ; then echo "Error: Images exceed ${MAX_SIZE} MB (currently ${CURRENT} MB)" exit 1 fi Troubleshooting Image Quality Too Low Increase quality settings: PNG: Increase quality to 85-90 JPEG: Increase quality to 85-90 Transparent PNGs Look Wrong Ensure palette: true handles transparency correctly. For complex transparency, use: . png ( { quality : 85 , palette : false } ) Sharp Installation Issues On macOS, ensure libvips is available: brew install vips Or let sharp download pre-built binaries: npm rebuild sharp Additional Resources Reference Files references/optimization-guide.md - Detailed compression algorithms and format comparison references/sharp-api.md - Complete sharp API reference for images Scripts scripts/optimize-images.ts - Production-ready optimization script Context Discipline Do not read optimized images back into context. The script outputs a summary table with file sizes, savings percentages, and totals. Ask the user to visually inspect results if quality verification is needed. Even optimized images can be large enough to fill the context window when processing many files. Summary Install sharp: bun add -d sharp Copy optimization script to project Benchmark: du -sh public/images/ Test: bun run scripts/optimize-images.ts --dry-run Optimize: bun run scripts/optimize-images.ts Verify: Check sizes and visual quality Commit: Include optimized images in deployment