frontend-doctor

v1.3.0

Published

2 months ago

CLI tool that analyzes frontend projects and detects common issues

0High
0Medium
0Low

inspectra

frontend cli analyzer dependencies circular-imports bundle-size code-quality

Frontend Doctor

CLI tool that analyzes frontend projects and detects common issues. Get a health score for your codebase.

Features

Core Analysis

Unused dependencies detection
Circular import detection
Large asset identification
Node.js version compatibility
Outdated package detection

Advanced Analysis

Bundle size impact analysis
React anti-pattern detection
Dead export detection
Dependency health scoring
Git-aware change impact
Environment variable auditing
Performance budget tracking
TypeScript strictness audit
Duplicate code detection
Import cost analysis (detect heavy packages)
Security vulnerability scanning (npm audit integration)
Accessibility linting (JSX/HTML a11y checks)
Bundle size treemap (dependency size breakdown)
Lighthouse integration (performance, a11y, SEO scores)
ESLint/Prettier config audit (conflict detection)
Package.json audit (missing fields, invalid semver, best practices)

Reporting & Tracking

PDF report generation with visual health gauge
HTML report generation (single-file, responsive)
Markdown report generation (GitHub PR friendly)
SARIF output for GitHub Code Scanning integration
SVG health badge generation
Score trend tracking across scans
Diff reports comparing to previous scan
Custom branding (title & logo) via config
Auto-open reports in default viewer
Team dashboard — aggregate scores across repos

DX & Automation

