npm package: @lxgicstudios/cache-audit
Description: Audit HTTP cache headers for any URL. Check Cache-Control, ETag, Expires, Vary. Detect missing headers, conflicting directives, suboptimal TTLs. Get platform-specific fix suggestions for Nginx, Vercel, and Cloudflare.
Author: LXGIC Studios
Latest version: 1.0.0

# @lxgicstudios/cache-audit

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

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

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

Or run directly with npx:

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

## Usage

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