Tax Zero

Image Optimization Guide ​

This guide explains how to optimize images in the Tax Zero VitePress project for better performance and faster loading times.

Quick Start ​

Install Dependencies ​

bash
npm install

Optimize All Images ​

bash
npm run optimize:images

Build with Optimized Images ​

bash
npm run optimize:images:prod

Optimization Features ​

1. Automated Compression ​

  • JPEG: Quality 80, progressive loading
  • PNG: Maximum compression (level 9)
  • WebP: Quality 80, high effort compression
  • AVIF: Quality 80, high effort compression

2. Responsive Image Generation ​

Automatically creates multiple width variants:

  • 400w for mobile
  • 600w for tablets
  • 800w for desktop
  • 1200w for large screens

3. Build-time Optimization ​

Images are automatically optimized during the build process using:

  • vite-plugin-imagemin for lossless compression
  • sharp for high-quality image processing

Manual Image Optimization ​

Before Adding New Images ​

  1. Use modern formats (WebP/AVIF) when possible
  2. Compress images using tools like TinyPNG or Squoosh
  3. Create appropriate size variants
  4. Use responsive images in your markup
  • Hero images: 1200px width max
  • Card images: 400-600px width
  • Icons/logos: Use SVG format
  • Thumbnails: 200-300px width

Format Guidelines ​

  • Photographs: Use WebP or AVIF with JPEG fallback
  • Graphics/icons: Use SVG for scalability
  • Logos: SVG or PNG with transparency
  • Backgrounds: WebP or JPEG depending on complexity

Using Optimized Images ​

Responsive Image Markup ​

vue
<picture>
  <source srcset="/images/hero-1200w.webp" media="(min-width: 1200px)">
  <source srcset="/images/hero-800w.webp" media="(min-width: 800px)">
  <source srcset="/images/hero-600w.webp" media="(min-width: 600px)">
  <img src="/images/hero-400w.webp" alt="Hero image" loading="lazy">
</picture>

Lazy Loading ​

Add loading="lazy" to images that are below the fold:

vue
<img src="/images/content-image.jpg" alt="Content" loading="lazy">

Image Dimensions ​

Always specify width and height to prevent layout shift:

vue
<img 
  src="/images/example.jpg" 
  alt="Example"
  width="800"
  height="400"
  loading="lazy"
>

Performance Monitoring ​

Check Image Sizes ​

bash
# List all images with sizes
find docs/public/images -type f -exec ls -lh {} \;

# Check optimization results
npm run optimize:images

Web Vitals ​

The project includes web-vitals package to monitor:

  • Largest Contentful Paint (LCP)
  • Cumulative Layout Shift (CLS)
  • First Input Delay (FID)

Troubleshooting ​

Common Issues ​

  1. Build fails: Ensure all dependencies are installed
  2. Large file sizes: Check if images are properly compressed
  3. Slow loading: Verify lazy loading is implemented
  4. Layout shift: Add width/height attributes

Manual Optimization Tools ​

Best Practices ​

  1. Use modern formats (WebP, AVIF) with fallbacks
  2. Implement lazy loading for below-the-fold images
  3. Specify dimensions to prevent layout shift
  4. Compress before upload using the optimization script
  5. Use responsive images for different screen sizes
  6. Monitor performance using Web Vitals
  7. Test on real devices and network conditions

File Organization ​

docs/public/images/
├── hero-1200w.webp    # Large screens
├── hero-800w.webp     # Desktop
├── hero-600w.webp     # Tablets
├── hero-400w.webp     # Mobile
├── logo.svg           # Vector logo
└── icons/             # Icon directory
    ├── feature1.svg
    └── feature2.svg