Watch mode — re-scan on file changes
Parallel rule execution for faster scans
Incremental scanning (skip unchanged files)
Interactive fix mode — auto-fix issues post-scan
Config init wizard (frontend-doctor init)
GitHub Actions workflow generation
Slack/Discord webhook notifications
GitHub PR comment integration
CI threshold mode (--threshold 80)
Branch comparison (compare main)
Plugin system — write custom rules as npm packages
Monorepo support — scan all workspace packages
VS Code extension scaffolding
Rule ignore comments (// frontend-doctor-ignore-next-line)
Config file support (.frontenddoctorrc, .frontenddoctorrc.json, package.json)

Installation

npm install -g frontend-doctor

Or run directly with npx:

npx frontend-doctor scan

Quick Start

# Basic scan (5 core rules)
frontend-doctor scan

# Full scan (all 21 rules)
frontend-doctor scan --full

# Fast parallel scan
frontend-doctor scan --full --parallel

# Incremental scan (skip unchanged files)
frontend-doctor scan --incremental

# Watch mode — re-scan on changes
frontend-doctor scan --watch

# Interactive fix mode
frontend-doctor scan --fix

# JSON output for CI
frontend-doctor scan --json --ci

# Generate all report formats (including SARIF)
frontend-doctor scan --pdf --html --md --badge --sarif

# Generate reports and auto-open
frontend-doctor scan --pdf --html --open

# Send results to Slack/Discord
frontend-doctor scan --webhook https://hooks.slack.com/services/xxx

# Post as GitHub PR comment (in CI)
frontend-doctor scan --github-comment

# Both reports with custom paths
frontend-doctor scan --pdf ./reports/scan.pdf --html ./reports/scan.html

# CI with threshold — fail if score drops below 80
frontend-doctor scan --ci --threshold 80

# Compare current branch against main
frontend-doctor compare main

# Scan all packages in a monorepo
frontend-doctor monorepo

# 🚀 One command to rule them all — runs ALL rules in parallel + generates PDF, HTML, Markdown, SARIF & badge
frontend-doctor checkup

Commands

Main Commands

| Command | Description | |---------|-------------| | scan | Run core checks (default) | | scan --full | Run all 21 rules | | checkup | Run ALL rules + generate PDF, HTML, Markdown, SARIF & badge | | init | Create config file interactively | | ci-setup | Generate GitHub Actions workflow | | clear-cache | Clear incremental scan cache | | compare <branch> | Compare health score between branches | | dashboard | Generate/view team dashboard | | monorepo / mono | Scan all packages in a monorepo | | vscode-ext | Scaffold a VS Code extension |

Individual Checks

| Command | Description | |---------|-------------| | deps | Unused, outdated, unhealthy dependencies | | circular | Circular import detection | | assets | Oversized static assets | | bundle | Bundle size impact analysis | | react | React anti-patterns and optimization opportunities | | dead-code | Unused exports detection | | health | Dependency maintenance status | | diff | Git-aware change impact analysis | | env | Environment variable audit & secret detection | | budget | Performance budget tracking | | typescript / ts | TypeScript strictness audit | | duplicates / dups | Duplicate code detection | | a11y / accessibility | Accessibility lint checks | | imports | Import cost analysis | | treemap | Bundle composition treemap | | lighthouse / lh | Lighthouse performance audit | | lint-config | ESLint/Prettier configuration audit | | pkg-audit | Package.json best practices audit |

Combo Commands

| Command | Description | |---------|-------------| | security | Security audit + env audit + dependency health | | perf | Bundle + assets + React patterns + duplicates | | quality | TypeScript + dead code + duplicates + circular |

Options

| Option | Description | |--------|-------------| | -p, --path <path> | Path to project (defaults to cwd) | | --full | Run all rules (scan command only) | | --json | Output as JSON | | --pdf [path] | Generate PDF report (optional custom path) | | --html [path] | Generate HTML report (optional custom path) | | --md [path] | Generate Markdown report (optional custom path) | | --badge [path] | Generate SVG health badge | | --open | Auto-open generated report in default viewer | | --parallel | Run rules concurrently for faster scans | | --incremental | Skip rules if source files unchanged | | --fix | Interactive fix mode after scan | | --watch | Watch for file changes and re-scan | | --webhook <url> | Send results to Slack/Discord/custom webhook | | --github-comment | Post results as GitHub PR comment | | --ci | Exit with non-zero code on issues | | --threshold <score> | Fail if health score is below this value | | --sarif [path] | Generate SARIF report for GitHub Code Scanning | | --dashboard [dir] | Save scan result to team dashboard | | -v, --verbose | Verbose output |

Example Output

Frontend Doctor v1.0.0

Scanning /path/to/project...

Compatibility
  ✔ Check Node.js version compatibility
  ✔ Audit TypeScript configuration strictness

Dependencies
  ⚠ Unused dependency: lodash
  ⚠ Heavy dependency in use: moment (67kb)
    → Consider replacing with dayjs (2kb)
  ⚠ Low health score for left-pad: 15/100
    → No updates in 2+ years

Imports
  ✖ Circular dependency: src/a.ts → src/b.ts → src/a.ts
    → Break the cycle by extracting shared code

Assets
  ⚠ hero.png (2.3MB) exceeds 500KB threshold
    → Use imagemin, squoosh, or convert to WebP/AVIF

Performance
  ⚠ Large component: Dashboard.tsx (847 lines)
    → Split into smaller, focused components
  ⚠ Duplicate code (22 lines, 94% similar)
    → Extract to a shared utility function

────────────────────────────────────────
Health Score: 65/100
1 error | 6 warnings | 7 passed
Completed in 3.2s

CI Integration

# Fail on errors (exit code 2), warn on warnings (exit code 1)
frontend-doctor scan --full --ci

# Fail if score drops below 80
frontend-doctor scan --full --ci --threshold 80

GitHub Actions

Auto-generate a workflow file:

frontend-doctor ci-setup

Or add manually:

- name: Run Frontend Doctor
  run: npx frontend-doctor scan --full --ci --github-comment
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    GITHUB_REPOSITORY: ${{ github.repository }}
    PR_NUMBER: ${{ github.event.pull_request.number }}

GitLab CI

frontend-doctor:
  script:
    - npx frontend-doctor scan --full --ci
  allow_failure: true

Configuration

Create a config file interactively:

frontend-doctor init

Or manually create .frontenddoctorrc.json, .frontenddoctorrc, .frontendrc.json, .frontendrc, frontend-doctor.config.json, or add to package.json:

{
  "threshold": 80,
  "rules": ["unused-dependencies", "circular-imports", "security-audit"],
  "plugins": ["frontend-doctor-plugin-custom", "./my-rules.js"],
  "ignore": ["**/test/**", "**/fixtures/**"],
  "budgets": {
    "bundle": 500000,
    "largestAsset": 1048576,
    "dependencies": 75,
    "devDependencies": 50
  },
  "branding": {
    "title": "My Project Health Report",
    "logo": "./assets/logo.png"
  }
}

Config Fields

| Field | Description | |-------|-------------| | threshold | Minimum health score — fail if below this | | rules | Array of rule names to enable (empty = all) | | plugins | npm packages or local files exporting custom rules | | ignore | Glob patterns for files/dirs to ignore | | budgets | Performance budget overrides | | branding.title | Custom title on PDF/HTML reports | | branding.logo | Path to logo image for reports |

Reports

PDF Report

Generate a professional PDF report with:

Visual health score gauge with grade (A-F)
Table of contents
Summary table with color-coded metrics
Score trend chart (requires 2+ scans)
Diff from previous scan
Issue tables grouped by category
Custom branding support
Page numbers in footer

frontend-doctor scan --pdf
frontend-doctor scan --pdf ./my-report.pdf --open

HTML Report

Generate a responsive, single-file HTML report with:

SVG health gauge
Interactive table of contents with anchor links
Score trend line chart
Diff comparison from last scan
Styled issue tables per category
Mobile-responsive layout

frontend-doctor scan --html
frontend-doctor scan --html ./report.html --open

Markdown Report

Generate a GitHub-friendly Markdown report:

frontend-doctor scan --md
frontend-doctor scan --md ./report.md

Health Badge

Generate an SVG badge for your README:

frontend-doctor scan --badge
frontend-doctor scan --badge ./docs/health-badge.svg

Then reference it in your README:

![Health Score](./health-badge.svg)

Trend Tracking

Each scan automatically saves results to .frontend-doctor-history.json in the project root. Reports include a score trend chart when 2+ scans are available.

The diff section shows what changed since the last scan:

Health score delta
Error/warning count changes
Pass count changes

Rules Reference

Core Rules (5)

| Rule | Severity | Description | |------|----------|-------------| | node-version | warning | Node.js version compatibility | | unused-dependencies | warning | Unused packages in package.json | | circular-imports | error | Circular import chains | | large-assets | warning | Files over 500KB | | outdated-packages | warning | Outdated npm packages |

Extended Rules (15)

| Rule | Severity | Description | |------|----------|-------------| | bundle-impact | warning | Bundle size analysis per dependency | | react-patterns | warning | React anti-patterns (large components, missing memo, etc.) | | dead-exports | warning | Exported symbols never imported | | dependency-health | warning | Maintenance status, deprecation, security | | env-audit | error | Missing .env.example, exposed secrets | | performance-budget | warning | Configurable budgets exceeded | | typescript-strict | warning | TS config strictness score | | duplicate-code | warning | Copy-pasted code blocks | | import-cost | warning | Heavy imports impacting bundle size | | security-audit | error | Known vulnerabilities via npm audit | | accessibility | warning | Missing alt tags, ARIA labels, keyboard handling | | bundle-treemap | info | Dependency size breakdown and composition | | lighthouse-audit | warning | Lighthouse performance, a11y, SEO scores | | eslint-config-audit | warning | ESLint/Prettier configuration conflicts | | package-json-audit | warning | Missing fields, invalid semver, best practices |

Health Score

The health score (0-100) is calculated based on issues:

| Severity | Points Deducted | |----------|----------------| | Error | -10 per issue | | Warning | -3 per issue | | Info | -1 per issue |

What Makes Frontend Doctor Unique

Bundle Impact Analysis - See actual bundle cost, not just file sizes
Dependency Health Scoring - Know if your deps are maintained
Git-Aware Analysis - Understand impact of your changes vs base branch
Secret Detection - Find exposed API keys and credentials
React Anti-Pattern Detection - Catch performance issues early
Duplicate Code Detection - Find copy-paste candidates for extraction
TypeScript Strictness Audit - Score your TS configuration
Performance Budgets - Configurable limits with CI integration
Security Vulnerability Scanning - npm audit integration with actionable fixes
Accessibility Linting - Catch missing alt tags, ARIA labels, keyboard issues
Import Cost Tracking - Identify heavy packages dragging down bundle size
Watch Mode - Continuous monitoring during development
Parallel Execution - Faster scans on multi-core machines
Incremental Scanning - Skip unchanged files for near-instant re-scans
Interactive Fix Mode - Auto-apply fixes for common issues
Webhook Notifications - Slack/Discord alerts on scan results
GitHub Actions Integration - Automated PR comments with health reports
CI Threshold Mode - Fail builds when score drops below a target
Branch Comparison - Compare health scores between branches
Plugin System - Write custom rules as npm packages or local files
Monorepo Support - Scan all workspace packages with aggregate scoring
VS Code Extension - Scaffold an extension for inline diagnostics
SARIF Output - GitHub Code Scanning integration
Team Dashboard - Aggregate health scores across multiple repos
Bundle Treemap - Visual breakdown of node_modules size
Lighthouse Integration - Performance, accessibility, and SEO scoring
ESLint/Prettier Audit - Detect config conflicts and missing setup
Package.json Audit - Find missing fields, invalid semver, @types in prod
Rule Ignore Comments - // frontend-doctor-ignore-next-line
Config File Support - .frontenddoctorrc, .frontenddoctorrc.json, or package.json

Webhooks

Send scan results to Slack, Discord, or any webhook endpoint:

# Slack
frontend-doctor scan --webhook https://hooks.slack.com/services/T00/B00/xxx

# Discord
frontend-doctor scan --webhook https://discord.com/api/webhooks/xxx/yyy

# Generic webhook (receives JSON payload)
frontend-doctor scan --webhook https://example.com/hooks/health

Watch Mode

Re-scan automatically when source files change:

frontend-doctor scan --watch
frontend-doctor scan --watch --parallel

Incremental Scanning

Skip rules when source files haven't changed since last scan:

frontend-doctor scan --incremental

# Clear cache when needed
frontend-doctor clear-cache

Interactive Fix

Auto-fix common issues with guided prompts:

frontend-doctor scan --fix

Supported auto-fixes:

Remove unused dependencies (npm uninstall)
Update outdated packages (npm update)
Fix security vulnerabilities (npm audit fix)

Branch Comparison

Compare health scores between your current branch and a base branch:

frontend-doctor compare main
frontend-doctor compare develop --json

Shows: score delta, new issues introduced, and resolved issues.

SARIF Output

Generate SARIF reports for GitHub Code Scanning:

frontend-doctor scan --sarif
frontend-doctor scan --sarif ./report.sarif

Upload SARIF in GitHub Actions:

- name: Run Frontend Doctor
  run: npx frontend-doctor scan --full --sarif ./results.sarif
- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: ./results.sarif

Team Dashboard

Aggregate health scores across multiple projects:

# Save scan results to a shared dashboard directory
frontend-doctor scan --dashboard /shared/dashboard

# Generate the HTML dashboard
frontend-doctor dashboard --path /shared/dashboard --open

Plugin System

Write custom rules as npm packages or local files:

npm install frontend-doctor-plugin-custom

{
  "plugins": ["frontend-doctor-plugin-custom", "./my-local-rules.js"]
}

Plugin format:

export const rules = [
  {
    name: 'my-custom-rule',
    description: 'My custom check',
    severity: 'warning',
    category: 'performance',
    async run(context) {
      return { passed: true, issues: [] };
    },
  },
];

Monorepo Support

Scan all packages in a monorepo (npm/yarn/pnpm workspaces):

frontend-doctor monorepo
frontend-doctor monorepo --parallel
frontend-doctor mono --ci --threshold 70

Shows per-package scores and an aggregate score.

Rule Ignore Comments

Suppress specific warnings in source files:

// frontend-doctor-ignore-next-line
import heavyLib from 'heavy-lib';

// frontend-doctor-ignore-next-line import-cost
import another from 'another-heavy';

// frontend-doctor-ignore-file
// (ignores all issues in this file)

VS Code Extension

Scaffold a VS Code extension for inline diagnostics:

frontend-doctor vscode-ext

This creates a vscode-extension/ directory with a working extension that shows frontend-doctor diagnostics inline in VS Code.

Development

# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/cli.js scan

# Watch mode
npm run dev

Author

Vidhyasagar Thakur

License

MIT