Skip to main content
This guide will help you run your first Rev-dep checks and understand the output. We’ll use both exploratory CLI commands and config-based governance.
Make sure you’ve installed Rev-dep before proceeding.

​
Exploratory Commands

Start by exploring your codebase with instant CLI commands. These are perfect for understanding your dependency structure.

​
Detect Circular Dependencies

Circular imports can cause hard-to-debug issues. Find them instantly: 
rev-dep circular
Use --ignore-type-imports to exclude TypeScript type-only imports from analysis.
Example output: 
Found 2 circular dependency chains:

1. src/features/auth/utils.ts → src/features/auth/service.ts → src/features/auth/utils.ts
2. src/components/Button.tsx → src/components/Icon.tsx → src/components/Button.tsx

​
Find Unused Dependencies

Identify npm packages declared in package.json but never imported: 
rev-dep node-modules unused
Example output: 
Unused node modules (3):
  - lodash
  - moment
  - axios

​
Discover Entry Points

Find all entry points in your project: 
rev-dep entry-points
Example output: 
Entry points (4):
  - src/index.ts
  - src/server.ts
  - scripts/build.js
  - src/pages/index.tsx

​
Trace File Dependencies

See all files imported by a specific entry point: 
rev-dep files --entry-point src/index.ts
Example output: 
Files imported by src/index.ts (12):
  - src/utils/helper.ts
  - src/features/auth/index.ts
  - src/features/auth/service.ts
  - src/components/App.tsx
  ...

​
Find Where a File is Used

Discover which entry points depend on a specific file: 
rev-dep resolve --file src/utils/helper.ts
Example output: 
File src/utils/helper.ts is used by 3 entry points:

1. src/index.ts
   → src/features/auth/service.ts
   → src/utils/helper.ts

2. src/server.ts
   → src/api/routes.ts
   → src/utils/helper.ts

3. src/pages/dashboard.tsx
   → src/components/Stats.tsx
   → src/utils/helper.ts

​
Config-Based Governance

For comprehensive project checks and CI integration, use Rev-dep’s config-based approach. This is significantly faster than running individual commands.

​
Initialize Configuration

Create a configuration file with default checks: 
rev-dep config init
This creates a rev-dep.config.json file: 
{
  "configVersion": "1.6",
  "$schema": "https://github.com/jayu/rev-dep/blob/master/config-schema/1.6.schema.json?raw=true",
  "rules": [
    {
      "path": ".",
      "prodEntryPoints": ["src/index.ts"],
      "devEntryPoints": ["**/*.test.*"],
      "circularImportsDetection": {
        "enabled": true
      },
      "orphanFilesDetection": {
        "enabled": true,
        "autofix": true
      },
      "unusedNodeModulesDetection": {
        "enabled": true
      }
    }
  ]
}

​
Run All Checks

Execute all checks defined in your configuration: 
rev-dep config run
1

Rev-dep analyzes your codebase

Builds a comprehensive dependency graph in a single pass.
2

Multiple checks run in parallel

All enabled checks execute simultaneously for maximum performance.
3

Results are displayed

Violations are grouped by check type with file locations.
Example output: 
✓ Analyzing project structure...
✓ Building dependency graph...
✓ Running checks...

────────────────────────────────────────────────────────
Rule: . (root)
────────────────────────────────────────────────────────

✓ Circular Imports Detection: No issues found

❌ Orphan Files Detection (2 issues):
  - src/utils/orphan.ts
  - src/legacy/old-helper.ts

❌ Unused Node Modules Detection (3 issues):
  - lodash
  - moment  
  - axios

✓ Missing Node Modules Detection: No issues found

────────────────────────────────────────────────────────
Summary: 5 issues found across 2 checks
────────────────────────────────────────────────────────

​
View All Issues

By default, Rev-dep shows the first 5 issues per check. To see everything: 
rev-dep config run --list-all-issues

​
Apply Automatic Fixes

Many checks support automatic fixes. Apply them with: 
rev-dep config run --fix
Review changes carefully after running --fix. The command will delete orphan files, remove unused exports, and modify import statements.
Checks with autofix support:
  • orphanFilesDetection - Deletes orphan files
  • unusedExportsDetection - Removes unused exports
  • importConventions - Fixes import style violations

​
Real-World Example

Let’s walk through a complete example with a TypeScript project:
1

Create a sample project structure

mkdir my-project && cd my-project
npm init -y
npm install -D rev-dep typescript
2

Create some source files

src/index.ts
import { helper } from './utils/helper';
import { featureA } from './features/featureA';

console.log('Main entry point');
helper();
featureA();
src/utils/helper.ts
export function helper() {
  console.log('Helper function called');
}

export function unusedHelper() {
  // This is never used
  return 'unused';
}
src/utils/orphan.ts
// This file is never imported anywhere
export function orphanFunction() {
  return 'I am alone';
}
3

Initialize Rev-dep configuration

npx rev-dep config init
Edit rev-dep.config.json to enable checks:
{
  "configVersion": "1.6",
  "rules": [
    {
      "path": ".",
      "prodEntryPoints": ["src/index.ts"],
      "unusedExportsDetection": {
        "enabled": true,
        "autofix": true
      },
      "orphanFilesDetection": {
        "enabled": true,
        "autofix": true
      }
    }
  ]
}
4

Run checks

npx rev-dep config run
Output:
❌ Unused Exports Detection (1 issue):
  - unusedHelper in src/utils/helper.ts:5

❌ Orphan Files Detection (1 issue):
  - src/utils/orphan.ts

Summary: 2 issues found
5

Apply fixes

npx rev-dep config run --fix
Rev-dep will:
  • Remove the unusedHelper export from src/utils/helper.ts
  • Delete the orphaned src/utils/orphan.ts file
6

Verify clean codebase

npx rev-dep config run
Output:
✓ Unused Exports Detection: No issues found
✓ Orphan Files Detection: No issues found

Summary: All checks passed!

​
Performance Benefits

The config-based approach provides significant performance advantages:
  • Single dependency tree build - Analyzes your codebase once
  • Parallel rule execution - Processes multiple rules simultaneously
  • Parallel check execution - Runs all enabled checks within each rule in parallel
  • Optimized file discovery - Discovers files once and reuses across checks
For a 500k+ LoC monorepo, rev-dep config run executes all checks in approximately 500ms - that’s 20-200x faster than running individual commands sequentially!

​
Monorepo Usage

For monorepo projects, enable cross-package dependency resolution: 
rev-dep circular --follow-monorepo-packages
Or in your config: 
{
  "rules": [
    {
      "path": ".",
      "followMonorepoPackages": true,
      "circularImportsDetection": {
        "enabled": true
      }
    }
  ]
}

​
Integrate with CI

Add Rev-dep to your CI pipeline for continuous governance: 
name: Dependency Checks

on: [push, pull_request]

jobs:
  rev-dep:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npx rev-dep config run

​
Next Steps

Configuration Guide

Learn about all available checks and options

CLI Reference

Explore all CLI commands and flags

Module Boundaries

Enforce architectural constraints

Import Conventions

Standardize import patterns

Build docs developers (and LLMs) love

Get started for freeTalk to us