npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

react-memory-leak-detector

v1.4.2

Published

Dev-only React memory-leak detector. A Vite, Next.js or Babel plugin tags each component and hook with a named marker; a small runtime uses WeakRef + FinalizationRegistry to warn in the console, and emit events, when an unmounted component is still held i

Readme

react-memory-leak-detector

Spot React memory leaks while you develop — no heap snapshot needed to find out that something leaked.

When a component unmounts but something still holds onto it (a stray timer, listener, subscription, or closure), you get a console warning and a leak event you can forward to your own logger or Sentry. Only components still in memory after a garbage collection are reported. A component that was cleaned up correctly but not yet collected isn't (see When leaks are reported). Dev-only — it compiles out of production builds.

Install

npm install --save-dev react-memory-leak-detector

Setup

Two steps: add the build plugin, then import the runtime once in dev.

1. Add the plugin

Vite

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import heapMarkers from "react-memory-leak-detector/vite";

export default defineConfig({
  plugins: [
    heapMarkers(), // list it BEFORE react()
    react(),
  ],
});

Dev-only by default, so nothing ships to production. Works with any @vitejs/plugin-react version (or none). Keep heapMarkers() before react() — it warns you at startup if the order is wrong.

Next.js — wrap your config:

// next.config.ts (or next.config.mjs)
import withHeapMarkers from "react-memory-leak-detector/next";

const nextConfig = {
  /* your config */
};

export default withHeapMarkers(nextConfig);

No .babelrc needed, so Next keeps compiling with SWC (and next/font keeps working). Only the development browser bundle is instrumented: production builds and React Server Components are left untouched. Works with webpack and Turbopack. On Next 15.x, Turbopack only instruments files marked "use client". Turbopack on Next 15.2 and earlier isn't supported; use webpack (next dev without --turbopack).

Webpack / Babel — add the plugin to your Babel config, in development:

// .babelrc
{ "env": { "development": { "plugins": ["react-memory-leak-detector/babel-plugin"] } } }

In a Next.js app, use the wrapper above instead. A .babelrc replaces Next's compiler setup: without "presets": ["next/babel"] nothing compiles, and under webpack it turns off SWC, which breaks next/font. If you already use Babel with Next, add the preset and, for the App Router, ["react-memory-leak-detector/babel-plugin", { "skipServerComponents": true }].

2. Import the runtime

Load it once at the top of your app entry, in dev only:

// Vite: your entry file, e.g. src/main.tsx
if (import.meta.env.DEV) import("react-memory-leak-detector/runtime");

// Webpack: your entry file
if (process.env.NODE_ENV === "development") import("react-memory-leak-detector/runtime");

Next.js — the runtime must load in the browser. With Next 15.3+, put it in instrumentation-client.ts at the project root (next to app/ or pages/):

// instrumentation-client.ts
if (process.env.NODE_ENV === "development") import("react-memory-leak-detector/runtime");

On older versions, use the same line in pages/_app.tsx (Pages Router) or at the top of a "use client" component rendered by your root layout (App Router). Don't put it in app/layout.tsx itself: that's a Server Component, so the import never reaches the browser.

That's it. Type declarations are bundled, so TypeScript needs no extra setup.

The dynamic import() resolves after React's first render, so the app shell and whatever else is in the initial tree render before the tracker exists. That's fine: the runtime adopts any component it first sees at mount or unmount, so those components are tracked and their leaks reported like any other. To call the tracker API from your entry file (e.g. subscribe), wait for the import:

if (import.meta.env.DEV) {
  import("react-memory-leak-detector/runtime").then(() => {
    window.__heapTracker?.subscribe((event) => console.log("leak", event));
  });
}

Getting leaks

On page load the tracker installs. A component is reported once it has been unmounted for leakAgeMs (10 s by default) and a garbage collection has run since without freeing it:

[heap-leak] Suspected leak: UserCard — 1 instance(s) unmounted >10s ago still retained after garbage collection (live 1 total)

Any time, run window.__heapTracker.report() for a live table of tracked components:

  • live — instances still in memory (mounted, or unmounted and not yet collected).
  • stale — unmounted more than leakAgeMs ago and still in memory after a garbage collection: something is holding them. These are the ones reported.
  • awaitingGc — unmounted more than leakAgeMs ago, but no garbage collection has run since. They may just not have been collected yet, so they aren't reported (yet).

