npm install -D nestjs-doctor

Same 50 rules as the CLI, surfaced as inline diagnostics in the editor and in the Problems panel. Files are scanned on open and on save with a configurable debounce.

Use NestJS Doctor: Scan Project from the command palette to trigger a full scan manually.

CI

Pin it as a devDependency:

npm install -D nestjs-doctor

Use --min-score to gate on a minimum health score:

npx nestjs-doctor . --min-score 75

Or wire it into package.json:

{
  "scripts": {
    "health": "nestjs-doctor . --min-score 75"
  }
}

Exit codes: 1 if the score is below threshold, 2 for bad input.

Usage: nestjs-doctor [directory] [options]

  --verbose       Show file paths and line numbers per diagnostic
  --score         Output only the numeric score (for CI)
  --json          JSON output (for tooling)
  --report        Generate an interactive HTML report (--graph also works)
  --min-score <n> Minimum passing score (0-100). Exits with code 1 if below threshold
  --config <p>    Path to config file
  --init          Set up the /nestjs-doctor skill for AI coding agents
  -h, --help      Show help

AI Coding Agents

Ships with skills for popular AI coding agents. Run --init to auto-detect installed agents and install the nestjs-doctor skill for each one:

npm install -D nestjs-doctor
npx nestjs-doctor --init

A project-level fallback is always written to .agents/nestjs-doctor/. Commit it so every contributor gets the skill automatically.

Skills

--init installs two skills per agent:

Configuration

Optional. Create nestjs-doctor.config.json in your project root:

{
  "minScore": 75,
  "ignore": {
    "rules": ["architecture/no-orm-in-services"],
    "files": ["src/generated/**"]
  },
  "rules": {
    "architecture/no-barrel-export-internals": false
  },
  "categories": {
    "performance": false
  }
}

Also works as a "nestjs-doctor" key in package.json.

Example rule-specific override:

{
  "rules": {
    "architecture/no-manual-instantiation": {
      "excludeClasses": ["Logger", "PinoLogger"]
    }
  }
}

Custom Rules

Extend the built-in rule set with project-specific checks. Only .ts files are supported.

Rule shape

Each .ts file in the custom rules directory must export an object with a meta descriptor and a check function:

import type { RuleContext } from "nestjs-doctor";

export const noTodoComments = {
  meta: {
    id: "no-todo-comments",
    category: "correctness",        // "security" | "performance" | "correctness" | "architecture" | "schema"
    severity: "warning",            // "error" | "warning" | "info"
    description: "TODO comments should be resolved before merging",
    help: "Replace the TODO with an implementation or open an issue.",
    // scope: "file",              // optional — "file" (default) or "project"
  },
  check(context: RuleContext) {
    const text = context.sourceFile.getFullText();
    const regex = /\/\/\s*TODO/gi;
    let match: RegExpExecArray | null;
    while ((match = regex.exec(text)) !== null) {
      const pos = context.sourceFile.getLineAndColumnAtPos(match.index);
      context.report({
        message: "Unresolved TODO comment",
        filePath: context.filePath,
        line: pos.line,
      });
    }
  },
};

Rule IDs are automatically prefixed with custom/ (e.g. no-todo-comments becomes custom/no-todo-comments).

Usage

Set customRulesDir in your config file:

{
  "customRulesDir": "./rules"
}

Error handling

Invalid rules produce warnings but never crash the scan. Common issues — missing check function, invalid category/severity, syntax errors — are surfaced in CLI output so you can fix them without blocking the rest of the analysis.

Monorepo Support

Monorepo detection supports five strategies (checked in priority order — first match wins):

1. nest-cli.json (takes precedence)

When "monorepo": true is set, each sub-project is scanned independently and results are merged.

{
  "monorepo": true,
  "projects": {
    "api": { "root": "apps/api" },
    "admin": { "root": "apps/admin" },
    "shared": { "root": "libs/shared" }
  }
}

2. pnpm-workspace.yaml (pnpm / Turborepo)

Reads pnpm-workspace.yaml, expands the packages globs, and filters to packages that depend on @nestjs/core or @nestjs/common.

packages:
  - "apps/*"
  - "packages/*"

3. package.json workspaces (npm / Yarn)

Reads the workspaces field from the root package.json. Both array and object formats are supported. Skipped when pnpm-workspace.yaml exists to avoid duplicate detection.

{
  "workspaces": ["apps/*", "packages/*"]
}

{
  "workspaces": {
    "packages": ["apps/*", "packages/*"]
  }
}

4. nx.json (Nx)

Detects nx.json and discovers sub-projects by scanning for project.json files. Each project must have a package.json with a NestJS dependency to be included.

// nx.json
{
  "targetDefaults": { "build": { "dependsOn": ["^build"] } }
}

5. lerna.json (standalone Lerna)

Reads lerna.json when useWorkspaces is not set. Uses the packages globs (defaults to ["packages/*"]). When useWorkspaces is true, detection is handled by strategy 3 instead.

{
  "packages": ["packages/*"]
}

Non-NestJS packages are always filtered out automatically — only packages with @nestjs/core or @nestjs/common are included.

If a monorepo is detected but no NestJS packages are found, nestjs-doctor emits a warning and falls back to single-project mode.

Output includes a combined score and a per-project breakdown.

Schema Analysis

Auto-detected from Prisma schema files (schema.prisma) or TypeORM entity decorators (@Entity()). When a schema is found, nestjs-doctor extracts entity-relationship data and:

• Renders an interactive ER diagram in the Schema tab of the HTML report (sidebar entity tree + canvas diagram + problems panel)
• Runs 3 schema-specific rules covering primary keys, timestamps, and cascade configuration

Supported ORMs: Prisma, TypeORM.

See the schema rules documentation for the full rule list.

Scoring

Weighted by severity and category, normalized by file count:

Node.js API

import { diagnose, diagnoseMonorepo } from "nestjs-doctor";

const result = await diagnose("./my-nestjs-app");
result.score;       // { value: 82, label: "Good" }
result.diagnostics; // Diagnostic[]
result.summary;     // { total, errors, warnings, info, byCategory }

const mono = await diagnoseMonorepo("./my-monorepo");
mono.isMonorepo;    // true
mono.subProjects;   // [{ name: "api", result }, ...]
mono.combined;      // Merged DiagnoseResult

Rules (50)

Security (10)

Correctness (20)

Architecture (10)

Performance (7)

Schema (3)