MemLens

MemLens is a lightweight, in-browser lens for spotting memory issues in React apps. It detects and visualizes:

Detached DOM elements still retained in memory
Unmounted React Fiber nodes that may indicate leaks
Event listener leaks (optional)
High-level DOM and heap usage stats (overlay header)

It can run as a one-line console snippet or as a small library you embed in dev builds.

Key features

Visual overlay: Highlights detached DOM elements; interactive panel shows counts and the React component stack for the selected element
React Fiber analysis: Scans the fiber tree to attribute elements to components
Event listener leak scan (opt-in): Groups leaked listeners by component and type
Non-intrusive: Uses a transparent overlay and avoids tracking its own UI

Browser support

Requires browsers with WeakRef/FinalizationRegistry support (e.g. modern Chrome, Edge, Safari, Firefox). In older browsers the tool may not function.

Quick start

Option A: Run from the browser console (CDN)

Paste this in your app page:

(() => {
  const s = document.createElement('script');
  s.src = 'https://unpkg.com/@memlab/lens/dist/memlens.run.bundle.min.js';
  s.crossOrigin = 'anonymous';
  document.head.appendChild(s);
})();

This injects and starts MemLens with the interactive overlay.

Option B: Run from the browser console (local build)

Copy the contents of packages/lens/dist/memlens.run.bundle.min.js (or packages/lens/dist/memlens.run.bundle.js) and paste into the browser's web console. The overlay starts immediately.

Option C: Programmatic scanner (UMD global)

Load the library bundle and use the MemLens global:

<script src="https://unpkg.com/@memlab/lens/dist/memlens.lib.bundle.min.js"></script>
<script>
  // Create a scanner (no overlay by default; use the run bundle for overlay)
  const scan = MemLens.createReactMemoryScan({
    isDevMode: true,
    scanIntervalMs: 1000,
    trackEventListenerLeaks: true, // optional
  });

  const unsubscribe = scan.subscribe((result) => {
    console.log('[MemLens]', {
      totalElements: result.totalElements,
      detached: result.totalDetachedElements,
      eventListenerLeaks: result.eventListenerLeaks,
    });
  });

  scan.start();

  // Later: scan.stop(); unsubscribe(); scan.dispose();
</script>

Note: The visualization overlay is provided by the self-starting "run" bundle (Option A/B/D). The library bundle focuses on scanning APIs.

Option D: Node/Puppeteer injection

@memlab/lens exposes a helper to retrieve the self-starting bundle as a string for script injection:

// Node
const {getBundleContent} = require('@memlab/lens');

// Puppeteer example
await page.addScriptTag({content: getBundleContent()});

Overlay controls and interactions

Toggle switch: Show/hide all overlay rectangles
Select/pin: Click a rectangle to pin/unpin the current selection
Hover: Reveal the selection chain of related detached elements
Component stack panel: Shows the React component stack of the selected element
Keyboard: Press D to temporarily ignore the currently selected element in the overlay
Widget: The control widget is draggable

Notes:

The overlay ignores its own UI elements and won’t count them as part of the page.
In dev mode, MemLens logs basic timing and scan stats to the console.

Configuration (CreateOptions)

type CreateOptions = {
  isDevMode?: boolean;                // enable console logs and dev-only behaviors
  subscribers?: Array<(r) => void>;   // observers of each scan result
  extensions?: Array<BasicExtension>; // e.g., DOMVisualizationExtension
  scanIntervalMs?: number;            // default ~1000ms
  trackEventListenerLeaks?: boolean;  // enable listener leak scanning
};

Core API (ReactMemoryScan):

start(), pause(), stop(), dispose()
subscribe(cb) => () => void
registerExtension(ext) => () => void

Build

# from packages/lens
npm run build
# or
webpack

Test

1) Install Playwright dependencies (first time):

npx playwright install
npx playwright install-deps

2) Run tests:

npm run test:e2e

3) Manual test: open src/tests/manual/todo-list/todo-with-run.bundle.html in a browser, or copy/paste dist/memlens.run.bundle.js to the DevTools console on any React page.

Learn more

Please check out this tutorial page on how to use MemLens (a debugging utility) to visualize memory leaks in the browser for easier memory debugging.

Package detail

@memlab/lens

readme