web-vitals-auditor
Run Lighthouse audits, diagnose Core Web Vitals regressions, and audit bundles, images, and fonts for performance wins.
Open source Open in the app JSON README (API)
About
Run Lighthouse audits, diagnose Core Web Vitals regressions, and audit bundles, images, and fonts for performance wins.
Details
- Kind
- Plugins
- Topic
- No topic detected
- Publisher
- mohitkale
- Origin
- marketplace
- Category
- ferramentas
- Last push
- 2026-07-28T13:37:25Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
mohitkale/web-vitals-auditor/web-vitals-auditor
README
# Web Vitals Auditor
Ship a faster site with a clear answer to one question: **what should we fix first?**
Web Vitals Auditor is a [Claude Code](https://docs.anthropic.com/en/docs/claude-code/getting-started) plugin for practical performance work. It runs a repeatable Lighthouse baseline, turns the result into a ranked fix list, and checks the common causes of slow pages: JavaScript bundles, images, and fonts.
It is designed for the moment after “the score dropped” and before a team spends a day chasing the wrong optimization.
> This is a Claude Code plugin, not a browser extension and not a Claude.ai chat attachment. It runs on the developer machine where Claude Code can inspect the project and, when you ask, run an audit.
## The outcome
After one focused pass, you have:
- Desktop and mobile Lighthouse JSON reports you can keep with the work.
- A prioritized explanation of LCP, CLS, TBT, and (when present) INP findings.
- Static checks for bundle bloat, image delivery, and font loading.
- A sensible starting performance budget for CI.
```mermaid
flowchart LR
A["Production URL or static build"] --> B["Lighthouse\ndesktop + mobile"]
B --> C["Core Web Vitals\nranked by impact"]
A --> D["Bundle, image, and\nfont checks"]
C --> E["Smallest high-value\nfixes first"]
D --> E
E --> F["Re-run audit and\nprotect with a budget"]
```
## When it pays off
Use it before a release, after a performance regression, or when a page feels slow but the cause is unclear.
| If you see | Start here | What you get |
|---|---|---|
| A slow page or falling Lighthouse score | `lighthouse-audit` | Mobile and desktop baseline with saved evidence |
| A Lighthouse JSON report | `vitals-diagnose` | Ranked fixes tied to report audits |
| A suspiciously large build | `bundle-analyze` | Duplicate and oversized dependency leads |
| LCP or CLS issues around media | `image-audit` | Missing dimensions, modern formats, lazy-loading, preload leads |
| Text flash or render blocking | `font-audit` | `font-display`, loading, weight, and format leads |
## Install
### Option 1: Install from the GitHub marketplace (recommended)
This makes the plugin available in future Claude Code sessions. From any terminal, run:
```bash
claude plugin marketplace add mohitkale/web-vitals-auditor
claude plugin install web-vitals-auditor@web-vitals-auditor-marketplace
```
Restart Claude Code, then enter `/plugin` to confirm it is enabled.
### Option 2: Use a downloaded ZIP for one session
Download the release asset, then point Claude Code at it. The same command works on macOS, Windows (PowerShell, Git Bash, or WSL), and Linux; change the path for your download folder.
```bash
claude --plugin-dir "/path/to/web-vitals-auditor-1.1.0.zip"
```
For an unpacked source folder instead:
```bash
claude --plugin-dir "/path/to/web-vitals-auditor"
```
`--plugin-dir` loads the plugin for that session. It does not permanently install it. Use the marketplace route when you want automatic updates and a persistent install.
### Windows notes
- Install and run Claude Code in a supported shell. Anthropic documents Windows support through WSL or Git Bash.
- Use a quoted Windows path in PowerShell, for example: `claude --plugin-dir "C:\Users\you\Downloads\web-vitals-auditor-1.1.0.zip"`.
- For local audits, Chrome or Chromium must be available to Lighthouse, and Node.js 18+ must be on `PATH`.
### macOS notes
- Use Terminal, iTerm, or another shell with Claude Code and Node.js 18+ available.
- Chrome or Chromium is required only when running a Lighthouse audit. The report-reading and static inspection skills can still help without it.
## Your first useful audit
Open Claude Code in the project you want to inspect and run:
```text
/web-vitals-auditor:doctor
/web-vitals-auditor:lighthouse-audit https://your-production-or-staging-url.example
```
Then turn the mobile report into a decision list:
```text
/web-vitals-auditor:vitals-diagnose ./lighthouse-mobile-YYYY-MM-DDTHHMMSS.json
```
The audit never crawls beyond the URL you provide. Run it against a production build or staging site, not a framework development server.
## What Claude does for you
| Command | Best for | Result |
|---|---|---|
| `/web-vitals-auditor:doctor` | Before the first audit | Confirms Node, Lighthouse, Chrome/Chromium, and framework markers |
| `/web-vitals-auditor:lighthouse-audit <url>` | A page-level baseline | One desktop and one mobile JSON report with an actionable summary |
| `/web-vitals-auditor:vitals-diagnose <report>` | Deciding what to fix | Evidence-led priority list from the Lighthouse report |
| `/web-vitals-auditor:serve-audit <static-build-dir>` | A static production build | Serves a short-lived local preview, audits it, then stops it |
| `/web-vitals-auditor:bundle-analyze <build-dir>` | JavaScript bloat | Leads for duplicates, large packages, and tree-shaking misses |
| `/web-vitals-auditor:image-audit [source-dir]` | LCP and CLS image risks | File and line-level image delivery checks |
| `/web-vitals-auditor:font-audit [source-dir]` | Render blocking and font flashes | Font loading and unused-weight checks |
| `/web-vitals-auditor:budget-generate [site-type]` | Keeping a win | A mobile-first Lighthouse CI budget file |
| `/web-vitals-auditor:full-audit <url> [build-dir]` | Release readiness | One opt-in combined report; no source changes |
Two focused agents are also available when the task calls for a deeper read:
- `perf-forensics` traces a regression across a report, bundle output, images, fonts, and source.
- `vitals-interpreter` reads a Lighthouse JSON report without running commands.
## A typical result
```text
Mobile: performance 58 [warn]
1. TBT 780 ms [fail]
Main cause: long main-thread script work.
Next move: inspect the largest shipped modules with bundle-analyze.
2. LCP 3.9 s [warn]
Main cause: the first-fold image is not preloaded and is larger than needed.
Next move: ship a responsive AVIF/WebP source and preload the LCP image.
3. CLS 0.18 [warn]
Main cause: image space is not reserved.
Next move: add intrinsic width and height (or an aspect ratio).
```
This is lab data, not a substitute for field data. Lighthouse navigation runs commonly report INP as `n/a`; use CrUX or real-user monitoring to understand interaction responsiveness for actual visitors.
## Privacy and safety
- The plugin is local files: skills, commands, agents, and small Node.js hooks. It does not operate analytics, telemetry, or a plugin-owned backend.
- Startup hooks only look for framework and audit markers in the current working directory. They add a short local context note when they find one.
- Network activity happens only when you explicitly audit a URL or allow `npx` to fetch a pinned audit tool.
- It does not read `.env` values, modify application code, deploy, or run destructive build commands.
Read the full [privacy policy](PRIVACY.md).
## Supported setup
- Claude Code 2.1+ (the package was validated with Claude Code 2.1.206).
- Node.js 18+ and `npx` for Lighthouse and local static-server audits.
- A supported Chrome or Chromium installation for Lighthouse runs.
- Any framework is welcome. The automated hints recognize Next.js, Vite, Nuxt, Webpack, Lighthouse CI, and common static build folders.
## Release and updates
Each release is versioned in the plugin manifest and published as a GitHub release ZIP that Claude Code can load directly. The release checklist validates the manifest, marketplace catalog, hooks, and fixture behavior before a tag is created.
For development from a clone:
```bash
claude plugin validate .claude-plugin/plugin.json
claude plugin validate .claude-plugin/marketplace.json
node tests/run.js
```
## Limitations
- Lighthouse is a single lab run, so use repeated CI runs and field data before making business-level claims.
- `serve-audit` is for static output with an `index.html`; it deliberately does not pretend a Next.js `.next` directory is a static site.
- Bundle, image, and font checks are static inspections. They cannot see assets injected later by a CMS, CDN, or third-party script.
## License
MIT. See [LICENSE](LICENSE).