@lxgicstudios/cache-audit

Audit HTTP cache headers for any URL. Checks Cache-Control, ETag, Expires, and Vary headers. Detects missing headers, conflicting directives, and suboptimal TTLs. Gives you platform-specific fix suggestions for Nginx, Vercel, and Cloudflare.

Zero dependencies. Just Node.js built-ins.

Install

npm install -g @lxgicstudios/cache-audit

Or run directly with npx:

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

Usage

# Audit a single URL
cache-audit https://example.com

# Crawl and audit all linked resources (CSS, JS, images)
cache-audit https://example.com --crawl

# Get JSON output for CI/CD pipelines
cache-audit https://example.com --json

# Verbose mode shows all headers
cache-audit https://example.com --verbose

Features

• Analyzes Cache-Control directives and TTL values
• Checks ETag presence and format (weak vs strong)
• Validates Expires header dates and detects conflicts
• Audits Vary header for problematic values
• Detects missing cache headers that hurt performance
• Warns about conflicting directives (no-store + max-age, public + private)
• Scores your caching setup out of 100
• Platform-specific fix suggestions for Nginx, Vercel, and Cloudflare
• Crawl mode checks all linked resources on a page
• Zero external dependencies

Options

| Option | Description | Default | |--------|-------------|---------| | --crawl | Crawl and check all linked resources | false | | --json | Output results as JSON | false | | --verbose | Show all headers, not just cache-related | false | | --timeout <ms> | Request timeout in milliseconds | 10000 | | --help | Show help message | |

What It Checks

| Header | What's Checked | |--------|---------------| | Cache-Control | Conflicting directives, TTL analysis, missing immutable | | ETag | Presence, weak vs strong format | | Expires | Valid date, past dates, conflicts with Cache-Control | | Vary | Wildcard usage, User-Agent proliferation | | Last-Modified | Presence for conditional requests | | Pragma | Unnecessary HTTP/1.0 headers | | Age | CDN cache status |

Example Output

cache-audit v1.0.0

Auditing https://example.com...

URL: https://example.com
Status: 200
Score: 72/100

Cache Headers:
  cache-control: max-age=3600
  etag: "5f3b5c6e-1f4"

Issues:
  ⚠ [Cache-Control] max-age=3600 on a static asset without "immutable".
  ℹ [ETag] Weak ETag detected: W/"5f3b5c6e-1f4".
  ⚠ [Vary] Consider adding Accept-Encoding to Vary.

License

MIT - LXGIC Studios