Gremoire

Debugging & Profiling Node.js with node --inspect ​

A Step-by-Step Guide for Frontend (Vite) and Backend Applications

Introduction — Why Use node --inspect? ​

As applications grow, so do their performance and memory challenges:

  • Frontend build tools (like Vite/Rollup/Esbuild) sometimes consume hundreds of MB of RAM or even crash with “JavaScript heap out of memory” during production builds.
  • Backend servers (like Express or NestJS) may face memory leaks, slow responses, or blocked event loops under real-world load.

node --inspect helps developers dig deeper into these issues.
It enables Node’s V8 Inspector Protocol, letting you attach familiar tools like Chrome DevTools or VS Code to your Node.js process.

With this, you can:

  • Take heap snapshots to analyze memory usage.
  • Run CPU profiles to find bottlenecks.
  • Debug async operations (I/O delays, DB queries, timers).
  • Plan resource allocation for CI/CD or containerized builds.

In short: node --inspect is not just for bug fixing — it’s for performance tuning and system stability.

Part 1: Using node --inspect with Frontend (Vite Builds) ​

Step 1 — Run Vite Build with Inspector ​

bash
node --inspect node_modules/vite/bin/vite.js build

This runs the Vite build but also opens a debugging port (ws://127.0.0.1:9229).

Step 2 — Open Chrome DevTools ​

  1. Open Chrome and go to:
    chrome://inspect
  2. Under Remote Target, you should see your Node.js process.
  3. Click Inspect to attach.

Step 3 — Analyze Memory ​

  • Go to the Memory tab.
  • Take a heap snapshot before and after the build.
  • Compare object types (strings, arrays, objects) to see what consumes the most memory.

Step 4 — Analyze CPU ​

  • Go to the Performance tab.
  • Click Record, run the build, then stop recording.
  • Identify which functions or plugins are consuming CPU time.

Common Use Cases for Frontend ​

  • Builds crash with OOM → find peak memory usage, adjust --max-old-space-size.
  • Builds are slow → check if a plugin or step (e.g., image processing) is the bottleneck.
  • Optimize CI/CD pipelines by knowing exactly how much RAM to allocate for builds.

Part 2: Using node --inspect with Backend Apps ​

Step 1 — Start Backend with Inspector ​

For JavaScript:

bash
node --inspect src/index.js

For TypeScript with tsx:

bash
node --inspect -r tsx src/index.ts

Step 2 — Attach Debugger ​

  • Again, go to chrome://inspect in Chrome.
  • Or configure VS Code with a launch.json:
json
{
  "type": "node",
  "request": "attach",
  "name": "Attach to Node",
  "port": 9229
}

Step 3 — Debug Memory Leaks ​

  • Open Memory tab.
  • Take multiple heap snapshots over time (before traffic, during load test, after requests).
  • If objects keep growing and never released → you’ve found a leak.

Step 4 — Debug Performance ​

  • Use the Performance tab to record CPU usage under load.
  • Check for blocking synchronous code (loops, heavy JSON parsing, etc.).
  • Use the Async tab (or clinic bubbleprof) to trace slow I/O (e.g., DB queries).

Common Use Cases for Backend ​

  • Detect memory leaks in APIs or microservices.
  • Find slow endpoints by profiling requests.
  • Ensure event loop isn’t blocked → avoid user-visible lags.
  • Validate scaling decisions (how much RAM/CPU per container/VM).

Tips & Best Practices ​

  • Default port: 9229. You can change it with:
    bash
    node --inspect=127.0.0.1:9230 app.js
  • Security: Never expose --inspect on a public server. Keep it bound to localhost.
  • Production caution: Only use in dev/staging unless you’re debugging a live issue.
  • CI/CD optimization: Profile locally, then adjust NODE_OPTIONS in pipelines:
    bash
    NODE_OPTIONS="--max-old-space-size=2048" vite build

Conclusion ​

  • Frontend developers use node --inspect to profile Vite builds → optimize memory usage and plugin performance.
  • Backend developers use it to debug long-running servers → catch memory leaks, CPU bottlenecks, async delays.
  • Tools like Chrome DevTools and VS Code make profiling familiar and accessible.

node --inspect is not just debugging — it’s engineering visibility into how Node.js behaves under the hood, helping teams build faster, leaner, and more reliable apps.