About 📣

Working in large JS/TS projects makes it difficult to answer simple but crucial questions:

• Which files depend on this file?
• Is this file even used?
• Which files does this entry point import?
• Do I have circular dependencies?
• Which packages in node_modules are unused?
• Which modules take the most disk space?

Rev-dep helps you understand the real structure of your codebase so you can debug issues faster, refactor safely, and keep your dependencies clean.

It's particularly useful for JavaScript projects without TypeScript or test coverage — places where answering question "What will break if I change this" is not straightforward

Why Rev-dep? 🤔

Rev-dep is designed for fast iteration and minimal, actionable results — no noise, just answers.

✅ Results in milliseconds

Built in Go for speed. Even on large codebases, rev-dep responds almost instantly.

✅ Actionable, list-based output

You get exact file paths, import chains, and clear dependency relationships — the kind of information you can fix or clean up right away.

✅ Designed for real-world JS/TS with first class monorepo support

Works with mixed JS/TS projects, path aliases and thousands of files without configuration hassles.

✅ Deep analysis, one CLI

Unused files, unused or missing dependencies, reverse-imports, entry point detection, node_modules insights, dependency paths — everything in one tool.

✅ Much faster than alternatives

Rev-dep outperforms Madge, dpdm, dependency-cruiser, skott, knip, depcheck and other similar tools.

For large project with 500k+ lines of code and 6k+ source code files get checks as fast as:

| Task | Execution Time [ms] | Alternative | Alternative Time [ms] | Slower Than Rev-dep | |------|-------|--------------|------|----| | Find circular dependencies | 289 | dpdm-fast | 7061| 24x| | Find unused files | 588 | knip | 6346 | 11x | | Find unused node modules | 594 | knip | 6230 | 10x | | Find missing node modules | 553 | knip| 6226 | 11x | | List all files imported by an entry point | 229 | madge | 4467 | 20x | | Discover entry points | 323 | madge | 67000 | 207x | Resolve dependency path between files | 228 | please suggest | | Count lines of code | 342 | please suggest | | Check node_modules disk usage | 1619 | please suggest | | Analyze node_modules directory sizes | 521 | please suggest |

Benchmark run on WSL Linux Debian Intel(R) Core(TM) i9-14900KF CPU @ 2.80GHz

Key Features 🚀

• 🔍 Reverse dependency lookup — see all entry points that require a given file
• 🗂️ Entry point discovery
• 🧹 Dead file detection
• 📦 Unused / missing / used node modules / dependencies analysis
• 🔄 Circular imports/dependencies detection
• 🧭 Trace all import paths between files
• 📁 List all files imported by any entry point
• 📏 Count actual lines of code (excluding comments and blanks)
• 💽 Node modules disk usage & size analysis
• 💡 Works with both JavaScript and TypeScript
• ⚡ Built for large codebases and monorepos
• 🏗️ Supports TypeScript path aliases and package.json imports and exports map

Installation 📦

Install globally to use as a CLI tool:

yarn global add rev-dep

npm install -g rev-dep

pnpm global add rev-dep

Quick Examples ⚡

A few instant-use examples to get a feel for the tool:

# Detect unused node modules
rev-dep node-modules unused

# Detect circular imports/dependencies
rev-dep circular

# List all entry points in the project
rev-dep entry-points

# Check which files an entry point imports
rev-dep files --entry-point src/index.ts

# Find every entry point that depends on a file
rev-dep resolve --file src/utils/math.ts

# Resolve dependency path between files
rev-dep resolve --file src/utils/math.ts --entry-point src/index.ts

Practical Examples 🔧

Practical examples show how to use rev-dep commands to build code quality checks for your project.

How to identify where a file is used in the project

rev-dep resolve --file path/to/file.ts

You’ll see all entry points that implicitly require that file, along with resolution paths.

How to check if a file is used

rev-dep resolve --file path/to/file.ts --compact-summary

Shows how many entry points indirectly depend on the file.

How to identify dead files

rev-dep entry-points

Exclude framework entry points if needed using --result-exclude.

For example exclude Next.js valid entry points when using pages router, exclude scripts directory - scripts are valid entry-points and exclude all test files:

rev-dep entry-points --result-exclude "pages/**","scripts/**","**/*.test.*"

How to list all files imported by an entry point

