laurigates/typescript-debugging

TypeScript Debugging

When to Use This Skill

| Scenario | Use this skill | Alternative | |----------|---------------|-------------| | Setting up Bun inspector for debugging | Yes | N/A | | Configuring VSCode launch.json for Bun | Yes | N/A | | Investigating memory leaks with heap snapshots | Yes | N/A | | CPU profiling TypeScript applications | Yes | N/A | | Debugging network requests with verbose fetch | Yes | N/A | | Setting up sourcemaps for debugging | Yes | bun-development for build-time sourcemap flags | | Monitoring errors in production | No - use typescript-sentry | N/A | | Running tests to find failures | No - use bun-development | bun-test for quick test runs |

Core Expertise

Modern debugging for TypeScript/JavaScript with Bun runtime:

• WebKit Inspector Protocol (debug.bun.sh)
• VSCode integration with Bun extension
• Memory profiling with V8 heap snapshots
• Automatic sourcemap generation for TypeScript
• Chrome DevTools for heap analysis

Inspector Flags

Basic Debugging

# Start with debugger enabled
bun --inspect script.ts

# Custom port
bun --inspect=4000 script.ts

# Custom host:port
bun --inspect=localhost:4000 script.ts

Break on Start

# Break at first line (for fast scripts)
bun --inspect-brk script.ts

# Wait for debugger before running
bun --inspect-wait script.ts

Debugging Tests

# Debug test file
bun --inspect test

# Break before tests run
bun --inspect-brk test auth.test.ts

Web Debugger (debug.bun.sh)

Bun's built-in web debugger is a modified WebKit Web Inspector:

# Start debugging - outputs debug URL
bun --inspect script.ts
# ------------------- Bun Inspector -------------------
# Listening: ws://localhost:6499/
# Open: debug.bun.sh/#localhost:6499
# -----------------------------------------------------

Features

| Feature | Description | |---------|-------------| | Source view | View original TypeScript/JSX with sourcemaps | | Breakpoints | Click line numbers to set/remove | | Console | Execute code in current context | | Call stack | Inspect execution frames | | Scope | View local/closure/global variables | | Watch | Add expressions to monitor |

Execution Controls

| Control | Action | |---------|--------| | Continue (F8) | Run until next breakpoint | | Step Over (F10) | Execute line, skip into functions | | Step Into (F11) | Enter function call | | Step Out (Shift+F11) | Complete function, return to caller |

VSCode Integration

Extension Setup

Install Bun for Visual Studio Code.

launch.json Configuration

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "bun",
      "request": "launch",
      "name": "Debug Script",
      "program": "${workspaceFolder}/src/index.ts",
      "cwd": "${workspaceFolder}",
      "stopOnEntry": false,
      "watchMode": false
    },
    {
      "type": "bun",
      "request": "launch",
      "name": "Debug Tests",
      "program": "${workspaceFolder}/tests/index.test.ts",
      "cwd": "${workspaceFolder}",
      "runtime": "bun",
      "runtimeArgs": ["test"]
    },
    {
      "type": "bun",
      "request": "launch",
      "name": "Debug with Watch",
      "program": "${workspaceFolder}/src/index.ts",
      "watchMode": true
    },
    {
      "type": "bun",
      "request": "attach",
      "name": "Attach to Bun",
      "url": "ws://localhost:6499/"
    }
  ]
}

Configuration Options

| Option | Type | Description | |--------|------|-------------| | program | string | Entry file path | | cwd | string | Working directory | | args | string[] | Arguments to script | | env | object | Environment variables | | stopOnEntry | boolean | Break at first line | | watchMode | boolean | Enable --watch/--hot | | noDebug | boolean | Run without debugger | | strictEnv | boolean | Only use specified env |

Memory Debugging

Heap Snapshots

Create snapshots for Chrome DevTools analysis:

import { writeHeapSnapshot } from "v8";

// Create snapshot at any point
writeHeapSnapshot("before.heapsnapshot");

// After suspect operation
doSomeWork();

writeHeapSnapshot("after.heapsnapshot");

Load .heapsnapshot files in Chrome DevTools Memory tab for comparison.

Heap Statistics (bun:jsc)

import { heapStats } from "bun:jsc";

const stats = heapStats();
console.log({
  heapSize: stats.heapSize,
  objectCount: stats.objectCount,
  objectTypeCounts: stats.objectTypeCounts
});
// objectTypeCounts: { Array: 1234, Object: 5678, Function: 890, ... }

Process Memory

// Resident Set Size (actual RAM used)
console.log(process.memoryUsage.rss());

// Full memory breakdown
console.log(process.memoryUsage());
// { rss, heapTotal, heapUsed, external, arrayBuffers }

Non-JS Memory (mimalloc)

# Show native memory stats
MIMALLOC_SHOW_STATS=1 bun script.ts

Performance Profiling

CPU Profiling

# Generate CPU profile
bun --cpu-prof script.ts

# Produces .cpuprofile file for Chrome DevTools

Network Request Debugging

