A fast TypeScript CLI tool that generates module dependency graphs from JavaScript/TypeScript codebases using ripgrep for blazing-fast performance.
- 🚀 Lightning fast - uses ripgrep for parallel file searching
- 📊 Generates comprehensive dependency graphs in JSON format
- 🔍 Supports both ES modules and CommonJS
- 🎯 Handles TypeScript path aliases from tsconfig.json
- 🌳 Identifies root nodes (entry points) automatically
- 📁 Works with .js, .jsx, .ts, .tsx, and .mjs files
npm install -g modgraphYou can use modgraph directly with npx without installing it:
npx modgraphAnalyze all files in the current directory:
modgraph
# or with npx
npx modgraphAnalyze dependencies starting from specific files:
modgraph src/index.ts src/cli.ts
# or with npx
npx modgraph src/index.ts src/cli.tsSave the dependency graph to a JSON file:
modgraph --output dependency-graph.json
# or with npx
npx modgraph --output dependency-graph.jsonUse a custom TypeScript configuration file:
modgraph --config ./path/to/tsconfig.json
# or with npx
npx modgraph --config ./path/to/tsconfig.jsonExclude files matching glob patterns:
modgraph --exclude "**/*.test.ts" "**/*.spec.ts"
# or with npx
npx modgraph --exclude "**/*.test.ts" "**/*.spec.ts"The tool generates a JSON object with the following structure:
{
"rootNodes": ["src/index.ts", "src/cli.ts"],
"modules": {
"src/index.ts": {
"dependencies": ["src/utils/parser.ts", "lodash"],
"dependents": []
},
"src/utils/parser.ts": {
"dependencies": ["fs", "path"],
"dependents": ["src/index.ts"]
}
},
"metadata": {
"cwd": "/home/user/my-project",
"totalFiles": 42,
"totalDependencies": 156,
"generatedAt": "2025-06-19T10:30:00Z"
}
}- rootNodes: Array of files that have no dependents (entry points)
- modules: Object mapping file paths to their dependencies and dependents
- dependencies: Files that this module imports
- dependents: Files that import this module
- metadata: Additional information about the scan
- cwd: Current working directory
- totalFiles: Number of files in the dependency graph
- totalDependencies: Total number of import relationships
- generatedAt: ISO timestamp of when the graph was generated
modgraph includes built-in support for the Model Context Protocol, allowing AI assistants to analyze your codebase structure.
modgraph mcp
# or with npx
npx modgraph mcpThis starts an MCP server via stdio that exposes the analyze tool.
Add the following to your Claude Desktop configuration:
{
"mcpServers": {
"modgraph": {
"command": "npx",
"args": ["modgraph", "mcp"]
}
}
}Or if you have modgraph installed globally:
{
"mcpServers": {
"modgraph": {
"command": "modgraph",
"args": ["mcp"]
}
}
}Generates a module dependency graph with the following parameters:
directory(required): The directory to analyzeentryPoints(optional): Specific entry point files to analyzetsConfigPath(optional): Path to tsconfig.jsonexcludePatterns(optional): Glob patterns to excludedebug(optional): Include debug information
Example usage in an AI assistant:
Use the analyze tool to understand the structure of /path/to/project
The tool recognizes various import/require patterns:
- Named imports:
import { foo } from './bar' - Default imports:
import foo from './bar' - Namespace imports:
import * as foo from './bar' - Dynamic imports:
import('./bar') - Side effect imports:
import './bar'
- Basic require:
const foo = require('./bar') - Destructured require:
const { foo } = require('./bar')
- Path aliases from tsconfig.json (e.g.,
@utils/*,@/components) - Recognizes .ts, .tsx extensions
- Handles index file resolution
modgraph is designed to handle large codebases efficiently:
- Can analyze 10,000+ files in under 5 seconds
- Uses ripgrep's parallel search capabilities
- Streams results to minimize memory usage
# Clone the repository
git clone https://github.com/yourusername/modgraph.git
cd modgraph
# Install dependencies
npm install
# Run in development mode
npm run dev
# Build for production
npm run build
# Run tests
npm testMIT
Contributions are welcome! Please feel free to submit a Pull Request.