NgVitals

June 20, 2026 · View on GitHub

Health intelligence for Angular applications.

NgVitals is a static analysis tool that evaluates the health, architecture, maintainability, and modernization readiness of Angular applications.

Installation

npm install -g ng-vitals

Or run directly via npx:

npx ng-vitals analyze

Quick Start

Navigate to your Angular project directory and run:

ng-vitals analyze

This will:

Discover your Angular workspace (angular.json)
Load the TypeScript program via tsconfig
Parse all source files
Extract Angular metadata (components, services, directives, pipes, routes, modules)
Build the dependency graph
Run analysis rules
Print a full report to stdout

Commands

`ng-vitals analyze`

Analyzes an Angular workspace and prints a comprehensive health report.

Usage:

ng-vitals analyze [options]

Options:

Flag	Description	Default
`-d, --dir <path>`	Directory to analyze	Current working directory
`--json [file]`	Output report as JSON (to stdout or file)
`--sarif [file]`	Output report as SARIF (to stdout or file)
`--html [file]`	Output report as HTML (to file)
`--mermaid [dir]`	Output Mermaid diagrams to directory	`./mermaid`
`--fail-on <severity>`	Fail with exit code 1 if findings meet or exceed severity
`--baseline <file>`	Path to baseline JSON file for filtering known findings

Examples:

# Analyze current directory
ng-vitals analyze

# Analyze a specific project
ng-vitals analyze /path/to/angular-project

# Output JSON report to file
ng-vitals analyze --json report.json

# Output SARIF for CI integration
ng-vitals analyze --sarif results.sarif

# Output HTML report
ng-vitals analyze --html report.html

# Generate Mermaid diagrams
ng-vitals analyze --mermaid ./diagrams

# Fail CI if high severity findings exist
ng-vitals analyze --fail-on high

# Use baseline to ignore known findings
ng-vitals analyze --baseline baseline.json

`ng-vitals diff`

Compares two JSON report snapshots and shows what changed.

Usage:

ng-vitals diff <before> <after>

Arguments:

Argument	Description
`<before>`	Path to the before JSON report
`<after>`	Path to the after JSON report

Examples:

# Compare two snapshots
ng-vitals diff report-june.json report-july.json

# Save diff output
ng-vitals diff before.json after.json > diff.txt

Output:

The diff command shows:

Components added or removed
Services added or removed
Modules added or removed
Routes added or removed
Findings added or removed
Dependency graph metric changes

`ng-vitals trend`

Shows architecture trends from a directory of JSON snapshots.

Usage:

ng-vitals trend <directory>

Arguments:

Argument	Description
`<directory>`	Directory containing JSON snapshot files

Examples:

# Show trends from history directory
ng-vitals trend history/

# Show trends with date-sorted snapshots
ng-vitals trend ./snapshots/

Expected file naming:

Snapshot files should be named with dates for proper chronological sorting:

history/
  2026-06-18.json
  2026-06-20.json
  2026-06-25.json

Output:

Architecture Trends

Components:
18 → 22 → 30

Services:
5 → 7 → 8

Routes:
12 → 15 → 18

Standalone:
0% → 25% → 80%

OnPush:
0% → 50% → 75%

Findings:
45 → 32 → 18

High Findings:
7 → 4 → 1

Report Sections

The analyze command outputs the following sections:

1. Workspace Summary

Displays workspace information including Angular version, project structure, and file inventory.

NgVitals

Angular Version: 19
Projects: 1

  Project: sample-app
  Source Root: src
  TsConfig: tsconfig.app.json

Tsconfig Files: 1
Resolved TS Files: 45
Template Files: 12
Total Files: 57

Workspace discovered successfully.

2. Architecture Summary

Shows workspace-level architecture metrics.

================================================================================
Architecture Summary
================================================================================

  Angular Version:     19
  Workspace Type:      Single Project
  Application Size:    Medium
  Style:               Feature-Based
  Standalone Adoption: High
  OnPush Adoption:     Medium

3. Architecture Profile

Detailed breakdown of workspace characteristics.

================================================================================
Architecture Profile
================================================================================

  Module Architecture:     NgModule-based
  Standalone Components:   12/15 (80%)
  OnPush Components:       10/15 (67%)
  Lazy Loaded Routes:      5/8 (63%)

4. Modernization Report

Shows adoption metrics for modern Angular patterns.

================================================================================
Modernization Report
================================================================================

  Standalone Components:          12 / 15 (80%)
  OnPush Components:              10 / 15 (67%)
  Lazy Loaded Routes:             5 / 8 (63%)
  Directive Standalone Adoption:  3 / 4 (75%)
  Pipe Standalone Adoption:       2 / 2 (100%)

5. Workspace Metrics

Counts of Angular constructs found in the codebase.

