@hydration-audit/image-auditor

A lightweight, high-performance image and media crawler/auditor for modern web builds. Designed to automatically detect unoptimized assets, incorrect dimension properties, CDN delivery issues, and broken links across your built HTML pages.

Features

• 🔴 External SVG Detection (High Severity): Flags raw SVG links loaded in standard <img> tags, since inlining vector content is much more performant.
• 🟡 Oversized Image Budget (Medium Severity): Warns when an image exceeds a configurable weight limit (default 100 KB).
• 🟡 Dimension Mismatch (Medium Severity): Compares natural dimensions of files against HTML-declared width and height properties, warning when the natural size is significantly larger than display size (> 1.5x).
• 🔵 CDN Hosting Checks (Low Severity): Identifies if media assets (images, PDFs, videos, etc.) are hosted outside of your configured CDN domains.
• 🔴 Broken Link Auditor (High Severity): Verifies local file presence on disk and makes lightweight remote HEAD requests to verify status code 200 for external resources.

Installation

pnpm add -D @hydration-audit/image-auditor
# or
npm install -D @hydration-audit/image-auditor
# or
yarn add -D @hydration-audit/image-auditor

Configuration

Options can be defined globally in your .hydration-audit.config.ts or passed directly to the API:

export interface ImageAuditorConfig {
  /** Array of prefix URLs pointing to your allowed CDNs */
  cdnUrls?: string[];
  /** Maximum image size in bytes before flagging (default: 102400 / 100 KB) */
  maxSize?: number;
  /** Whether to perform HTTP requests to verify external remote assets (default: true) */
  checkRemote?: boolean;
}

Config Example (.hydration-audit.config.ts)

import { defineConfig } from '@hydration-audit/core';

export default defineConfig({
  // Core configurations...
  cdnUrls: ['https://cdn.mycompany.com/', 'https://images.unsplash.com/'],
  maxSize: 150 * 1024, // 150 KB
  checkRemote: true
});

Programmatic API

import { auditImages } from '@hydration-audit/image-auditor';

const report = await auditImages('./dist', {
  cdnUrls: ['https://my-cdn.com/'],
  maxSize: 100 * 1024, // 100 KB
  checkRemote: true
}, 'my-project-name');

console.log(report.totals);

License

MIT