@lxgicstudios/img-audit

Audit images on any website or local directory for performance problems. Finds oversized files, unoptimized formats, missing width/height attributes (CLS), missing alt text, and missing lazy loading. Reports potential savings from format conversion.

Zero dependencies. Just Node.js built-ins.

Install

npm install -g @lxgicstudios/img-audit

Or run directly with npx:

npx @lxgicstudios/img-audit https://example.com

Usage

# Audit images on a live website
img-audit https://example.com

# Scan a local directory
img-audit ./public/images --dir

# Custom size threshold (flag images over 100KB)
img-audit https://example.com --max-size 100

# JSON output for CI/CD
img-audit https://example.com --json

Features

• Detects oversized images that slow down your site
• Flags unoptimized formats (BMP, TIFF) that shouldn't be on the web
• Catches missing width/height attributes that cause Cumulative Layout Shift (CLS)
• Finds images without alt text (accessibility and SEO issue)
• Identifies images missing lazy loading
• Detects large data URIs that should be separate files
• Estimates potential savings from WebP/AVIF conversion
• Scans live websites or local directories
• Shows format breakdown with visual bar chart
• Scores your image setup out of 100
• Zero external dependencies

Options

| Option | Description | Default | |--------|-------------|---------| | --url | Treat argument as a URL | Auto-detected | | --dir | Treat argument as a local directory | Auto-detected | | --max-size <kb> | Flag images larger than this (KB) | 200 | | --json | Output results as JSON | false | | --timeout <ms> | Request timeout in milliseconds | 15000 | | --help | Show help message | |

What It Checks

| Check | Severity | Why It Matters | |-------|----------|---------------| | Missing alt text | Error | Accessibility and SEO ranking factor | | Missing dimensions | Warning | Causes CLS (Core Web Vital) | | Oversized files | Warning | Slows page load | | BMP/TIFF format | Error | Not suitable for web at all | | Large PNG | Info | Consider JPEG or WebP if no transparency | | Large GIF | Warning | Convert animations to video (WebM/MP4) | | Missing lazy loading | Info | Below-fold images should lazy load | | Large data URIs | Warning | Move to separate files for caching |

Savings Estimates

The tool estimates how much you'd save by converting to WebP:

| Current Format | Typical Savings | |---------------|----------------| | BMP | ~95% smaller | | TIFF | ~90% smaller | | PNG | ~60% smaller | | GIF | ~50% smaller | | JPEG | ~30% smaller |

Example Output

img-audit v1.0.0

Fetching https://example.com...
Found 12 images. Checking each...

Score: 68/100

Summary:
  Total images: 12
  With issues: 8
  Missing alt: 3
  Missing dimensions: 5
  Missing lazy loading: 9
  Oversized: 2
  Total size: 1.8MB
  Potential savings: ~580KB (by converting to WebP)

Format Breakdown:
  JPEG     ████████████████████ 8 (67%)
  PNG      ████████ 3 (25%)
  SVG      ██ 1 (8%)

License

MIT - LXGIC Studios