web-audit-agent

A CLI that crawls a web app (Next.js/React, Angular, or plain HTML), audits every page for performance (Lighthouse), accessibility (axe-core), and SEO issues, then uses Gemini to generate a plain-language explanation and a code fix for each issue — grouped by category and severity in the terminal, with an optional Markdown report file.

Requirements

• Node.js >= 18
• (Optional) A GOOGLE_API_KEY environment variable, only needed to generate AI explanations and code fixes for each issue. Without it, the tool still runs the full audit — Lighthouse performance, axe-core accessibility, SEO checks, and source file mapping — and prints a complete report; each issue's explanation is simply marked unavailable.

Usage

npx web-audit-agent --url http://localhost:3000 --framework nextjs-react --output report.md

| Flag | Required | Description | | -------------- | -------- | ----------------------------------------------------------------------------------------------- | | --url | no | Target URL to audit. If omitted, checks common local dev ports (3000 for Next.js, 4200 for Angular). | | --framework | no | nextjs-react | angular | html. If omitted, auto-detected from angular.json, next.config.*, or package.json dependencies in the current directory. | | --output | no | Path to also save the report as a Markdown file. |

Example

cd my-nextjs-app
GOOGLE_API_KEY=... npx web-audit-agent --output audit-report.md

This auto-detects the framework from my-nextjs-app's package.json, checks http://localhost:3000, crawls up to 20 same-origin pages (depth 2), analyzes each one, and prints a categorized report to the terminal — plus audit-report.md if --output is given.

GOOGLE_API_KEY can be omitted entirely — the audit still runs and the report still generates; you'll see one notice at startup ("No GOOGLE_API_KEY found — running audit without AI explanations. See README to enable them.") and each issue's explanation/code fix will be marked unavailable instead of AI-generated.

What it checks

• Performance — Lighthouse performance score, Largest Contentful Paint, Cumulative Layout Shift.
• Accessibility — axe-core violations (rule, impact, selector, HTML snippet, WCAG rule where applicable).
• SEO — missing/duplicate <title>, meta description, canonical tag, Open Graph tags.

Source file mapping

When the target is running against a local dev server (the default), each issue's report entry also includes a file: line pointing at the project source responsible for it:

• Next.js/React — resolved from React's dev-mode debug source (the same data React DevTools uses to jump to source), so it includes an exact line number.
• Angular — resolved by mapping the owning component (via Angular's ng debug API) back to its .ts/template file on disk; a line number is included on a best-effort basis.
• Plain HTML — resolved by matching the crawled URL to a file under the project root (or public/dist/build/src).

This relies on dev-mode debug metadata that production builds strip, so it's only available when auditing a local dev server, not a deployed production URL.

License

MIT