rev-dep files --entry-point path/to/file.ts

Useful for identifying heavy components or unintended dependencies.

How to reduce unnecessary imports for an entry point

1. List all files imported:

   rev-dep files --entry-point path/to/entry.ts

2. Identify suspicious files.

3. Trace why they are included:

   rev-dep resolve --file path/to/suspect --entry-points path/to/entry.ts --all

How to detect circular dependencies

rev-dep circular

How to find unused node modules

rev-dep node-modules unused

How to find missing node modules

rev-dep node-modules missing

How to check node_modules space usage

rev-dep node-modules dirs-size

Working with Monorepo

Rev-dep provides first-class support for monorepo projects, enabling accurate dependency analysis across workspace packages.

followMonorepoPackages Flag

The --follow-monorepo-packages flag enables resolution of imports from monorepo workspace packages. By default, this flag is set to false to maintain compatibility with single-package projects.

# Enable monorepo package resolution
rev-dep circular --follow-monorepo-packages
rev-dep resolve --file src/utils.ts --follow-monorepo-packages
rev-dep entry-points --follow-monorepo-packages

When enabled, rev-dep will:

• Detect workspace packages automatically by scanning for monorepo configuration
• Resolve imports between packages within the workspace
• Follow package.json exports for proper module resolution

Exports Map Support

Rev-dep fully supports the exports field in package.json files, which is the standard way to define package entry points in modern Node.js projects.

The exports map support includes:

• Conditional exports using conditions like node, import, default, and custom conditions
• Wildcard patterns for flexible subpath mapping
• Sugar syntax for simple main export definitions
• Nested conditions for complex resolution scenarios

Condition Names Flag

To control which conditional exports are resolved, use the --condition-names flag. This allows you to specify the priority of conditions when resolving package exports:

# Resolve exports for different environments
rev-dep circular --condition-names=node,import,default
rev-dep resolve --file src/utils.ts --condition-names=import,node
rev-dep entry-points --condition-names=default,node,import

The conditions are processed in the order specified, with the first matching condition being used. Common conditions include:

• node - Node.js environment
• import - ES modules
• require - CommonJS
• default - Fallback condition
• Custom conditions specific to your project or build tools

Example package.json with exports:

{
  "name": "@myorg/utils",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.js",
      "default": "./dist/index.js"
    },
    "./helpers": "./dist/helpers.js",
    "./types/*": "./dist/types/*.d.ts"
  }
}

How It Works

1. Monorepo Detection: When followMonorepoPackages is enabled, rev-dep scans for workspace configuration (pnpm-workspace.yaml, package.json workspaces, etc.)

2. Package Resolution: Imports to workspace packages are resolved using the package's exports configuration, falling back to main/module fields when exports are not defined

3. Dependency Validation: The tool validates that cross-package imports are only allowed when the target package is listed in the consumer's dependencies or devDependencies

4. Path Resolution: All paths are resolved relative to their respective package roots, ensuring accurate dependency tracking across the entire monorepo

This makes rev-dep particularly effective for large-scale monorepo projects where understanding cross-package dependencies is crucial for maintaining code quality and architecture.

Config-Based Checks

Rev-dep provides a configuration system for orchestrating project checks. The config approach is designed for speed and is the preferred way of implementing project checks because it can execute all checks in a single pass, significantly faster than multiple running individual commands separately.

Available checks are:

• module boundaries - check if imports respect module boundaries
• import conventions - enforce syntactic consistency for imports (includes autofix capability)
• circular imports - check if there are circular imports
• orphan files - check if there are orphan/dead files
• unused node modules - check against unused node modules
• missing node modules - check against missing node modules

Checks are grouped in rules. You can have multiple rules, eg. for each monorepo package.

Getting Started

Initialize a configuration file in your project:

# Create a default configuration file
rev-dep config init

Behavior of rev-dep config init:

• Monorepo root: Running rev-dep config init at the workspace root creates a root rule and a rule for each discovered workspace package.
• Monorepo workspace package or regular projects: Running rev-dep config init inside a directory creates config with a single rule with path: "." for this directory.

Run all configured checks:

# Execute all rules and checks defined in the config
rev-dep config run

List all detected issues:

# Lists all detected issues, by default lists first five issues for each check
rev-dep config run --list-all-issues

