@hydration-audit/cli

CLI tool for analyzing JavaScript hydration costs in island-architecture frameworks.

Part of the Hydration Cost Visibility Platform.

Installation

npm install -g @hydration-audit/cli
# or use directly with npx
npx @hydration-audit/cli analyze

Commands

hydration-audit analyze [dir]

Analyze hydration costs in a built project.

# Analyze current directory
hydration-audit analyze

# Analyze a specific build output
hydration-audit analyze ./dist

# CI mode — exit code 1 on errors, GitHub annotations
hydration-audit analyze --ci

# JSON output for tooling
hydration-audit analyze --json

# Watch mode — re-analyze on file changes
hydration-audit analyze --watch

# Custom per-island budget
hydration-audit analyze --budget 30000

# Verbose logging
hydration-audit analyze --verbose

# Custom config file
hydration-audit analyze --config ./my-config.ts

Flags:

| Flag | Description | |---|---| | --json | Output JSON report to stdout (suppresses terminal table) | | --ci | CI mode: exit code 1 on errors, GitHub Actions annotations | | --watch | Watch for changes and re-analyze | | --no-terminal | Suppress terminal output | | --verbose | Enable debug logging | | --config <path> | Path to config file | | --budget <bytes> | Per-island gzip budget in bytes |

hydration-audit init

Scaffold a .hydration-audit.config.ts configuration file.

hydration-audit init
# Creates .hydration-audit.config.ts in the current directory

hydration-audit dashboard [dir]

Launch the interactive web dashboard.

hydration-audit dashboard
hydration-audit dashboard --port 3000
hydration-audit dashboard --report ./custom-report.json

Flags:

| Flag | Description | |---|---| | --port <port> | Port number (default: 4173) | | --report <path> | Path to report JSON file |

CI/CD Integration

GitHub Actions

- name: Check hydration costs
  run: npx @hydration-audit/cli analyze ./dist --ci

When --ci is used:

• Exit code 1 if issues match the configured failOn severity
• GitHub annotations appear on PR files (::error file=...,line=...::message)
• Step summary table written to $GITHUB_STEP_SUMMARY

License

MIT