================================================================================
Workspace Metrics
================================================================================

  Components:       15
  Services:         8
  Directives:       4
  Pipes:            2
  Routes:           8
  Templates:        12
  TypeScript Files: 45

6. Components Table

Detailed breakdown of all detected components.

================================================================================
Components
================================================================================

Found 15 component(s)

Name                                Selector                  Standalone   ChangeDet   Inputs  Outputs
-----------------------------------------------------------------------------------------------
AppComponent                        app-root                  false        Default     0       0
UserDashboardComponent              app-user-dashboard        true         OnPush      5       2
...

Summary:
  Standalone: 12/15
  OnPush: 10/15
  Total Inputs: 42
  Total Outputs: 18

7. Services Table

Detailed breakdown of all detected services.

================================================================================
Services
================================================================================

Found 8 service(s)

Name                                ProvidedIn      Methods     Properties  Deps
-----------------------------------------------------------------------------------------------
AuthService                         root            4           2           1
ApiService                          root            6           1           0
...

Summary:
  ProvidedIn root: 7
  ProvidedIn any: 1
  Total Methods: 32
  Total Properties: 12
  Total Constructor Deps: 15

8. Directives Table

Detailed breakdown of all detected directives.

================================================================================
Directives
================================================================================

Found 4 directive(s)

Name                                Selector                  Standalone
-----------------------------------------------------------------------------------------------
TooltipDirective                    [appTooltip]              true
HighlightDirective                  [appHighlight]            true
...

9. Pipes Table

Detailed breakdown of all detected pipes.

================================================================================
Pipes
================================================================================

Found 2 pipe(s)

Name                                Pipe Name                 Standalone   Pure
-----------------------------------------------------------------------------------------------
DateFormatPipe                      dateFormat                true         true
TruncatePipe                        truncate                  true         true

10. Routes Table

Detailed breakdown of all detected routes.

================================================================================
Routes
================================================================================

Found 8 route(s)

Path                                Component                 Lazy Loaded   Guard
-----------------------------------------------------------------------------------------------
/                                   AppComponent              false         false
/dashboard                          DashboardComponent        true          true
/users                              UserManagementComponent   false         false
/users/:id                          UserDetailComponent       true          false
...

11. Dependency Graph Summary

Metrics from the dependency graph analysis.

================================================================================
Dependency Graph Summary
================================================================================

  Nodes:                29
  Edges:                35
  Components:           15
  Services:             8
  Directives:           4
  Pipes:                2
  External Deps:        3

12. Most Consumed Services

Services with the most consumers (components or other services depending on them).

================================================================================
Most Consumed Services
================================================================================

Service                             Consumers
-----------------------------------------------------------------------------------------------
AuthService                         7
ApiService                          5
NotificationService                 3

13. Service Consumers

Tree view showing which components consume each service.

================================================================================
Service Consumers
================================================================================

AuthService
  └─ ArticleDetailComponent
  └─ EditorComponent
  └─ HomeComponent
  └─ LoginComponent

ApiService
  └─ ArticleService
  └─ CommentService
  └─ AuthService

14. Circular Dependencies

Lists any circular dependency cycles detected in the dependency graph.

================================================================================
Circular Dependencies
================================================================================

  AuthService → ApiService → AuthService
  (length: 2)

If no circular dependencies are found:

  No circular dependencies detected.

15. Deep Dependency Chains

Lists dependency chains exceeding the depth threshold (default: 5).

================================================================================
Deep Dependency Chains
================================================================================

  Depth: 6 (threshold: 5)
  Chain: ComponentA → ServiceA → ServiceB → ServiceC → ServiceD → ServiceE

If no deep chains are found:

  No deep dependency chains detected.

16. Findings

Analysis findings sorted by severity.

================================================================================
Findings
================================================================================

  [high] architecture.circular-module-dependency
    Circular dependency detected: AppModule -> SharedModule -> AppModule

  [medium] maintainability.large-component
    DashboardComponent exceeds 300 lines (450 lines)

  [low] maintainability.dead-service
    LoggingService has zero consumers

17. Quality Gate (conditional)

Displayed when --fail-on is used. Shows whether the quality gate passed or failed.

================================================================================
Quality Gate
================================================================================

  Threshold:  high
  Highest:    medium
  Passed:     true

18. Baseline Summary (conditional)

Displayed when --baseline is used and findings were filtered.

Baseline Summary
  New Findings: 2
  Ignored Baseline Findings: 5

Output Formats

JSON Output

Export the full report as JSON for programmatic consumption:

# Print to stdout
ng-vitals analyze --json

# Write to file
ng-vitals analyze --json report.json

The JSON report contains:

schemaVersion: Report schema version
workspace: Workspace metadata (Angular version, projects, file metrics)
components: Array of component metadata
services: Array of service metadata
modules: Array of module metadata
routes: Array of route metadata
dependencyGraph: Graph metrics and circular dependencies
findings: Array of analysis findings