Fix all fixable checks:

# Fix checks configured with autofix
rev-dep config run --fix

Configuration Structure

The configuration file (rev-dep.config.json(c) or .rev-dep.config.json(c)) allows you to define multiple rules, each targeting different parts of your codebase with specific checks enabled.

Here's a comprehensive example showing all available properties:

{
  "configVersion": "1.2",
  "$schema": "https://github.com/jayu/rev-dep/blob/master/config-schema/1.2.schema.json?raw=true", // enables json autocompletion
  "conditionNames": ["import", "default"],
  "ignoreFiles": ["**/*.test.*"],
  "rules": [
    {
      "path": ".",
      "followMonorepoPackages": true,
      "moduleBoundaries": [
        {
          "name": "ui-components",
          "pattern": "src/components/**/*",
          "allow": ["src/utils/**/*", "src/types/**/*"],
          "deny": ["src/api/**/*"]
        },
        {
          "name": "api-layer",
          "pattern": "src/api/**/*",
          "allow": ["src/utils/**/*", "src/types/**/*"],
          "deny": ["src/components/**/*"]
        }
      ],
      "importConventions": [
        {
          "rule": "relative-internal-absolute-external",
          "autofix": true,
          "domains": [
            {
              "path": "src/features/auth",
              "alias": "@auth",
              "enabled": true
            },
            {
              "path": "src/shared/ui",
              "alias": "@ui-kit",
              "enabled": false // checks disabled for this domain, but alias is still used for absolute imports from other domains
            }
          ]
        }
      ],
      "circularImportsDetection": {
        "enabled": true,
        "ignoreTypeImports": true
      },
      "orphanFilesDetection": {
        "enabled": true,
        "validEntryPoints": ["src/index.ts", "src/app.ts"],
        "ignoreTypeImports": true,
        "graphExclude": ["**/*.test.*", "**/stories/**/*"]
      },
      "unusedNodeModulesDetection": {
        "enabled": true,
        "includeModules": ["@myorg/**"],
        "excludeModules": ["@types/**"],
        "pkgJsonFieldsWithBinaries": ["scripts", "bin"],
        "filesWithBinaries": ["scripts/check-something.sh"],
        "filesWithModules": [".storybook/main.ts"],
        "outputType": "groupByModule"
      },
      "missingNodeModulesDetection": {
        "enabled": true,
        "includeModules": ["lodash", "axios"],
        "excludeModules": ["@types/**"],
        "outputType": "groupByFile"
      }
    }
  ]
}

Available Properties

Root Level Properties

• configVersion (required): Configuration version string
• $schema (optional): JSON schema reference for validation
• conditionNames (optional): Array of condition names for exports resolution
• ignoreFiles (optional): Global file patterns to ignore across all rules. Git ignored files are skipped by default.
• rules (required): Array of rule objects

Rule Properties

Each rule can contain the following properties:

• path (required): Target directory path for this rule (either . or path starting with sub directory name)
• followMonorepoPackages (optional): Enable monorepo package resolution (default: true)
• moduleBoundaries (optional): Array of module boundary rules
• circularImportsDetection (optional): Circular import detection configuration
• orphanFilesDetection (optional): Orphan files detection configuration
• unusedNodeModulesDetection (optional): Unused node modules detection configuration
• missingNodeModulesDetection (optional): Missing node modules detection configuration
• importConventions (optional): Array of import convention rules

Module Boundary Properties

• name (required): Name of the boundary
• pattern (required): Glob pattern for files in this boundary
• allow (optional): Array of allowed import patterns
• deny (optional): Array of denied import patterns (overrides allow)

Import Convention Properties

• rule (required): Type of the rule, currently only relative-internal-absolute-external
• autofix (optional): Whether to automatically fix import convention violations (default: false)
• domains (required): Array of domain definitions. Can be a string (glob pattern) or an object with:
  • path (required): Directory with the domain files
  • alias (optional): Alias to be used for absolute imports of code from this domain
  • enabled (optional): Set to false to skip checks for this domain (default: true)

Detection Options Properties

CircularImportsDetection:

• enabled (required): Enable/disable circular import detection
• ignoreTypeImports (optional): Exclude type-only imports when building graph (default: false)

OrphanFilesDetection:

