DepGraph

Interactive, 100% local dependency graph for JS/TS projects, with actionable circular-dependency detection. No Graphviz, no runtime dependencies.

A single command produces a standalone HTML file (force-directed graph, folder view, search, click-to-highlight cycles) and prints the exact cycle chains in the terminal, classified runtime vs type-only, with the cheapest edge to break suggested for each real cycle.

Usage

No install needed — run it with npx:

npx @tomi_tom/depgraph <dir> -o graph.html
# then open graph.html in your browser

Or install it globally:

npm install -g @tomi_tom/depgraph
depgraph <dir> -o graph.html

Options

-o, --out <file>       output HTML file (default: depgraph.html)
    --json             also write the graph as JSON (<out>.json)
    --dot              also write Graphviz DOT (<out>.dot)
    --forbid "a -> b"  forbid imports from a to b (repeatable, globs * and **)
    --fail-type-cycles exit non-zero even when cycles are type-only
-h, --help             show help

Exit codes (CI-ready)

0  clean — type-only cycles are tolerated by default (they vanish at compile time)
1  usage / IO error
2  runtime circular dependencies
3  forbidden dependencies (--forbid violations)

Features

• Runtime vs type-only cycles. DepGraph knows the difference between a cycle that can break your app at runtime and one made only of import type edges (which TypeScript erases at compile time). Only runtime cycles fail the build — no more red CI for harmless type cycles.
• Cheapest break suggested. Every runtime cycle comes with the edge that is cheapest to cut (fewest imported bindings): invert it, extract shared code, or switch it to import type.
• Architecture rules. --forbid "src/ui -> src/db" (repeatable, globs * and **) turns the graph into a CI guardrail against forbidden layer crossings — violations are listed in the terminal and clickable in the HTML.
• Folder view. One toggle aggregates the graph by directory (edge thickness = number of imports) — the architecture at a glance on large codebases. Files are color-coded by folder, with a legend.
• Impact analysis. Click any file → ⌁ impact highlights everything it transitively touches: dependents upstream (orange) and dependencies downstream (cyan). Your blast radius before a refactor.
• Circular dependencies surfaced as closed import chains, clickable to highlight (type-only edges are dashed, runtime cycle nodes have a red ring).
• TypeScript path aliases resolved from tsconfig.json (paths + baseUrl), plus the NodeNext .js → .ts convention — works even when run from a subfolder.
• Interactive HTML: hover tooltips, detail panel with clickable imports/importers, search (/), "show cycles only" toggle, zoom/pan, pinnable nodes (double-click / shift-drag).
• Live layout controls: real-time physics sliders (repulsion, cable length, elasticity, gravity, damping, node size, edge opacity) + shape presets (Balanced / Compact / Spread / Tree).
• Calm & efficient: the force layout freezes once it settles (no CPU spinning) and wakes on interaction; respects prefers-reduced-motion.
• One-click PNG export straight from the browser — no Graphviz, unlike madge/dependency-cruiser.
• Insights in the terminal: most-imported file, orphan files (no imports in/out).

Example

$ npx @tomi_tom/depgraph src --forbid "src/components -> src/utils"
✓ 18 files · 28 imports analyzed (tsconfig aliases resolved)
⚠ 3 circular dependency(ies) detected (2 runtime · 1 type-only):
   ⤷ [runtime] src/api/client.ts → src/api/endpoints.ts → src/api/client.ts
     ✂ cheapest break: src/api/client.ts → src/api/endpoints.ts (1 binding) — invert it, or extract shared code / use "import type"
   ⤷ [type-only] src/models/post.ts → src/models/user.ts → src/models/post.ts
   ⤷ [runtime] src/lib/a.ts → src/lib/b.ts → src/lib/c.ts → src/lib/a.ts
     ✂ cheapest break: src/lib/a.ts → src/lib/b.ts (1 binding) — invert it, or extract shared code / use "import type"
   ℹ type-only cycles vanish at compile time (no runtime risk) — they don't fail the build (use --fail-type-cycles to change that)
✗ 2 forbidden dependency(ies):
   ⤷ src/components/button.ts → src/utils/format.ts  (rule: src/components -> src/utils)
→ depgraph.html

Why

Existing tools require Graphviz for the visuals (madge, dependency-cruiser), leave cycles as a "wall of paths" that is hard to act on, and treat every cycle the same. DepGraph shows each cycle as a closed import chain (A → B → C → A), tells you whether it can actually hurt you at runtime, and points at the cheapest edge to cut.

Limitations

Resolves relative imports (./, ../), the NodeNext .js → .ts convention, and TS path aliases (tsconfig.json paths + baseUrl). Not yet supported: monorepo project references / workspace packages, and dynamic/computed import paths. UTF-8 source; symlinks are ignored.

Development

git clone https://github.com/Tomi-Tom/depgraph
cd depgraph
npm install          # builds dist/ automatically (prepare script)
npm test             # 59 tests (Vitest)
node dist/cli.js sample-project -o graph.html   # demo (2 runtime cycles + 1 type-only)

License

MIT