NgVitals

Health intelligence for Angular applications.

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

Features

• Architecture Analysis — Detect circular dependencies, module relationships, deep chains
• Modernization Tracking — Standalone adoption, OnPush adoption, lazy loading metrics
• Maintainability Rules — Large components, too many dependencies, dead services
• Dependency Intelligence — Service consumption graphs, most-used services
• Multiple Outputs — Console, JSON, SARIF, HTML, Mermaid diagrams
• CI Integration — Quality gates, baseline filtering, exit codes
• Trend Analysis — Track metrics over time from JSON snapshots

Installation

npm install -g ng-vitals

Or run directly via npx:

npx ng-vitals analyze

Quick Start

cd your-angular-project
ng-vitals analyze

This will:

1. Discover Angular workspace (angular.json or tsconfig.json workspace)
2. Load TypeScript program via tsconfig
3. Parse source files
4. Extract Angular metadata (components, services, directives, pipes, routes, modules)
5. Build dependency graph
6. Run analysis rules
7. Print report to stdout

Commands

| Command | Description | |---------|-------------| | ng-vitals analyze | Analyze Angular workspace | | ng-vitals diff | Compare two JSON report snapshots | | ng-vitals trend | Show architecture trends over time |

ng-vitals analyze

Analyzes Angular workspace and prints 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> | Exit 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 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 before JSON report | | <after> | Path to 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:

• 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 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 use dates for 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 following sections.

1. Workspace Summary

Displays workspace info including Angular version, project structure, 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:      8/18 (44%)

4. Modernization Report

Modernization adoption metrics.

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

  Standalone Components:          12 / 15 (80%)
  OnPush Components:              10 / 15 (67%)
  Lazy Loaded Routes:             8 / 18 (44%)
  Directive Standalone Adoption:  6 / 8 (75%)
  Pipe Standalone Adoption:       4 / 5 (80%)

5. Workspace Metrics

Aggregate file counts.

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

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

6. Components, Services, Directives, Pipes, Routes

Entity tables and dependency information.

7. Dependency Graph Summary

Graph node/edge metrics and circular dependencies.

8. Most Consumed Services

Services with highest consumer counts.

9. Service Consumers

Reverse dependency list for each service.

10. Circular Dependencies

Circular service/component/module cycles.

11. Deep Dependency Chains

Long dependency paths with depth above threshold.

Example Commands

# Basic analysis
ng-vitals analyze

# JSON report
ng-vitals analyze --json report.json

# SARIF output
ng-vitals analyze --sarif results.sarif

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

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

# Quality gate
ng-vitals analyze --fail-on high

# Baseline filtering
ng-vitals analyze --baseline baseline.json

# Compare snapshots
ng-vitals diff before.json after.json

# Trend analysis
ng-vitals trend history/

CI Integration

GitHub Actions

name: Analyze Angular App

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 install
      - run: npx ng-vitals analyze --fail-on high --sarif results.sarif

GitLab CI

analyze:
  image: node:22
  script:
    - npm install
    - npx ng-vitals analyze --fail-on high

Azure DevOps

- script: npx ng-vitals analyze --sarif $(Build.SourcesDirectory)/results.sarif
  displayName: Analyze Angular app

Troubleshooting

"angular.json not found"

Ensure project has angular.json or root-level tsconfig.json.

"No tsconfig.json found"

Ensure Angular project has tsconfig.json or tsconfig.app.json at root.

Empty output for services/components

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

Circular dependencies not detected

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

Requirements

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

How It Works

NgVitals is read-only static analysis tool. It:

1. Discovers Angular workspace
2. Parses source files via TypeScript Compiler API
3. Extracts Angular metadata (components, services, modules, routes)
4. Builds dependency graph
5. Runs analysis rules
6. Reports findings sorted by severity

NgVitals never modifies source code.

Sample Output

NgVitals

Angular Version: 19
Projects: 1

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

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

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

================================================================================
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
...

================================================================================
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

License

MIT