Heap Snapshot Inspection Skill

This skill provides expert guidance for investigating memory issues in Chromium-based environments (Chrome, Node.js, Electron) using heap snapshots and the @paulirish/agents CLI.

Core Tooling

We use the @paulirish/agents package which includes the heap-snapshot CLI.

Usage Pattern

Always prefer using the CLI via npx to ensure the latest version and dependencies:

npx -y @paulirish/agents heap-snapshot <command> [arguments]

Analysis Workflow

1. High-Level Summary

Start by getting an overview of the heap composition.

npx -y @paulirish/agents heap-snapshot summary path/to/snapshot.heapsnapshot

2. Identifying Leaks (Diffing)

Compare two snapshots (e.g., before and after an action) to see what objects are growing.

npx -y @paulirish/agents heap-snapshot diff baseline.heapsnapshot leak.heapsnapshot

3. Listing Specific Classes

If you suspect a specific class of objects (e.g., Detached DOM nodes or a specific constructor), list them.

npx -y @paulirish/agents heap-snapshot list leak.heapsnapshot --class Detached

4. Inspecting Objects

Get details for a specific object by its ID.

npx -y @paulirish/agents heap-snapshot inspect leak.heapsnapshot --id 12345

5. Retainer Analysis

Understand why an object is still in memory by looking at its retainers.

npx -y @paulirish/agents heap-snapshot retainers leak.heapsnapshot --id 12345

Best Practices

Capture Clean Snapshots: Before taking a snapshot, always perform a Garbage Collection (GC) if possible.
Isolate Reproductions: Use minimal test cases to make diffing more effective.
Focus on Retained Size: When listing objects, prioritize those with high retained size, as they are keeping other objects alive.
Look for "Detached": In web apps, "Detached" elements are a common source of leaks.

heap-snapshot-inspection