Prefer to handle leaks yourself — a debug overlay, your logger, Sentry? Subscribe:

const unsubscribe = window.__heapTracker?.subscribe((event) => {
  // { component, stale, live, leakAgeMs, at }
  Sentry.captureMessage(`heap-leak:${event.component}`, { extra: event });
});

Events fire only for stale components and are debounced per component. Like the warnings, they wait for a garbage collection, so components that are merely waiting to be collected don't reach your logger. The global is typed as optional (it only exists once the runtime import has resolved), so subscribe from the import's .then() or anywhere after it — not on the line right after a fire-and-forget import(). configure({ logging: false }) keeps the events but silences the console.

When leaks are reported

The browser frees memory only when its garbage collector runs, and an idle tab may not run it for a while. Until then, a component that cleaned up correctly is still in memory just like a leaked one. So the tracker doesn't judge a component by being in memory leakAgeMs after unmount. It waits for the first major (full) garbage collection after that point, and reports the component only if that collection didn't free it.

Minor collections, which browsers run far more often, don't count. In Chrome a cleared timer, a removed listener or a cancelled animation frame leaves a dead record in the browser's own heap that still points at the component, and minor collections treat it as live. A component that cleaned up correctly survives them all, until the next major collection frees it.

Warnings can therefore come later than leakAgeMs: after the browser's next major collection, within one sweep (sweepIntervalMs, 2 s). Components waiting for that collection show up as awaitingGc in report(). To get a verdict right away:

  1. In Chrome DevTools → Memory, click Collect garbage (the trash-can icon).
  2. Wait for the next sweep, or run window.__heapTracker.report().

One click judges every component that went stale before it, however many unmounted since the last collection.

From code (a debug overlay, an automated test), start Chrome with --js-flags="--expose-gc" and call window.__heapTracker.forceGc(), which collects and re-sweeps in one step.

Right after the page loads, the first verdicts also wait until the tracker has seen the browser collect garbage twice, usually within seconds.

A reported component is really being held, though not always by a bug. Something may keep it on purpose (a cache), or React may (see Compatibility). The heap snapshot below shows what.

Finding the cause

A reported component tells you what leaked; a heap snapshot tells you why. In Chrome DevTools → Memory, take a snapshot and filter for ComponentName$Heap:

Heap snapshot: LeakyTimeout$Heap instances retained, with the Retainers panel showing a DOMTimer holding them

Each row is a leaked instance. Select one and read the Retainers panel bottom-up to see what's holding it — here a DOMTimer, i.e. an uncleared setTimeout/setInterval. Clean it up on unmount and the instances disappear.

Configuration

All options are optional. The common ones, passed to the plugin:

heapMarkers({
  leakAgeMs: 10000,   // ms unmounted before a garbage collection can get it reported
  logging: true,      // console warnings on/off
  trackHooks: true,   // also track custom hooks, not just components
  excludeNames: [/^useTranslation$/], // component/hook names to skip entirely
});

With Next.js, pass the same options as the second argument: withHeapMarkers(nextConfig, { leakAgeMs: 5000 }).

Runtime options can also be changed live: window.__heapTracker.configure({ leakAgeMs: 5000 }).

Compatibility

| React feature | Status | | ---------------------------------------------------------- | ----------------------------------------------------------------------------------- | | React 17 / 18 / 19 function components & hooks | ✅ (React 17 root unmounts: see below) | | Concurrent rendering, Suspense, StrictMode (React 18 / 19) | ✅ | | SSR (effects no-op server-side) | ✅ | | React Compiler (1.0) | ✅ compiled as usual; see below | | <Activity mode="hidden"> (React 19.2+) | ⚠️ hidden components are reported as leaks; see below | | React Server Components | ✅ skipped by the Next.js wrapper; ⚠️ Babel plugin: use skipServerComponents: true | | Class components | ❌ not instrumented (PRs welcome) |

React Compiler. Instrumented components and hooks compile as usual. The compiler normally moves closures that use nothing from the component (an empty event handler, say) out to module scope. With the Vite plugin and the Next.js wrapper, the instrumentation runs first and keeps such closures in the component, so a missing cleanup is still reported. With the Babel plugin in the same Babel config as the compiler, the compiler runs first: those closures stay hoisted, no longer hold the component, and aren't reported.