# Log all fetch/http requests
BUN_CONFIG_VERBOSE_FETCH=1 bun script.ts

# Log as curl commands
BUN_CONFIG_VERBOSE_FETCH=curl bun script.ts

Sourcemaps

Bun automatically generates sourcemaps for transpiled files:

• TypeScript → JavaScript mapping preserved
• JSX transformations tracked
• Stack traces show original source locations
• Debugger shows TypeScript, not transpiled JS

Build with Sourcemaps

# External sourcemaps (recommended for debugging)
bun build ./src/index.ts --outdir=dist --sourcemap=external

# Inline sourcemaps
bun build ./src/index.ts --outdir=dist --sourcemap=inline

# No sourcemaps (production)
bun build ./src/index.ts --outdir=dist --sourcemap=none

Console Debugging

Beyond console.log

// Structured object/array display
console.table([{ id: 1, name: "a" }, { id: 2, name: "b" }]);

// Timing operations
console.time("fetch");
await fetch(url);
console.timeEnd("fetch"); // fetch: 234ms

// Group related logs
console.group("Request");
console.log("URL:", url);
console.log("Method:", method);
console.groupEnd();

// Conditional logging
console.assert(value > 0, "Value must be positive", value);

// Stack trace without error
console.trace("Reached here");

Programmatic Breakpoints

// Pause execution when debugger attached
debugger;

// Conditional breakpoint
if (suspiciousCondition) {
  debugger;
}

Common Leak Patterns

Closure Entrapment

// BAD: largeData retained in closure
const largeData = loadHugeArray();
setInterval(() => {
  console.log(largeData.length); // Keeps largeData alive forever
}, 1000);

// GOOD: Copy only needed data
const dataLength = largeData.length;
setInterval(() => {
  console.log(dataLength);
}, 1000);

Event Listener Cleanup

// BAD: Listener never removed
emitter.on("data", handler);

// GOOD: Use once for single events
emitter.once("data", handler);

// GOOD: Explicit cleanup
emitter.on("data", handler);
// Later...
emitter.removeListener("data", handler);

AbortSignal/AbortController

// For long-running operations
const controller = new AbortController();
const response = await fetch(url, { signal: controller.signal });

// Cleanup on timeout
setTimeout(() => controller.abort(), 30000);

Module-Level Variables

// BAD: Grows indefinitely
const cache: Map<string, Data> = new Map();

export function getData(key: string) {
  if (!cache.has(key)) {
    cache.set(key, expensiveCompute(key));
  }
  return cache.get(key);
}

// GOOD: Use LRU or TTL cache
import { LRUCache } from "lru-cache";
const cache = new LRUCache<string, Data>({ max: 1000 });

Debugging Workflow

Memory Leak Investigation

1. Baseline: Create heap snapshot at startup
2. Reproduce: Perform suspect operations
3. Compare: Create second snapshot, compare in DevTools
4. Identify: Look for growing object counts (Delta column)
5. Trace: Use retainers view to find what's holding references

Performance Investigation

1. Profile: Run with --cpu-prof
2. Load: Open .cpuprofile in Chrome DevTools
3. Analyze: Check flame graph for hot paths
4. Optimize: Focus on widest flames first

Agentic Optimizations

| Context | Command | |---------|---------| | Quick debug | bun --inspect-brk script.ts | | Debug tests | bun --inspect-brk test | | Memory check | bun -e "import{heapStats}from'bun:jsc';console.log(heapStats())" | | Network debug | BUN_CONFIG_VERBOSE_FETCH=curl bun script.ts | | CPU profile | bun --cpu-prof script.ts | | Native memory | MIMALLOC_SHOW_STATS=1 bun script.ts |

Quick Reference

Inspector Flags

| Flag | Description | |------|-------------| | --inspect | Enable debugger on available port | | --inspect=<port> | Enable debugger on specific port | | --inspect-brk | Break at first line | | --inspect-wait | Wait for debugger attachment | | --cpu-prof | Generate CPU profile |

Debug URLs

| URL | Purpose | |-----|---------| | debug.bun.sh | Bun's web debugger | | chrome://inspect | Chrome DevTools (for heap analysis) |

Environment Variables

| Variable | Description | |----------|-------------| | BUN_CONFIG_VERBOSE_FETCH | 1 or curl for request logging | | MIMALLOC_SHOW_STATS | 1 to show native memory stats |

Memory APIs

| API | Import | Purpose | |-----|--------|---------| | writeHeapSnapshot() | v8 | Create heap snapshot file | | heapStats() | bun:jsc | Get heap statistics | | memoryUsage() | process | Get process memory | | memoryUsage.rss() | process | Get resident set size |

Troubleshooting

Debugger Not Connecting

# Check if port is in use
lsof -i :6499

# Try explicit port
bun --inspect=9229 script.ts

Breakpoints Not Hit

• Ensure sourcemaps are enabled
• Use --inspect-brk for fast-exiting scripts
• Check file paths match in debugger

VSCode Issues (Windows)

Bun's Unix socket debugging may not work on Windows. Use WSL or the web debugger instead.