v0.2.2-beta

Getting started

Quick start.

Get from zero to a full analysis report in under a minute. Start with the project-local ng add setup so the CLI and config schema stay pinned together.
  1. 01

    Go to your Angular project

    bash
    01cd my-angular-app
  2. 02

    Install and initialize

    bash
    01ng add ngcompass

    This installs ngcompass in your Angular project and creates ngcompass.config.ts in the project root using the ngcompass:recommended preset. You can edit it later to add rule overrides or change the preset.

    ngcompass.config.ts
    01import { defineConfig } from '@ngcompass/config';
    02

    03export default defineConfig({
    04  extends: 'ngcompass:recommended',
    05

    06  include: [
    07    'src/**/*.ts',
    08    'src/**/*.html',
    09  ],
    10

    11  exclude: [
    12    'node_modules/**',
    13    'dist/**',
    14    'build/**',
    15    'coverage/**',
    16    '**/*.d.ts',
    17    '**/*.spec.ts',
    18    '**/*.test.ts',
    19  ],
    20

    21  profiles: {
    22    ci: {
    23      outputFormat: 'json',
    24      maxWarnings: 0,
    25    },
    26  },
    27});

    If your workspace cannot run schematics, use manual local install and then run npx ngcompass init --force to overwrite an existing config.

  3. 03

    Run analysis

    bash
    01npx ngcompass analyze

    ngcompass scans your TypeScript files, component templates, and Angular metadata. Results are printed to the terminal grouped by severity. The process exits with a non-zero code if any error-severity violations are found.

  4. 04

    Open the interactive report (optional)

    bash
    01npx ngcompass analyze --format html

    This writes ngcompass-report.html to the current directory. Open it in your browser to review severity charts, per-file drill-down, and search + filter. Use --output <path> to change the output location.

Explore your codebase visually

Beyond static analysis, ngcompass ships two graph commands that generate JSON files you can load into interactive browser-based viewers — no upload, no server, everything runs locally.

Dependency graph

See every import relationship in your project. Explore what each file depends on, what depends on it, and which modules are the heaviest.

bash
01npx ngcompass graph --output graph.json

Then load graph.json at ngcompass.dev/graph.

Circular dependencies

Find every import cycle in your codebase — the exact files and the order they close the loop.

bash
01npx ngcompass circular --format json --output cycles.json

Then load cycles.json at ngcompass.dev/cycles.

Next steps

Continue from here:

CLI commands →

Full reference for analyze, graph, circular, and more.

Configuration →

Tune which rules run and at what severity.

CI integration →

Add ngcompass to GitHub Actions.