React 17: unmounting a whole root. After ReactDOM.unmountComponentAtNode, React 17 can keep that root's last tree in memory until it next renders something (seen under StrictMode and after a Suspense retry). Its components are then reported even though they cleaned up, and a forced garbage collection doesn't clear them; any later React render does. Components removed from an app that stays mounted, the normal case, aren't affected, and neither is React 18+.

<Activity mode="hidden">. Hiding runs a component's effect cleanups but keeps it in memory, which looks exactly like a leak: once hidden for longer than leakAgeMs and through a garbage collection, it's reported, and that clears when it's shown again. List such components in excludeUnmountTracking to stop this. They stay searchable in heap snapshots, but are never reported, leaked or not.

All plugin options

heapMarkers({
  // ── build-time: what gets instrumented ──
  include: /\.[tj]sx?$/,              // files to process
  excludeNames: [/^useTranslation$/], // names that skip ALL instrumentation
  excludeUnmountTracking: [],         // names that keep the heap marker but skip
                                      //   the unmount effect — use for components
                                      //   under <Activity mode="hidden">, whose
                                      //   cleanup fires while still alive
  trackHooks: true,                   // false = components only
  skipServerComponents: false,        // true = skip files without "use client" (RSC)

  // ── runtime: how leaks are judged/reported (injected into the app) ──
  logging: true,                      // false = track silently, no console warnings
  leakAgeMs: 10000,                   // unmounted this long, then still in memory
                                      //   after a garbage collection = "stale"
  suspectThreshold: 1,                // min stale instances before warning/event
  sweepIntervalMs: 2000,              // how often the sweep runs
  warnCooldownMs: 30000,              // min gap between warnings for the same component
});

Runtime options can also be set before load (window.__heapTrackerOptions = { … }, e.g. at the top of main.tsx) or live (window.__heapTracker.configure({ … })).

window.__heapTracker API

| Call | Purpose | | ---- | ------- | | report() | console.table of every component with live instances; also returns the array. | | subscribe(fn) | Listen for stale-leak events; returns an unsubscribe function. | | configure(opts) | Update runtime options (e.g. { logging: false }). | | sweep() | Force an immediate sweep (otherwise every sweepIntervalMs). | | forceGc() | window.gc?.() + re-sweep, to get a verdict without waiting for the browser to collect. Needs Chrome started with --js-flags="--expose-gc". |

Leak event shape: { component, stale, live, leakAgeMs, at }. component matches the ComponentName$Heap marker in heap snapshots.

Engines (Vite plugin and Next.js wrapper)

The Vite plugin and the Next.js wrapper inject markers with Oxc by default and fall back to Babel automatically if oxc-parser can't load — you normally don't touch this. oxc-parser is an optional dependency that needs Node ^20.19 or >=22.12; the Babel fallback needs @babel/core installed (Next.js apps often don't have it). If neither works, you get one error explaining both. Force one with heapMarkers({ engine: "oxc" }) or "babel". The Babel engine parses with Babel and reads no project config, so non-default syntax (decorators, using, import attributes) needs its parser opted in, e.g. heapMarkers({ engine: "babel", parserPlugins: ["decorators-legacy"] }); the Oxc engine parses these natively. oxc-parser needs Node ^20.19 or >=22.12.

TypeScript option types are exported as HeapMarkersOptions (/babel-plugin), HeapMarkersViteOptions (/vite) and HeapMarkersNextOptions (/next).

How it works

  1. The plugin tags every component/hook with a uniquely-named marker — searchable as ComponentName$Heap in heap snapshots — and injects a synthetic useEffect that reports mount/unmount.
  2. The runtime holds each marker in a WeakRef + FinalizationRegistry and sweeps periodically.
  3. When components have been unmounted for leakAgeMs, the runtime releases a witness: an object it has held long enough to be in the old generation, which only a major garbage collection frees. Nothing else references it.
  4. Witness gone but marker still reachable → a major collection ran and something kept the component: warning + event. Both still there → no major collection yet, so no verdict (awaitingGc). See When leaks are reported.

License

MIT