What is Vercel Doctor?
Reduce your Vercel bill by scanning your Next.js codebase for costly patterns.
Vercel Doctor is a specialized health check tool for Next.js projects deployed on Vercel. It scans your codebase for patterns that inflate your bill — function duration, uncached routes, unoptimized images, and more — then gives you a score out of 100 with actionable fixes. Guidance adapts to your detected Next.js major version.
Quick Start
Run on your project
npx -y vercel-doctor@latest .That's it. No install, no config. It scans your codebase and outputs a score with diagnostics.
Fix the issues
Each diagnostic includes a help message explaining what to change and why. Fix the highest-impact rules first — errors before warnings.
Re-run to verify
npx -y vercel-doctor@latest . --diffUse --diff on feature branches to scan only the files you changed.
What it checks
Vercel Doctor runs two analysis passes in parallel:
- Billing lint — AST-based and pattern-based rules that detect costly Next.js and Vercel patterns
- Dead code detection — finds unused files, exports, and types that bloat your bundle and slow cold starts
Rule categories
| Category | Rules | What it catches |
|---|---|---|
| Function Duration | 3 | Sequential awaits, blocking logging, non-parallel I/O |
| Caching | 6 | force-dynamic, missing cache policies, no-store fetches, side effects in GET handlers |
| Invocations | 2 | Client-side fetching in pages, aggressive link prefetching |
| Image Optimization | 4 | Global unoptimized, missing sizes, broad remote patterns, SVG without unoptimized |
| Platform | 8 | Edge heavy imports, cron jobs, Bun runtime, Fluid Compute, deploy archive, Turbopack cache |
| Dead Code | 4 | Unused files, exports, types, and duplicates |
Features
- Zero config — runs out of the box on any Next.js project
- Monorepo support — auto-detects workspaces, lets you pick which projects to scan
- Diff mode — scan only changed files on feature branches
- Reports — generate markdown reports and AI-compatible fix prompts for Cursor, Claude, and Windsurf
- Scoring — 0–100 score with Great / Needs work / Critical labels
- CI-friendly — non-interactive mode for automated pipelines
- Configurable — ignore rules or files via config file
- AI skill — install as a skill for Claude Code, Cursor, Codex, and more
- Version-aware guidance — recommendations adjust to your detected Next.js major version
Last updated on