SARIF Output

Export findings in SARIF format for CI integration:

# Print to stdout
ng-vitals analyze --sarif

# Write to file
ng-vitals analyze --sarif results.sarif

SARIF (Static Analysis Results Interchange Format) is supported by:

GitHub Code Scanning
Azure DevOps
VS Code SARIF extensions
Other CI/CD platforms

HTML Output

Export a self-contained HTML report:

ng-vitals analyze --html report.html

The HTML report includes:

Responsive design with light/dark mode
All analysis sections in a single file
No external dependencies

Mermaid Diagrams

Generate Mermaid diagrams for visualization:

ng-vitals analyze --mermaid ./diagrams

Generates:

components.mmd — Component dependency diagram
services.mmd — Service dependency diagram
modules.mmd — Module dependency diagram
routes.mmd — Route tree diagram

Render these with any Mermaid-compatible tool (GitHub, VS Code, etc.).

Quality Gate

Use --fail-on to fail the command when findings meet or exceed a severity level:

# Fail if any high severity findings
ng-vitals analyze --fail-on high

# Fail if medium or higher findings
ng-vitals analyze --fail-on medium

# Fail on any finding
ng-vitals analyze --fail-on info

Severity levels:

Level	Exit Code
`high`	1 if high findings exist
`medium`	1 if medium or high findings exist
`low`	1 if low, medium, or high findings exist
`info`	1 if any findings exist

CI example:

# GitHub Actions
- name: Analyze Angular app
  run: ng-vitals analyze --fail-on high

Baseline

Use --baseline to suppress known findings and report only new ones:

ng-vitals analyze --baseline baseline.json

Baseline file format:

{
  "schemaVersion": "1.0",
  "entries": [
    {
      "id": "circular-module-dependency:AppModule->SharedModule->AppModule",
      "file": "src/app/app.module.ts",
      "line": 10,
      "title": "Circular Module Dependency",
      "severity": "high",
      "category": "architecture"
    }
  ]
}

How it works:

Findings matching baseline entries (by id + file + line) are suppressed
Only new findings not in the baseline are reported
A summary shows new vs. ignored finding counts
If the baseline file is missing, a warning is printed and analysis proceeds

CI Integration

GitHub Actions

name: Angular Analysis
on: [push, pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - name: Analyze
        run: npx ng-vitals analyze --fail-on high --sarif results.sarif
      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

GitLab CI

analyze:
  script:
    - npx ng-vitals analyze --fail-on high

Azure DevOps

- script: npx ng-vitals analyze --sarif $(Build.SourcesDirectory)/results.sarif
  displayName: 'Run NgVitals Analysis'

Analysis Rules

NgVitals runs the following rules during analysis:

Architecture Rules

Rule	ID	Description
Circular Module Dependency	`architecture.circular-module-dependency`	Detects circular `imports` between NgModules

Maintainability Rules

Rule	ID	Description
Large Component	`maintainability.large-component`	Detects components exceeding line count thresholds
Large Service	`maintainability.large-service`	Detects services with excessive public methods
Too Many Inputs	`maintainability.too-many-inputs`	Detects components with too many `@Input()` properties
Too Many Dependencies	`maintainability.too-many-dependencies`	Detects components with too many constructor dependencies
Dead Service	`maintainability.dead-service`	Detects services with zero consumers

Finding Severity Levels

Level	Meaning
`high`	Significant architectural or maintainability risk
`medium`	Meaningful improvement opportunity
`low`	Minor improvement opportunity
`info`	Informational finding

Exit Codes

Code	Meaning
`0`	Command completed successfully
`1`	Error occurred or quality gate failed

Requirements

Node.js 22+
Angular project with angular.json
TypeScript project with tsconfig.json

How It Works

Angular Project
        ↓
Scanner (discovers workspace, loads tsconfig)
        ↓
Parser (extracts Angular metadata via TypeScript Compiler API)
        ↓
Application Model (normalized domain objects)
        ↓
Dependency Graph Builder (builds component/service graph)
        ↓
Rule Engine (runs analysis rules against the model)
        ↓
Findings (sorted by severity)
        ↓
Report (formatted text output to stdout)

NgVitals never modifies your source code. It is a read-only static analysis tool.

Troubleshooting

"No angular.json found"

NgVitals requires an Angular workspace with an angular.json file in the project root.

"No tsconfig.json found"

Ensure your Angular project has a tsconfig.json or tsconfig.app.json at the root.

Empty output for services/components

Verify your source files are included in the tsconfig.json include array.

Circular dependencies not detected

Circular dependency detection operates on the module imports array, not import statements. Modules must import each other via @NgModule({ imports: [...] }) to be detected.

License

ISC