CtrlK
BlogDocsLog inGet started
Tessl Logo

testland/madge-deps

Run Madge against a JS/TS production source tree to detect circular dependencies, find orphan modules, and visualize the module graph. Scoped to production code via `excludeRegExp` for test files. Use when a build compiles but throws `Cannot read property X of undefined` on a module that is clearly imported, or when a repo needs a CI gate that blocks new import cycles.

79

Quality

99%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

SecuritybySnyk

Passed

No findings from the security scan

Overview
Quality
Evals
Security
Files
name:
madge-deps
description:
Run Madge against a JS/TS production source tree to detect circular dependencies, find orphan modules, and visualize the module graph. Scoped to production code via `excludeRegExp` for test files. Use when a build compiles but throws `Cannot read property X of undefined` on a module that is clearly imported, or when a repo needs a CI gate that blocks new import cycles.
metadata:
{"keywords":"madge, circular-dependency, module-graph, dependency-analysis, javascript, typescript"}

madge-deps

Madge analyzes JavaScript module graphs (AMD, CommonJS, ES6) and CSS preprocessor imports (Sass, Stylus, Less) per the Madge README. NPM deps and Node core modules are excluded by default.

When to use

  • A bundle that compiles but throws Cannot read property X of undefined at runtime - likely a circular import causing partial module init.
  • Pre-merge gate to block any new circular dep.
  • Finding orphan files (no imports + no exports referenced) to delete.

Step 1 - Install

npm install -g madge
# or per-project
npm install -D madge

Optional Graphviz for visual graphs:

OSInstall
macOSbrew install graphviz
Ubuntuapt-get install graphviz
Windowschoco install graphviz

Per the Madge README.

Step 2 - Detect circular dependencies

# Single entry point
madge --circular src/index.ts

# Whole directory
madge --circular src/

Exit code: 0 if none found, 1 if any circular path exists. Use directly in CI.

Step 3 - Find orphans + leaves

# Files imported by nothing
madge --orphans src/

# Files that import nothing (terminal modules)
madge --leaves src/

Orphans are deletion candidates; verify usage outside source tree (scripts, configs, side-effect imports) before removal.

Step 4 - Visualize

# Render full graph as SVG (requires Graphviz)
madge --image graph.svg src/

# Show what depends on a specific file
madge --depends src/config/db.ts src/

# Export raw DOT for custom rendering
madge --dot src/ > graph.gv

Step 5 - Configure for production-only scope

.madgerc in project root:

{
  "fileExtensions": ["ts", "tsx", "js", "jsx"],
  "excludeRegExp": [
    "\\.test\\.(ts|tsx|js|jsx)$",
    "\\.spec\\.(ts|tsx|js|jsx)$",
    "__tests__/",
    "__mocks__/",
    "node_modules/",
    "dist/",
    "build/"
  ],
  "tsConfig": "tsconfig.json"
}

Test files are excluded so tests can intentionally import production modules without flagging the production tree.

Step 6 - CI gate

# GitHub Actions
- name: Block circular deps
  run: npx madge --circular --extensions ts,tsx src/

- name: Detect new orphans (advisory)
  run: npx madge --orphans --extensions ts,tsx src/ || true

The first step fails on any circular path; the second is informational only (orphans require human judgment - could be webpack entry, dynamic import, etc.).

Anti-patterns

Anti-patternWhy it failsFix
Scan whole repo including node_modules/OOM on large workspacesexcludeRegExp: ["node_modules/"] (Step 5) - actually default behavior, but verify
Treat orphans as "always delete"Webpack/Vite entry points + dynamic imports look orphanedManual review per orphan; use --depends to verify (Step 4)
Allow circular deps in non-prod with "we'll fix later"Cycles compound; mid-project untangling is brutalBlock on first cycle (Step 6); waiver template if scope-exclusion needed
Forget tsconfig.json for path aliasesMadge can't resolve @/foo imports; reports false positives"tsConfig": "tsconfig.json" in .madgerc (Step 5)
Run with default extensions (js only) for TS projectMisses 100% of TS filesfileExtensions: ["ts", "tsx", "js", "jsx"] (Step 5)

Limitations

  • Madge resolves static imports only; dynamic import() calls and require() with computed strings are not in the graph.
  • ESM-only projects: ensure Madge version supports your Node ESM resolver. Check the Madge README for current ESM compat notes.

References

  • Madge README - CLI flags, .madgerc schema, extension support
Workspace
testland
Visibility
Public
Created
Last updated
Repository
https://github.com/testland/qa
Publish Source
GitHub
Badge
testland/madge-deps badge