Image Optimization for Web Projects

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

Install Sharp

bun add -d sharp
# or
npm install -D sharp

Quick Start Workflow

1. Benchmark Current State

# 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

bun run scripts/optimize-images.ts --file=public/images/largest-image.png --dry-run

3. Run Full Optimization

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(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();

• Screenshots: quality 80, compression 9
• Photos: quality 85, compression 9
• Icons/logos: quality 90, compression 9 (preserve crispness)

JPEG Optimization

sharp(filePath)
  .jpeg({
    quality: 80,    // 1-100, lower = smaller
    mozjpeg: true,  // Use mozjpeg encoder
  })
  .toBuffer();

• Photos: quality 75-80
• Screenshots: quality 80-85
• Hero images: quality 85

The Optimization Script

scripts/optimize-images.ts

1. Recursively finds all PNG/JPEG images
2. Applies compression settings
3. Overwrites originals (only if smaller)
4. Reports savings per file
5. 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

Next.js Considerations

next/image

1. Faster builds - Smaller source images = faster processing
2. Fallback support - Non-Next.js imports still benefit
3. Reduced storage - Smaller repo size
4. CDN efficiency - Less data to cache/serve

next/image

Workflow Integration

Pre-commit Hook (Optional)

.husky/pre-commit

# Warn if large images are being committed
find public/images -name "*.png" -size +500k -exec echo "Warning: Large image: {}" \;

CI/CD Check

# 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

• PNG: Increase

  quality

  to 85-90
• JPEG: Increase

  quality

  to 85-90

Transparent PNGs Look Wrong

palette: true

.png({ quality: 85, palette: false })

Sharp Installation Issues

brew install vips

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

Summary

1. Install sharp:

   bun add -d sharp

2. Copy optimization script to project
3. Benchmark:

   du -sh public/images/

4. Test:

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

5. Optimize:

   bun run scripts/optimize-images.ts

6. Verify: Check sizes and visual quality
7. Commit: Include optimized images in deployment