dependency-cruiser — Validate and Visualize JS Dependencies

Introduction

dependency-cruiser validates your project's module dependencies against a set of rules you define, then reports violations. It also generates visual dependency graphs. Think of it as a linter for your import structure.

What dependency-cruiser Does

• Parses ES6 imports, CommonJS require, and TypeScript references to build a full dependency graph
• Validates dependencies against configurable rules (no circular deps, no orphans, layer boundaries)
• Generates visual graphs in DOT, SVG, HTML, or Mermaid format
• Supports JavaScript, TypeScript, CoffeeScript, and Vue single-file components
• Integrates into CI pipelines to enforce architectural constraints automatically

Architecture Overview

dependency-cruiser performs a two-phase process. First, it extracts dependencies by parsing source files with an AST-based approach, resolving paths using Node's module resolution algorithm (enhanced for TypeScript paths, webpack aliases, and Babel module maps). Second, it evaluates the dependency graph against your rule set and reports violations with severity levels.

Self-Hosting & Configuration

• Install as a dev dependency: npm install --save-dev dependency-cruiser
• Run npx depcruise --init to generate a starter .dependency-cruiser.cjs config
• Define forbidden dependency patterns: e.g., no imports from 'test' folders into 'src'
• Configure path aliases via tsconfig or webpack config references in the options
• Set up a CI step: npx depcruise src --config .dependency-cruiser.cjs

Key Features

• Rule-based validation: define allowed, forbidden, and required dependency patterns
• Built-in rule presets for common patterns like no-circular, no-orphans, and not-to-dev-dep
• Multiple reporter formats: err, dot, archi, mermaid, html, json, and text
• Incremental analysis: only check changed files by comparing against a baseline
• Supports path aliases from tsconfig.json, webpack, and Babel configurations

Comparison with Similar Tools

• Madge — Focused on visualization and circular detection; dependency-cruiser adds rule enforcement and policy-based validation
• ESLint import/no-cycle — Single-rule lint check per file; dependency-cruiser evaluates the entire graph and supports complex multi-rule policies
• Nx — Monorepo boundary enforcement at the project level; dependency-cruiser works at the file/module level within any project
• Knip — Finds unused files and exports; dependency-cruiser validates dependency relationships and architectural boundaries

FAQ

Q: How does it differ from ESLint import rules? A: ESLint processes one file at a time. dependency-cruiser builds the full project graph first, so it can enforce cross-cutting rules like layer boundaries and detect all cycles in a single run.

Q: Can I use it in a monorepo? A: Yes. Point it at specific workspace folders or the root, and configure rules per package or across the entire repo.

Q: What output format should I use for CI? A: Use the err reporter for human-readable violation output, or the err-long reporter for detailed paths. Both exit with code 1 on violations.

Q: Does it support dynamic imports? A: Yes. dependency-cruiser detects dynamic import() expressions and includes them in the graph with a dynamic dependency flag.

Sources

• https://github.com/sverweij/dependency-cruiser
• https://www.npmjs.com/package/dependency-cruiser