• enabled (required): Enable/disable orphan files detection
• validEntryPoints (optional): Array of valid entry point patterns (eg. ["src/index.ts", "src/main.ts"])
• ignoreTypeImports (optional): Exclude type-only imports when building graph (default: false)
• graphExclude (optional): File patterns to exclude from graph analysis

UnusedNodeModulesDetection:

• enabled (required): Enable/disable unused modules detection
• includeModules (optional): Module patterns to include in analysis
• excludeModules (optional): Module patterns to exclude from analysis
• pkgJsonFieldsWithBinaries (optional): Package.json fields containing binary references (eg. lint-staged). Performs plain-text lookup
• filesWithBinaries (optional): File patterns to search for binary usage. Performs plain-text lookup
• filesWithModules (optional): Non JS/TS file patterns to search for module imports (eg. shell scripts). Performs plain-text lookup
• outputType (optional): Output format - "list", "groupByModule", "groupByFile"

MissingNodeModulesDetection:

• enabled (required): Enable/disable missing modules detection
• includeModules (optional): Module patterns to include in analysis
• excludeModules (optional): Module patterns to exclude from analysis
• outputType (optional): Output format - "list", "groupByModule", "groupByFile"

Performance Benefits

The configuration approach provides significant performance advantages:

• Single Dependency Tree Build: Builds one comprehensive dependency tree for all rules
• 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 all checks

This makes config-based checks faster than running individual commands sequentially, especially for large codebases with multiple sub packages.

Reimplemented to achieve 7x-37x speedup

[email protected] was reimplemented in Go from scratch to leverage it's concurrency features and better memory management of compiled languages.

As a result v2 is up to 37x faster than v1 and consumes up to 13x less memory.

Performance comparison

To compare performance rev-dep was benchmarked with hyperfine using 8 runs per test, taking mean time values as a result. Benchmark was run on TypeScript codebase with 507658 lines of code and 5977 source code files.

Memory usage on Mac was measure using /usr/bin/time utility. Memory usage on Linux was not measured because I could't find reliable way to measure RAM usage on Linux. Subsequent runs had too much fluctuation.

MacBook Pro with Apple M1 chip, 16GB of RAM and 256GB of storage. Power save mode off

| Command | V1 Time | V2 Time | Time Change | V1 RAM | V2 RAM | RAM Change | | ------------------------------------------------------------ | ------- | ------- | ----------- | ------ | ------ | ---------- | | List entry-points rev-dep entry-points | 6500ms | 347ms | 19x | ~680MB | ~51MB | 13x | | List entry-points with dependent files count -pdc | 8333ms | 782ms | 11x | ~885MB | ~110MB | 8x | | List entry-point files rev-dep files | 2729ms | 400ms | 7x | ~330MB | ~36MB | 9x | | Resolve dependency path rev-dep resolve | 2984ms | 359ms | 8x | ~330MB | ~35MB | 9x |

WSL Linux Debian Intel(R) Core(TM) i9-14900KF CPU @ 2.80GHz

| Command | V1 Time | V2 Time | Time Change | | ----------------------------------------------------------------------- | ------- | ------- | ----------- | | List entry-points rev-dep entry-points | 9904ms | 270ms | 37x | | List entry-points with dependent files count --print-deps-count | 10562ms | 458ms | 23x | | List entry-point files rev-dep files | 3097ms | 230ms | 13x | | Resolve dependency path rev-dep resolve | 3146ms | 230ms | 14x |

New features

V2 comes with bunch of new commands

• circular - detects circular dependencies in the project
• lines-of-code - counts actual lines of code in the project excluding comments and blank lines
• list-cwd-files - lists all files in the current working directory
• node-modules used - lists all used node modules
• node-modules unused - lists all unused node modules
• node-modules missing - lists all missing node modules
• node-modules installed - lists all installed node modules
• node-modules installed-duplicates - lists all installed node modules that exist in file system with the same version multiple times
• node-modules analyze-size - analyzes size of specific node modules and helps to identify space-hogging dependencies
• node-modules dirs-size - calculates cumulative files size in node_modules directories

⚠️ What's not supported

Comparing to previous versions, these tsconfig features are not supported

Multiple path aliases

Only first path will be used in resolution.

// tsconfig.json
{
  "paths": {
    "@/components": ["src/components/*", "src/components2/*"]
  }
}

