npm package: @lxgicstudios/img-audit
Description: Audit images for web performance: detect oversized files, unoptimized formats, missing width/height attributes causing CLS, missing alt text, and missing lazy loading. Scan live URLs or local directories. Zero dependencies.
Author: LXGIC Studios
Latest version: 1.0.0

# @lxgicstudios/img-audit

[![npm version](https://img.shields.io/npm/v/@lxgicstudios/img-audit.svg)](https://www.npmjs.com/package/@lxgicstudios/img-audit)
[![license](https://img.shields.io/npm/l/@lxgicstudios/img-audit.svg)](https://github.com/lxgicstudios/img-audit/blob/main/LICENSE)
[![node](https://img.shields.io/node/v/@lxgicstudios/img-audit.svg)](https://nodejs.org)

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

```bash
npm install -g @lxgicstudios/img-audit
```

Or run directly with npx:

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

## Usage

```bash
# 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](https://lxgicstudios.com)