📊 Component Dependency Visualizer

Visualize React component dependencies and detect circular references with an interactive D3.js graph

✨ Features

• 🔍 Automatic Component Detection - Scans your React/TypeScript project for components
• 📈 Interactive Visualization - Beautiful D3.js force-directed graph
• 🔄 Circular Dependency Detection - Finds and highlights circular dependencies
• 📦 Orphan Component Detection - Identifies unused components with no dependents
• 📏 File Size Analysis - Shows lines of code and file sizes for each component
• 📊 Detailed Statistics - Component counts, dependency metrics, and complexity analysis
• 🎨 Color-Coded Nodes - Visual indicators for circular dependencies, orphans, and highly connected components
• 🖱️ Interactive Controls - Toggle labels, arrows, and highlighting
• 💾 HTML Export - Generates standalone HTML file you can share with your team

🚀 Quick Start

Using npx (No Installation Required) ⚡

The fastest way to analyze your project - no installation needed!

npx component-dependency-visualizer src

Installation Options

Global Installation

npm install -g component-dependency-visualizer
# or
pnpm add -g component-dependency-visualizer
# or
yarn global add component-dependency-visualizer

Local Installation

npm install --save-dev component-dependency-visualizer
# or
pnpm add -D component-dependency-visualizer

📖 Usage

With npx (Recommended)

Analyze your entire src directory:

npx component-dependency-visualizer src

Analyze a specific directory:

npx component-dependency-visualizer src/components

Specify custom output path:

npx component-dependency-visualizer src/components -o my-graph.html

Don't open browser automatically:

npx component-dependency-visualizer src/components --no-open

With Global Installation

If you installed globally, use the shorter command:

comp-viz src
comp-viz src/components
comp-viz src/components -o my-graph.html
comp-viz src/components --no-open

In package.json

{
  "scripts": {
    "analyze": "comp-viz src/components"
  }
}

Then run:

npm run analyze

📸 What's in the HTML Visualization

The generated HTML includes:

• Interactive Graph - Drag nodes, zoom in/out
• Statistics Panel - Total components, dependencies, lines of code, orphan count, and more
• Circular Dependencies List - All detected cycles with file paths
• Orphan Components List - Unused components with their file paths and line counts
• Enhanced Tooltips - Hover over nodes to see dependencies, lines, and file size
• Legend - Color coding explanation
• Controls - Toggle visibility options

Color Coding

• 🔵 Blue - Normal component
• 🔴 Red - Part of a circular dependency
• ⚫ Gray - Orphan component (unused, no dependents)
• 🟡 Orange - High number of dependencies (>3)

🎯 What It Detects

Component Files

• React components (.tsx, .jsx)
• TypeScript/JavaScript files (.ts, .js)
• Automatically filters out:
  • index files
  • Utility/helper files
  • Config files
  • Test files (.test.*, .spec.*)

Import Types

• Relative imports (./Component, ../shared/Button)
• Alias imports (@/components/Button)

Metrics

• Total components
• Total dependencies
• Total lines of code
• Average lines per file
• Circular dependencies count
• Orphan components count
• Largest file by lines
• Maximum dependency depth
• Most depended-on component
• Component with most dependencies

🔧 How It Works

1. File Scanning - Uses glob patterns to find component files
2. AST Parsing - Parses files with Babel to extract import statements
3. File Analysis - Analyzes file size and line count for each component
4. Graph Building - Constructs dependency graph from imports
5. Cycle Detection - Runs DFS algorithm to find circular dependencies
6. Orphan Detection - Identifies components with no dependents (excluding entry points)
7. Visualization - Generates interactive D3.js force-directed graph with all metrics

📦 Example Output

📊 Component Dependency Visualizer

Analyzing: /Users/dev/my-app/src/components
Output: /Users/dev/my-app/dependency-graph.html

📈 Summary:
──────────────────────────────────────────────────
Components:        42
Dependencies:      89
Max Depth:         5
Total Lines:       3,847
Avg Lines/File:    92
Circular Deps:     2
Orphan Components: 3 (unused)
Most Depended On:  Button.tsx (12 refs)
Most Dependencies: Dashboard.tsx (8 deps)
Largest File:      Dashboard.tsx (342 lines)
──────────────────────────────────────────────────

⚠️  Circular Dependencies Detected:

  1. UserProfile.tsx → UserPosts.tsx → UserProfile.tsx
  2. Cart.tsx → CartItem.tsx → Cart.tsx

📦 Orphan Components (Unused Files):

  1. OldButton.tsx (components/deprecated/OldButton.tsx)
  2. TestComponent.tsx (components/test/TestComponent.tsx)
  3. UnusedModal.tsx (components/modals/UnusedModal.tsx)

✅ Visualization saved to: dependency-graph.html

📁 Project Structure

component-dependency-visualizer/
├── src/
│   ├── scanner/
│   │   ├── fileScanner.ts      # File discovery
│   │   └── parser.ts            # AST parsing
│   ├── analyzer/
│   │   ├── dependencyGraph.ts   # Graph construction
│   │   ├── circularDetector.ts  # Cycle detection
│   │   ├── fileAnalyzer.ts      # File size analysis
│   │   ├── orphanDetector.ts    # Orphan component detection
│   │   └── index.ts             # Main analyzer
│   ├── visualizer/
│   │   └── htmlGenerator.ts     # HTML generation
│   ├── types/
│   │   └── index.ts             # TypeScript types
│   └── cli.ts                   # CLI interface
├── templates/
│   └── graph.html               # D3.js visualization template
└── examples/                    # Example components

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 License

MIT © y00eunji

🙏 Acknowledgments

• D3.js - Data visualization
• Babel - AST parsing
• Commander.js - CLI framework
• Chalk - Terminal colors
• Ora - Loading spinner

🐛 Known Issues

• Does not yet support dynamic imports
• Vue and Svelte support coming soon
• Path alias resolution limited to @/ pattern

Made with 💜 by developers, for developers

If this tool helped you, please consider giving it a ⭐ on GitHub!