A powerful heap analyzer for Node.js memory profiling and leak detection
npm install heap-analyzerA CLI and agent tool for analyzing JavaScript heap snapshots from Google DevTools. Helps developers trace memory issues, browser crashes, and provides actionable insights for fixing leaks in JavaScript apps.
- š„ļø Interactive CLI for guided manual analysis
- š¤ Agent Mode for automated analysis and reporting
- ļæ½ Enhanced Compare Mode for detailed before/after analysis
- ļ潚 Continuous Monitoring with watch mode
- š Memory leak detection with categorized insights
- š” Actionable recommendations for optimization
- š JSON reports for CI/CD integration
- š Markdown reports for documentation and sharing
- šÆ Smart categorization of memory consumers
Install as a dev dependency:
``sh`
npm install --save-dev heap-analyzer
š Quick Start: For immediate heap analysis, see AGENT.md - zero-config automated analysis guide.
š§ Real-Time Debugging: For browser console debugging snippets, see DEBUGGING_SNIPPETS.md - intercept and track leaks as they happen.
heap-analyzer is a complete memlab wrapper that provides all memlab functionality with better developer experience and easier file management.
#### Memory Leak Detection
`shBasic leak detection (2-3 snapshots)
npx heap-analyzer find-leaks --baseline before.heapsnapshot --target after.heapsnapshot
npx heap-analyzer find-leaks --baseline baseline.heapsnapshot --target target.heapsnapshot --final final.heapsnapshot
#### Growth Analysis (Our Enhancement)
sh
Compare memory growth between snapshots
npx heap-analyzer compare before.heapsnapshot after.heapsnapshotSingle snapshot analysis
npx heap-analyzer analyze snapshot.heapsnapshot
`#### Interactive Heap Exploration
sh
Interactive heap exploration (memlab wrapper)
npx heap-analyzer heap snapshot.heapsnapshotHeap visualization (memlab wrapper)
npx heap-analyzer view-heap snapshot.heapsnapshot
npx heap-analyzer view-heap snapshot.heapsnapshot --node-id 12345
`#### Retainer Trace Analysis
sh
Analyze why specific objects are retained (memlab wrapper)
npx heap-analyzer trace snapshot.heapsnapshot --node-id 12345
`#### Node.js Server Analysis
sh
Take heap snapshot from running Node.js process
npx heap-analyzer node-snapshot --endpoint http://localhost:3000/debug/heap-snapshot
npx heap-analyzer node-snapshot --pid 12345Monitor Node.js process memory and auto-snapshot on high usage
npx heap-analyzer node-monitor --pid 12345 --threshold 500 --interval 5Load test with automatic heap snapshot collection
npx heap-analyzer node-load-test http://localhost:3000/api/heavy \
--endpoint http://localhost:3000/debug/heap-snapshot \
--concurrency 50 --duration 60
`#### Analysis Plugins
sh
Run memlab analysis plugins (memlab wrapper)
npx heap-analyzer analyze-plugin string-analysis
npx heap-analyzer analyze-plugin
`#### File Management
sh
List available snapshots
npx heap-analyzer list
`$3
All memlab commands work directly with better path resolution:
sh
Advanced leak detection with filtering
npx memlab find-leaks --baseline snapshots/sim-1.heapsnapshot --target snapshots/sim-2.heapsnapshot --trace-object-size-above 1000000Compare different leak sets
npx memlab diff-leaks --control-snapshot snapshots/before.heapsnapshot --treatment-snapshot snapshots/after.heapsnapshotML-based clustering
npx memlab find-leaks --baseline snapshots/baseline.heapsnapshot --target snapshots/target.heapsnapshot --ml-clustering
`$3
Core Commands:
-
- Run memlab leak detection (wrapper for memlab find-leaks)
- compare - Compare memory growth between snapshots
- analyze - Analyze single heap snapshot
- trace - Analyze retainer traces (wrapper for memlab trace)
- heap - Interactive heap exploration (wrapper for memlab heap)
- view-heap - Heap visualization (wrapper for memlab view-heap)
- analyze-plugin - Run analysis plugins (wrapper for memlab analyze)
- list - List available snapshotsOptions:
-
--baseline - Baseline snapshot (initial state)
- --target - Target snapshot (after action)
- --final - Final snapshot (after cleanup) - optional
- --snapshot-dir - Directory containing snapshots
- --node-id - Node ID for retainer trace analysis
- --help, -h - Show help informationFile Path Resolution:
- Automatically finds files in
./snapshots/ directory
- Supports relative and absolute paths
- Smart error handling for missing filesComplete Memlab Wrapper Features
All Memlab Commands Available:
- find-leaks: Sophisticated memory leak detection with retainer traces
- trace: Analyze specific object retention paths
- heap: Interactive heap exploration and querying
- view-heap: Visual heap inspection with node focusing
- analyze: Plugin-based heap analysis
- diff-leaks: Compare leak sets between different snapshots
Enhanced Developer Experience:
- Smart Path Resolution: Automatically finds files in
./snapshots/ directory
- Better Error Messages: Clear guidance when files are missing or invalid
- Consistent Interface: All memlab commands follow the same pattern
- File Validation: Checks file existence before running expensive operations
- Progress Indication: Shows what's happening before delegating to memlabGrowth Analysis (Our Addition):
- Memory Growth Tracking: Detailed size and object count comparisons
- Object Type Breakdown: See which types (Arrays, Objects, Strings) grew most
- Growth Pattern Detection: Identify data accumulation vs object creation patterns
- Actionable Insights: Specific recommendations based on growth patterns
$3
The heap analyzer detects memory leaks using only snapshot data, without requiring:
- Component source code access
- Global variable names or application structure
- Specific collection types or framework details
- Exact growth mechanisms or application logic
This snapshot-isolated approach ensures accurate leak detection across any JavaScript application, regardless of framework or implementation patterns.
Examples
$3
#### Basic Leak Detection
`sh
1. List available snapshots
npx heap-analyzer list2. Run leak detection
npx heap-analyzer find-leaks --baseline before.heapsnapshot --target after.heapsnapshot3. If leaks found, analyze specific objects
npx heap-analyzer trace after.heapsnapshot --node-id 12345
`#### Growth Analysis Workflow
sh
1. Compare memory growth
npx heap-analyzer compare baseline.heapsnapshot target.heapsnapshot2. Interactive exploration of larger snapshot
npx heap-analyzer heap target.heapsnapshot3. Visual inspection
npx heap-analyzer view-heap target.heapsnapshot
`#### Advanced Analysis
sh
1. Run memlab's sophisticated leak detection
npx heap-analyzer find-leaks --baseline baseline.heapsnapshot --target target.heapsnapshot --final final.heapsnapshot2. Compare different approaches to same feature
npx memlab diff-leaks --control-snapshot snapshots/approach-a.heapsnapshot --treatment-snapshot snapshots/approach-b.heapsnapshot3. Run analysis plugins for specific insights
npx heap-analyzer analyze-plugin string-analysis
`$3
Growth Analysis Output:
š Growth Analysis:
Memory growth: 50.01 MB
Growth percentage: 239.7%š Object Type Analysis:
š array: +49.74 MB (+13,022 objects)
š object: +0.20 MB (+13,076 objects)
š” Growth Pattern Analysis:
š High memory growth with low object count growth
šÆ This suggests existing objects got larger (data accumulation)
š Check: Arrays growing, string concatenation, cache buildup
Memlab Leak Detection Output:
Alive objects allocated in target page:
āāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāā¬āāāāāāāā¬āāāāāāāāāāāāāāā
ā (index) ā name ā type ā count ā retainedSize ā
āāāāāāāāāāā¼āāāāāāāāāāāāāāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāā¼āāāāāāāā¼āāāāāāāāāāāāāāā¤
ā 0 ā 'Array' ā 'object' ā 13020 ā '52.3MB' ā
ā 1 ā 'MouseEvent' ā 'object' ā 2 ā '2.2KB' ā
āāāāāāāāāāā“āāāāāāāāāāāāāāāāāāāāāāāāāāāāā“āāāāāāāāāāāāāā“āāāāāāāā“āāāāāāāāāāāāāāāNo leaks found - Memory growth is legitimate application behavior
Development Tools
$3
For deep inspection of specific suspicious objects found in your analysis:
sh
npm run inspect-object
`When to use:
- Investigate specific objects flagged in main analysis
- Understand object relationships and retention paths
- Debug circular references and memory ownership
- Analyze large objects consuming significant memory
Example workflow:
sh
1. Run main analysis to find suspects
npm run dev compareOutput shows: "š“ userCache (HIGH) - Node ID: 287534"
2. Deep dive into the suspicious object
npm run inspect-object snapshots/after.heapsnapshot 2875343. Get detailed analysis with retainer chains, references, and fix recommendations
`The Object Content Analyzer provides:
- Detailed object properties and memory breakdown
- Reference mapping (what objects it points to)
- Referrer analysis (what objects point to it)
- Retainer chains showing exactly what keeps objects alive
- Circular reference detection with cycle mapping
- Actionable recommendations for specific object types
š Full documentation: docs/OBJECT_CONTENT_ANALYZER.md
CI/CD Integration
Perfect for automated memory analysis in CI/CD pipelines:
yaml
GitHub Actions example
- name: Memory Leak Detection
run: |
# Generate snapshots in your test suite
npm run test:memory-snapshots
# Run leak detection
npx heap-analyzer find-leaks --baseline snapshots/baseline.heapsnapshot --target snapshots/after-test.heapsnapshot
# Growth analysis for performance monitoring
npx heap-analyzer compare snapshots/baseline.heapsnapshot snapshots/after-test.heapsnapshotGitLab CI example
memory_analysis:
script:
- npx heap-analyzer find-leaks --snapshot-dir ./test-snapshots/
- npx heap-analyzer analyze-plugin string-analysis
artifacts:
reports:
# Save memlab output for later analysis
expire_in: 1 week
`$3
sh
Set up automated snapshot comparison
npx heap-analyzer find-leaks --baseline production-baseline.heapsnapshot --target latest-build.heapsnapshotCheck for memory regressions
npx heap-analyzer compare production-baseline.heapsnapshot feature-branch.heapsnapshot
`Interpreting Analysis Results
$3
- LOW: Minor memory variations, typically within normal application behavior
- MEDIUM: Noticeable memory growth patterns that warrant investigation
- HIGH: Significant memory leaks detected with clear attribution
- CRITICAL: Large-scale memory growth requiring immediate attention
$3
Data URL/Base64 Accumulation: Canvas operations, image caching, file uploads
- Look for:
, FileReader, growing arrays of base64 strings
- Fix: Implement cleanup cycles, use object URLs, clear cachesEvent Listener Leaks: Missing cleanup in component lifecycle
- Look for:
addEventListener without removeEventListener
- Fix: Add cleanup in unmount/destroy hooksTimer Leaks: Uncleaned intervals and timeouts
- Look for:
, setTimeout without corresponding clear calls
- Fix: Store timer IDs and clear them on cleanupCollection Growth: Unbounded arrays, maps, or sets
- Look for: Global collections that only grow, never shrink
- Fix: Implement size limits, periodic cleanup, or LRU eviction
$3
Memory Growth: Absolute and percentage increase between snapshots
Object Count: New objects created, useful for detecting object accumulation
File Size Growth: Raw snapshot size difference, indicates data structure bloat
Heap Snapshot Creation
Create heap snapshots in Chrome DevTools:
1. Open DevTools (F12)
2. Go to Memory tab
3. Select "Heap snapshot"
4. Click "Take snapshot"
5. Save the
.heapsnapshot fileComplete Command Reference
$3
| Command | Description | Memlab Equivalent |
|---------|-------------|-------------------|
|
find-leaks | Memory leak detection | memlab find-leaks |
| trace | Retainer trace analysis | memlab trace |
| heap | Interactive heap exploration | memlab heap |
| view-heap | Heap visualization | memlab view-heap |
| analyze-plugin | Run analysis plugins | memlab analyze |
| compare | Growth analysis | (Our enhancement) |
| analyze | Single snapshot analysis | (Our enhancement) |
| list | List available snapshots | (Our enhancement) |$3
| Command | Description | Use Case |
|---------|-------------|----------|
|
node-snapshot --endpoint | Take snapshot via HTTP | Production monitoring |
| node-snapshot --pid | Take snapshot via process signal | Development debugging |
| node-monitor --pid | Auto-monitor memory usage | Continuous monitoring |
| node-load-test | Load test with snapshots | Performance testing |$3
`sh
Advanced leak detection with filtering
npx memlab find-leaks --baseline snapshots/baseline.heapsnapshot --target snapshots/target.heapsnapshot --trace-object-size-above 1000000Compare leak sets between different implementations
npx memlab diff-leaks --control-snapshot snapshots/old-version.heapsnapshot --treatment-snapshot snapshots/new-version.heapsnapshotMachine learning based leak clustering
npx memlab find-leaks --baseline snapshots/baseline.heapsnapshot --target snapshots/target.heapsnapshot --ml-clusteringTrace specific patterns
npx memlab find-leaks --baseline snapshots/baseline.heapsnapshot --target snapshots/target.heapsnapshot --trace-contains "EventListener"Interactive heap exploration with specific node focus
npx memlab view-heap --snapshot snapshots/large-heap.heapsnapshot --node-id 12345
`$3
All commands support smart path resolution:
sh
These are equivalent:
npx heap-analyzer find-leaks --baseline baseline.heapsnapshot --target target.heapsnapshot
npx heap-analyzer find-leaks --baseline ./snapshots/baseline.heapsnapshot --target ./snapshots/target.heapsnapshot
npx heap-analyzer find-leaks --baseline /absolute/path/to/baseline.heapsnapshot --target /absolute/path/to/target.heapsnapshotDirectory mode automatically finds files:
npx heap-analyzer find-leaks --snapshot-dir ./snapshots/
`$3
Debugging Memory Leaks:
1.
2.
3. (for interactive exploration)Performance Analysis:
1.
heap-analyzer compare baseline.heapsnapshot optimized.heapsnapshot
2.
3. Development Workflow:
1.
(see available snapshots)
2. heap-analyzer find-leaks --snapshot-dir ./snapshots/ (auto-detect and analyze)
3. heap-analyzer view-heap latest.heapsnapshot` (visual inspection)MIT