Imports that should resolve to src/components2/* will be considered unresolved.

Why it's not supported? I consider this typescript capability as an anti-pattern. It introduces unnecessary ambiguity in module resolution. Implementing this would make code more complex, less maintainable and slower.

Using rev-dep as node module

Importing rev-dep in JS/TS is no longer supported. Preferred way is to run rev-dep using child process.

Other discrepancies

Any other discrepancies between TypeScript module resolution and rev-dep should be considered as a bug.

Supported Platforms

• Linux x64
• MacOS Apple Silicon
• Windows x64

Go allows for cross-compiling, so I'm happy to build and distribute binaries for other platforms as well. Feel free to open an issue if you need support for another platform.

CLI reference 📖

rev-dep circular

Detect circular dependencies in your project

Synopsis

Analyzes the project to find circular dependencies between modules. Circular dependencies can cause hard-to-debug issues and should generally be avoided.

rev-dep circular [flags]

Examples

rev-dep circular --ignore-types-imports

Options

      --condition-names strings    List of conditions for package.json imports resolution (e.g. node, imports, default)
  -c, --cwd string                 Working directory for the command (default "$PWD")
      --follow-monorepo-packages   Enable resolution of imports from monorepo workspace packages
  -h, --help                       help for circular
  -t, --ignore-type-imports        Exclude type imports from the analysis
      --package-json string        Path to package.json (default: ./package.json)
      --tsconfig-json string       Path to tsconfig.json (default: ./tsconfig.json)
  -v, --verbose                    Show warnings and verbose output

rev-dep config

Create and execute rev-dep configuration files

Synopsis

Commands for creating and executing rev-dep configuration files.

Options

  -c, --cwd string   Working directory (default "$PWD")
  -h, --help         help for config

rev-dep config run

Execute all checks defined in (.)rev-dep.config.json(c)

Synopsis

Process (.)rev-dep.config.json(c) and execute all enabled checks (circular imports, orphan files, module boundaries, node modules) per rule.

rev-dep config run [flags]

Options

      --condition-names strings    List of conditions for package.json imports resolution (e.g. node, imports, default)
  -c, --cwd string                 Working directory (default "$PWD")
      --fix                        Automatically fix fixable issues
      --follow-monorepo-packages   Enable resolution of imports from monorepo workspace packages
  -h, --help                       help for run
      --list-all-issues            List all issues instead of limiting output
      --package-json string        Path to package.json (default: ./package.json)
      --tsconfig-json string       Path to tsconfig.json (default: ./tsconfig.json)
  -v, --verbose                    Show warnings and verbose output

rev-dep config init

Initialize a new rev-dep.config.json file

Synopsis

Create a new rev-dep.config.json configuration file in the current directory with default settings.

rev-dep config init [flags]

Options

  -c, --cwd string   Working directory (default "$PWD")
  -h, --help         help for init

rev-dep entry-points

Discover and list all entry points in the project

Synopsis

Analyzes the project structure to identify all potential entry points. Useful for understanding your application's architecture and dependencies.

rev-dep entry-points [flags]

Examples

rev-dep entry-points --print-deps-count

Options

      --condition-names strings    List of conditions for package.json imports resolution (e.g. node, imports, default)
  -n, --count                      Only display the number of entry points found
  -c, --cwd string                 Working directory for the command (default "$PWD")
      --follow-monorepo-packages   Enable resolution of imports from monorepo workspace packages
      --graph-exclude strings      Exclude files matching these glob patterns from analysis
  -h, --help                       help for entry-points
  -t, --ignore-type-imports        Exclude type imports from the analysis
      --package-json string        Path to package.json (default: ./package.json)
      --print-deps-count           Show the number of dependencies for each entry point
      --result-exclude strings     Exclude files matching these glob patterns from results
      --result-include strings     Only include files matching these glob patterns in results
      --tsconfig-json string       Path to tsconfig.json (default: ./tsconfig.json)
  -v, --verbose                    Show warnings and verbose output

rev-dep files

List all files in the dependency tree of an entry point

Synopsis

Recursively finds and lists all files that are required by the specified entry point.

rev-dep files [flags]

Examples

rev-dep files --entry-point src/index.ts

Options

      --condition-names strings    List of conditions for package.json imports resolution (e.g. node, imports, default)
  -n, --count                      Only display the count of files in the dependency tree
  -c, --cwd string                 Working directory for the command (default "$PWD")
  -p, --entry-point string         Entry point file to analyze (required)
      --follow-monorepo-packages   Enable resolution of imports from monorepo workspace packages
  -h, --help                       help for files
  -t, --ignore-type-imports        Exclude type imports from the analysis
      --package-json string        Path to package.json (default: ./package.json)
      --tsconfig-json string       Path to tsconfig.json (default: ./tsconfig.json)
  -v, --verbose                    Show warnings and verbose output

rev-dep imported-by

List all files that directly import the specified file

Synopsis

Finds and lists all files in the project that directly import the specified file. This is useful for understanding the impact of changes to a particular file.

rev-dep imported-by [flags]

Examples

rev-dep imported-by --file src/utils/helpers.ts

Options

      --condition-names strings    List of conditions for package.json imports resolution (e.g. node, imports, default)
  -n, --count                      Only display the count of importing files
  -c, --cwd string                 Working directory for the command (default "$PWD")
  -f, --file string                Target file to find importers for (required)
      --follow-monorepo-packages   Enable resolution of imports from monorepo workspace packages
  -h, --help                       help for imported-by
      --list-imports               List the import identifiers used by each file
      --package-json string        Path to package.json (default: ./package.json)
      --tsconfig-json string       Path to tsconfig.json (default: ./tsconfig.json)
  -v, --verbose                    Show warnings and verbose output

rev-dep lines-of-code

Count actual lines of code in the project excluding comments and blank lines

rev-dep lines-of-code [flags]

Examples

rev-dep lines-of-code

Options

  -c, --cwd string   Directory to analyze (default "$PWD")
  -h, --help         help for lines-of-code

rev-dep list-cwd-files

List all files in the current working directory

Synopsis

Recursively lists all files in the specified directory, with options to filter results.

rev-dep list-cwd-files [flags]

Examples

rev-dep list-cwd-files --include='*.ts' --exclude='*.test.ts'

Options

      --count             Only display the count of matching files
      --cwd string        Directory to list files from (default "$PWD")
      --exclude strings   Exclude files matching these glob patterns
  -h, --help              help for list-cwd-files
      --include strings   Only include files matching these glob patterns

rev-dep node-modules

Analyze and manage Node.js dependencies

Synopsis

Tools for analyzing and managing Node.js module dependencies. Helps identify unused, missing, or duplicate dependencies in your project.

Examples

  rev-dep node-modules used -p src/index.ts
  rev-dep node-modules unused --exclude-modules=@types/*
  rev-dep node-modules missing --entry-points=src/main.ts

Options

  -h, --help   help for node-modules

rev-dep node-modules dirs-size

Calculates cumulative files size in node_modules directories

Synopsis

Calculates and displays the size of node_modules folders in the current directory and subdirectories. Sizes will be smaller than actual file size taken on disk. Tool is calculating actual file size rather than file size on disk (related to disk blocks usage)

rev-dep node-modules dirs-size [flags]

Examples

rev-dep node-modules dirs-size

Options

  -c, --cwd string   Working directory for the command (default "$PWD")
  -h, --help         help for dirs-size

rev-dep node-modules installed-duplicates

Find and optimize duplicate package installations

Synopsis

Identifies packages that are installed multiple times in node_modules. Can optimize storage by creating symlinks between duplicate packages.

rev-dep node-modules installed-duplicates [flags]

Examples

rev-dep node-modules installed-duplicates --optimize --size-stats

Options

  -c, --cwd string   Working directory for the command (default "$PWD")
  -h, --help         help for installed-duplicates
      --isolate      Create symlinks only within the same top-level node_module directories. By default optimize creates symlinks between top-level node_module directories (eg. when workspaces are used). Needs --optimize flag to take effect
      --optimize     Automatically create symlinks to deduplicate packages
      --size-stats   Print node modules dirs size before and after optimization. Might take longer than optimization itself
      --verbose      Show detailed information about each optimization

rev-dep node-modules installed

List all installed npm packages in the project

Synopsis

Recursively scans node_modules directories to list all installed packages. Helpful for auditing dependencies across monorepos.

rev-dep node-modules installed [flags]

Examples

rev-dep node-modules installed --include-modules=@myorg/*

Options

  -c, --cwd string                Working directory for the command (default "$PWD")
  -e, --exclude-modules strings   list of modules to exclude from the output
  -h, --help                      help for installed
  -i, --include-modules strings   list of modules to include in the output

rev-dep node-modules missing

Find imported packages not listed in package.json

Synopsis

Identifies packages that are imported in your code but not declared in your package.json dependencies.

rev-dep node-modules missing [flags]

Examples

rev-dep node-modules missing --entry-points=src/main.ts

Options

      --condition-names strings            List of conditions for package.json imports resolution (e.g. node, imports, default)
  -n, --count                              Only display the count of modules
  -c, --cwd string                         Working directory for the command (default "$PWD")
  -p, --entry-points strings               Entry point file(s) to start analysis from (default: auto-detected)
  -e, --exclude-modules strings            list of modules to exclude from the output
  -b, --files-with-binaries strings        Additional files to search for binary usages. Use paths relative to cwd
  -m, --files-with-node-modules strings    Additional files to search for module imports. Use paths relative to cwd
      --follow-monorepo-packages           Enable resolution of imports from monorepo workspace packages
      --group-by-file                      Organize output by project file path
      --group-by-module                    Organize output by npm package name
  -h, --help                               help for missing
  -t, --ignore-type-imports                Exclude type imports from the analysis
  -i, --include-modules strings            list of modules to include in the output
      --package-json string                Path to package.json (default: ./package.json)
      --pkg-fields-with-binaries strings   Additional package.json fields to check for binary usages
      --tsconfig-json string               Path to tsconfig.json (default: ./tsconfig.json)
  -v, --verbose                            Show warnings and verbose output
      --zero-exit-code                     Use this flag to always return zero exit code

rev-dep node-modules unused

Find installed packages that aren't imported in your code

Synopsis

Compares package.json dependencies with actual imports in your codebase to identify potentially unused packages.

rev-dep node-modules unused [flags]

Examples

rev-dep node-modules unused --exclude-modules=@types/*

Options

      --condition-names strings            List of conditions for package.json imports resolution (e.g. node, imports, default)
  -n, --count                              Only display the count of modules
  -c, --cwd string                         Working directory for the command (default "$PWD")
  -p, --entry-points strings               Entry point file(s) to start analysis from (default: auto-detected)
  -e, --exclude-modules strings            list of modules to exclude from the output
  -b, --files-with-binaries strings        Additional files to search for binary usages. Use paths relative to cwd
  -m, --files-with-node-modules strings    Additional files to search for module imports. Use paths relative to cwd
      --follow-monorepo-packages           Enable resolution of imports from monorepo workspace packages
  -h, --help                               help for unused
  -t, --ignore-type-imports                Exclude type imports from the analysis
  -i, --include-modules strings            list of modules to include in the output
      --package-json string                Path to package.json (default: ./package.json)
      --pkg-fields-with-binaries strings   Additional package.json fields to check for binary usages
      --tsconfig-json string               Path to tsconfig.json (default: ./tsconfig.json)
  -v, --verbose                            Show warnings and verbose output
      --zero-exit-code                     Use this flag to always return zero exit code

rev-dep node-modules used

List all npm packages imported in your code

Synopsis

Analyzes your code to identify which npm packages are actually being used. Helps keep track of your project's runtime dependencies.

rev-dep node-modules used [flags]

Examples

rev-dep node-modules used -p src/index.ts --group-by-module

Options

      --condition-names strings            List of conditions for package.json imports resolution (e.g. node, imports, default)
  -n, --count                              Only display the count of modules
  -c, --cwd string                         Working directory for the command (default "$PWD")
  -p, --entry-points strings               Entry point file(s) to start analysis from (default: auto-detected)
  -e, --exclude-modules strings            list of modules to exclude from the output
  -b, --files-with-binaries strings        Additional files to search for binary usages. Use paths relative to cwd
  -m, --files-with-node-modules strings    Additional files to search for module imports. Use paths relative to cwd
      --follow-monorepo-packages           Enable resolution of imports from monorepo workspace packages
      --group-by-file                      Organize output by project file path
      --group-by-module                    Organize output by npm package name
  -h, --help                               help for used
  -t, --ignore-type-imports                Exclude type imports from the analysis
  -i, --include-modules strings            list of modules to include in the output
      --package-json string                Path to package.json (default: ./package.json)
      --pkg-fields-with-binaries strings   Additional package.json fields to check for binary usages
      --tsconfig-json string               Path to tsconfig.json (default: ./tsconfig.json)
  -v, --verbose                            Show warnings and verbose output

rev-dep resolve

Trace and display the dependency path between files in your project

Synopsis

Analyze and display the dependency chain between specified files. Helps understand how different parts of your codebase are connected.

rev-dep resolve [flags]

Examples

rev-dep resolve -p src/index.ts -f src/utils/helpers.ts

Options

  -a, --all                        Show all possible resolution paths, not just the first one
      --compact-summary            Display a compact summary of found paths
      --condition-names strings    List of conditions for package.json imports resolution (e.g. node, imports, default)
  -c, --cwd string                 Working directory for the command (default "$PWD")
  -p, --entry-points strings       Entry point file(s) to start analysis from (default: auto-detected)
  -f, --file string                Target file to check for dependencies
      --follow-monorepo-packages   Enable resolution of imports from monorepo workspace packages
      --graph-exclude strings      Glob patterns to exclude files from dependency analysis
  -h, --help                       help for resolve
  -t, --ignore-type-imports        Exclude type imports from the analysis
      --package-json string        Path to package.json (default: ./package.json)
      --tsconfig-json string       Path to tsconfig.json (default: ./tsconfig.json)
  -v, --verbose                    Show warnings and verbose output

Circular check performance comparison

Benchmark performed on TypeScript codebase with 6034 source code files and 518862 lines of code.

Benchmark performed on MacBook Pro with Apple M1 chip, 16GB of RAM and 256GB of Storage. Power save mode off.

Benchmark performed with hyperfine using 8 runs per test and 4 warm up runs, taking mean time values as a result. If single run was taking more than 10s, only 1 run was performed.

rev-dep circular check is 12 times faster than the fastest alternative❗

| Tool | Version | Command to Run Circular Check | Time | |------|---------|-------------------------------|------| | 🥇 rev-dep | 2.0.0 | rev-dep circular | 397 ms | | 🥈 dpdm-fast | 1.0.14 | dpdm --no-tree --no-progress --no-warning + list of directories with source code | 4960 ms | | 🥉 dpdm | 3.14.0 | dpdm --no-warning + list of directories with source code | 5030 ms | | skott | 0.35.6 | node script using skott findCircularDependencies function | 29575 ms | | madge | 8.0.0 | madge --circular --extensions js,ts,jsx,tsx . | 69328 ms | | circular-dependency-scanner | 2.3.0 | ds - out of memory error | n/a |

Glossary

Some of the terms used in the problem space that rev-dep covers can be confusing. Here is a small glossary to help you navigate the concepts.

Dependency

A dependency can be understood literally. In the context of a project’s dependency graph, it may refer to:

• a node module / package (a package is a dependency of a project or file), or
• a source code file (a file is a dependency of another file if it imports it).

Entry point

An entry point is a source file that is not imported by any other file. It can represent:

• the main entry of the application
• an individual page or feature
• configuration or test bootstrap files

— depending on the project structure.

Unused / Dead file

A file is considered unused or dead when:

• it is an entry point (nothing imports it), and
• running it does not produce any meaningful output or side effect.

In practice, such files can often be removed safely.

Circular dependency

A circular dependency occurs when a file directly or indirectly imports itself through a chain of imports.

This can lead to unpredictable runtime behavior, uninitialized values, or subtle bugs. However, circular dependencies between TypeScript type-only imports are usually harmless.

Reverse dependency (or "dependents")

Files that import a given file. Useful for answering: "What breaks if I change or delete this file?"

Import graph / Dependency graph

A visual representation of how files or modules import each other.

Missing dependency / unused node module

A module that your code imports but is not listed in package.json.

Unused dependency / unused node module

A dependency listed in package.json that is never imported in the source code.

Root directory / Project root

The top-level directory used as the starting point for dependency analysis.

Made in 🇵🇱 and 🇯🇵 with 🧠 by @jayu

I hope that this small piece of software will help you discover and understood complexity of your project hence make you more confident while refactoring. If this tool was useful, don't hesitate to give it a ⭐!