facebook/memlab

⭐ 4,964  ·  JavaScript  ·  GitHub Repo

A framework for finding JavaScript memory leaks and analyzing heap snapshots

detector e2e facebook heap hermes javascript leak memory

1-Sentence Summary

Automated JavaScript memory leak detection framework that compares heap snapshots across browser interactions.

🔥 Key Capabilities & USP

• Automated Browser Leak Detection – Uses Puppeteer to script user interactions, then automatically compares heap snapshots to filter and aggregate memory leaks. Solves the pain point of manually profiling memory in complex single-page applications.
• Object-Oriented Heap Traversing API – Provides a graph representation of heap snapshots with a programmatic API for building custom leak detectors. This is the USP: it turns opaque heap dumps into queryable data structures.
• Multi-Runtime Support – Works across Chromium, Node.js, Electron.js, and Hermes runtimes. Eliminates the need for separate memory analysis tools for each JavaScript environment.
• MemLens Browser Debugging Tools – Visualizes memory leaks interactively within the browser, enabling developers to inspect retainers and object references without leaving the debugging context.
• Memory CLI Toolbox – Built-in commands for unbound object analysis, retainer tracing, and heap snapshot comparison. Provides actionable insights without requiring deep V8 internals knowledge.

Technical Architecture

Component	Technology
Runtime	Node.js 16+
Browser Automation	Puppeteer
Heap Formats	V8 & Hermes snapshot formats
Data Model	Graph-based heap representation
Package Distribution	npm (memlab)
License	MIT
CI/CD	GitHub Actions (active)

• Architecture Highlight: The framework converts raw heap snapshots into a traversable graph, then applies diffing algorithms to isolate leaked objects between states. This graph abstraction is the core enabler for both the CLI tools and the programmatic API.
• Extensibility: Custom leak detectors can be written as JavaScript classes that implement the LeakDetector interface, allowing teams to encode domain-specific memory patterns.

Quick Start Guide

# Install globally
npm install -g memlab

# Create a test scenario script (e.g., test-maps.js)
const scenario = {
  url: () => 'https://www.google.com/maps/@37.386427,-122.0428214,11z',
  action: async page => await page.click('text/Hotels'),
  back: async page => await page.click('[aria-label="Close"]'),
};
module.exports = scenario;

# Run automated leak detection
memlab run --scenario test-maps.js

# Analyze a specific heap snapshot
memlab view-heap --snapshot <PATH TO .heapsnapshot FILE>

# Find unbound objects (common leak pattern)
memlab analyze unbound-object

# Trace retainer path for a specific object
memlab trace --node-id <HEAP_OBJECT_ID>

Pros, Cons & Use Cases

Pros

• Open source (MIT) with active Facebook/Meta backing and community contributions
• Production-proven – used internally at Meta for performance testing
• Visual debugging with MemLens reduces cognitive load when analyzing complex retainer chains
• CI/CD friendly – can be integrated into automated test suites for regression detection

Cons

• Requires non-minified code for readable retainer traces (minified builds produce cryptic object names)
• Windows limitations – development requires Git Bash; native Windows support is incomplete
• Node.js 16+ only – legacy Node.js environments are unsupported
• Steep learning curve – writing custom detectors requires understanding heap graph traversal concepts

Who should NOT use this?

• Teams using only minified production builds without source maps – the retainer traces will be unreadable
• Developers on Windows without Git Bash – the tooling assumes a Unix-like shell environment
• Projects with Node.js < 16 – the framework will not install or run
• Simple static sites – memory leaks in basic content pages are rare and don't justify the setup overhead

Ideal Use Cases

• Single-page applications (React, Angular, Vue) with complex state management that often leak DOM nodes or event listeners
• Long-running Node.js services (API servers, data processors) that need self-memory assertions in unit tests
• Electron.js desktop apps where memory leaks degrade user experience over time
• Performance engineering teams building automated CI pipelines for memory regression detection
• Hermes runtime debugging for React Native applications

Community & Activity

With 4,964 stars and active maintenance (last updated May 2026), MemLab has strong momentum as a specialized tool in the JavaScript performance ecosystem. The project benefits from Facebook/Meta's engineering rigor and a growing community of performance engineers contributing custom detectors and CLI improvements. The combination of automated leak detection and manual analysis tools makes it a must-try for any team shipping JavaScript applications at scale.