next-doctor

A CLI tool that scans your Next.js project and reports issues, bad patterns, and security risks, summarized into a health score out of 10.

Installation and Usage

Run directly with npx (no installation required):

npx next-doctor              # Run full scan
npx next-doctor --score      # Show health score only
npx next-doctor --json       # Output results as JSON (for CI/CD)
npx next-doctor --rule seo   # Run a specific category
npx next-doctor --vibe-check # Detect AI-generated code patterns

What It Checks

| Category | Description | | ------------- | --------------------------------------------------------- | | Migration | Pages Router usage, getServerSideProps, outdated patterns | | Performance | img tag usage, Google Fonts issues, missing loading.tsx | | Server/Client | Overuse of "use client", inefficient useEffect fetching | | Caching | Missing caching strategies, improper fetch usage | | Security | Exposed secrets, missing headers, unvalidated API routes | | SEO | Missing metadata, robots.txt, sitemap, lang attribute | | Structure | Missing error.tsx, not-found.tsx, incorrect file casing | | Accessibility | Missing alt attributes, ARIA labels | | Dependencies | Outdated or heavy packages | | Config | TypeScript setup, strict mode, ESLint, Turbopack | | Vibe Check | Detects AI-generated code patterns |

Health Score

The project starts at 10 and points are deducted based on detected issues:

• Critical: -2 points
• Warning: -0.5 points
• Suggestion: no impact

Score Interpretation

| Score | Status | | ----- | ---------- | | 10 | Perfect | | 8–9 | Healthy | | 6–7 | Fair | | 4–5 | Needs Work | | 2–3 | Poor | | 0–1 | Critical |

Vibe Check

Analyzes the codebase for patterns commonly associated with AI-generated code.

• Score range: 0 to 10
• 0 indicates fully human-written code
• 10 indicates fully AI-generated code with no human refinement

Key Features

• Read-only; does not modify project files
• Supports both JavaScript and TypeScript
• Compatible with App Router and Pages Router
• Exits with code 1 when critical issues are detected (useful for CI/CD pipelines)

License

MIT