See your architecture. Catch violations before they ship.

DepTrace reads the imports of a TypeScript or JavaScript repository, checks them against the architecture rules you write, and shows every dependency, cycle and violation in a dashboard on your own machine. It never runs your code.

Quick start View on GitHub

Install

Node.js 22.12 or later

npm install -g deptrace-cli

Installs the deptrace command. Or run it once with npx deptrace-cli.

Version: 0.5.0
License: MIT
Package: npm

The DepTrace dashboard overview for a sample project: counts of files, dependencies, packages, cycles and violations, a list of where to start, and violations by rule. — dashboard/overview · the sample project `tests/fixtures/storefront`

Rules you write in one file

Put deptrace.yml in the repository, name your layers with globs, and choose the rules. deptrace check exits with code 3 when a rule is broken, so CI fails on the pull request that broke it.

Rule types
`layer-boundaries`	Each layer may import only the layers you allow.
`forbidden-imports`	Files matching one glob must not import files matching another.
`forbidden-packages`	Keep frameworks and Node.js APIs out of the code that should not use them.
`module-boundaries`	Feature modules use each other only through their public files.
`circular-dependencies`	No group of files may import itself, optionally ignoring type-only imports.

deptrace.yml

excerpt from the sample project

layers:
  - name: ui
    files: ["src/ui/**"]
  - name: application
    files: ["src/application/**"]
  - name: domain
    files: ["src/domain/**"]

rules:
  layer-boundaries:
    severity: error
    allowed:
      ui: [application, shared]
      application: [domain, shared]
      domain: [shared]

  circular-dependencies:
    severity: error
    ignore-type-only: true

A dashboard that shows the evidence

deptrace dashboard serves the analysis to your browser from 127.0.0.1. Every number comes from the analysis, and every finding opens to the rule, the import statement and its line.

The dependency graph with one file selected: its dependencies are highlighted and everything else is dimmed; the file's card lists what it imports and what imports it, with line and column of each import. — **Dependency graph.** Search a file, follow its dependencies or dependents, the shortest path to another file, a cycle or a violation. Large graphs are grouped by folder instead of being cut off.

The violations page filtered to the one violation that is new compared with the baseline, with its card showing the rule, the source and target files, the import that causes it and the dependency path. — **Violations.** Filter by severity, rule, file or baseline status; each one shows the import that causes it and its stable fingerprint.

The layer matrix: rows import columns, each cell counts dependencies between two layers and marks pairs that the layer policy forbids, with the selected forbidden pair listing its dependency. — **Layers.** A matrix of the dependencies between your configured layers, with the forbidden pairs marked.

The dependency graph in the dark theme with a three-file cycle highlighted as three separate arcs, and the cycle's representative path listed beside it. — **Cycles.** Each cycle group with a representative path, in the light or dark theme.

Built for CI

Baselines. Accept today's violations with deptrace baseline create; the check then fails only on new ones.
GitHub Actions. Job summaries, annotations on the offending import, and SARIF for code scanning, from copyable workflows with pinned actions and read-only permissions.
Deterministic. The same code gives the same report and the same violation fingerprints on every machine.
Fast enough for every push. About 7 seconds for a synthetic 10,000-file repository on the benchmark machine (measurements).

deptrace check --baseline deptrace-baseline.json on the sample project (excerpt)

Violations: 4 errors, 1 warning
  error   existing  src/application/cart-service.ts:2:26  [circular-dependencies]
  warning existing  src/application/catalog-service.ts:4:27  [forbidden-imports/no-test-doubles]
  error   existing  src/domain/pricing.ts:2:30  [forbidden-packages/pure-domain]
  error   existing  src/domain/pricing.ts:3:30  [layer-boundaries]
  error   new       src/ui/product-list.ts:3:30  [layer-boundaries]
          Layer "ui" must not depend on layer "infrastructure" (allowed for "ui": application, shared).

Baseline: deptrace-baseline.json (1 new, 4 existing, 1 resolved)
error: Architecture check failed: 1 new failing violation (4 existing violations accepted by the baseline).

Quick start

Install
```
npm install -g deptrace-cli
```
Create a configuration
```
deptrace init
```
Writes a starter deptrace.yml; add your layers and rules (rule guide).
Check
```
deptrace check
```
Exit code 0 when the rules hold, 3 when they are broken.
Explore
```
deptrace dashboard
```
Open the printed address; press Ctrl+C to stop.

Your code stays on your machine

DepTrace parses files with the TypeScript compiler and never executes them. The CLI makes no network requests, and the dashboard only talks to its local server. There is no telemetry and no account. Reports contain repository-relative paths only.

Security & Trust Center · Report a vulnerability · Privacy