ng-loom

Angular-aware dependency visualization for Angular CLI workspaces.

ng-loom is a CLI that scans an Angular project and emits a shareable, self-contained static HTML report of the app's architecture: components, directives, pipes, services, NgModule wrappers, standalone imports, and dependency injection edges.

📦 npm · 📝 Read the write-up on dev.to or Medium

Working, actively developed. Verified against a public Angular app (screenshots below) and a large private production workspace.

This release focuses on correctness, safer report sharing, and a cleaner report/analyzer architecture.

• Added --portable report mode to remove absolute local paths and source snippets from generated HTML reports. Use --include-snippets with --portable if you want sanitized paths while keeping snippets.
• Improved Angular symbol resolution so duplicate class names, import aliases, constructor DI, inject() calls, standalone imports, NgModule metadata, and route references resolve by declaration identity instead of fragile text names.
• Template parsing now prefers the target project's installed @angular/compiler, with a warning-backed fallback to ng-loom's bundled compiler when the target compiler cannot be loaded.
• Added ambiguous selector handling for templates. When multiple directives/components can match the same selector, the report preserves the ambiguity, includes candidates, and marks heuristic confidence instead of silently choosing one.
• Improved trace/search behavior for duplicated names and selectors, including clearer disambiguation and more accurate "no path found" messaging.
• Added a collapsible Details panel in the HTML report for easier graph exploration.
• Reworked the analyzer into smaller focused modules and moved the report client JavaScript to typed TypeScript modules.
• Added friendlier CLI error handling and a --debug mode for full diagnostics.
• Corrected documentation around lazy route support: loadComponent is supported; loadChildren is not yet supported.
• Expanded automated coverage with analyzer regression tests, portable-output tests, report-client tests, and Playwright validation against generated fixture reports.
• Revalidated generated reports against real Angular workspaces after the refactors.

Still not supported in this release:

• Nx and full multi-project monorepo workspace resolution.

Generated from the public ngx-admin dashboard template (294 nodes, 340 edges).

Overview — folder/package clusters

All artifacts — flat dependency graph

Node focus with Details panel

Trace relation — multi-path lookup between two artifacts

npx ng-loom ./path/to/angular-project --out report.html

For local development:

npm install
npm run build
npm run dev -- ./path/to/angular-project --out report.html

Privacy note: the generated HTML report embeds absolute filesystem paths and source code snippets from your machine. It is not safe to share externally (e.g. post publicly, upload to a third party) as-is. Use --portable to strip this information before sharing:

ng-loom ./path/to/angular-project --out report.html --portable

This removes absolute paths (including the workspace root, which is replaced with just its folder name) and source code snippets. To keep source snippets while still stripping absolute paths, add --include-snippets:

ng-loom ./path/to/angular-project --out report.html --portable --include-snippets

• Angular workspace and tsconfig discovery, including Angular CLI multi-project workspaces and local file: package dependencies
• Component, directive, pipe, service, and NgModule discovery, including the @Service() decorator (experimental, unreleased Angular builds) alongside @Injectable()
• Standalone component imports extraction and NgModule imports/exports/declarations extraction
• hostDirectives tracking, including the { directive, inputs, outputs } aliasing form
• Constructor DI and inject() dependency detection
• Lazy route detection for loadComponent (loadChildren is not yet supported)
• Real Angular template AST parsing with the target project's installed @angular/compiler when available, including attribute selectors, structural directives, and the @if/@for/@switch/@defer/@let control-flow syntax
• @Input()/@Output()/model API extraction, including aliases and the signal-based input()/output()/model() functions
• Source-location evidence on every edge (file, line, column, snippet, and a vscode:// deep link)
• Self-contained static HTML report: zoomable/pannable dependency graph, folder/package cluster overview, node focus + Details panel, multi-path trace relation lookup, dark theme
• --include and --exclude path filters
• --portable to strip absolute paths and source snippets for safe sharing, with --include-snippets to keep snippets while still stripping absolute paths

• Pipe usage in templates ({{ value | pipeName }}) is not yet tracked as a uses edge
• Class-selector matching only looks at the static class="..." attribute, not [class.x]/[ngClass] bindings
• Route parsing handles common static component/loadComponent patterns, not every dynamic route construction
• No Nx monorepo support — resolveWorkspace only looks for tsconfig.app.json/tsconfig.json directly in the given root
• Expanded cluster state is not persisted across report reloads
• Trace path ranking is heuristic and may surface many similar paths in dense component graphs