Every developer spends a significant amount of time debugging. Mastering the right tools can save you hours of frustration.

1. The Humble console.log

The simplest form of debugging is printing the state of your application at various points. While basic, it's often the quickest way to check a variable's value or confirm if a piece of code is being executed.

JavaScript


function calculateTotal(items) {
  console.log('Starting calculation for items:', items); // What's the input?
  let total = 0;
  for (const item of items) {
    console.log(`Processing item: ${item.name}, price: ${item.price}`); // Is the loop working?
    total += item.price;
  }
  console.log('Final total:', total); // What's the output?
  return total;
}

Pro Tip: Use console.table() for arrays of objects and console.dir() to inspect object properties in detail.

2. The Node.js Inspector (with Chrome DevTools)

For more complex issues, you need a real debugger. Node.js has a built-in inspector that allows you to connect a debugging client, like Chrome DevTools, to your running application. This gives you powerful tools:

  • Breakpoints: Pause code execution at specific lines.
  • Step-by-Step Execution: Step through your code line by line.
  • Variable Inspection: Examine the values of all variables in the current scope.
  • Call Stack: See the chain of function calls that led to the current point.

How to Use It:

  1. Start your Node.js application with the --inspect or --inspect-brk flag.
  • --inspect: Starts the debugger but runs your code immediately.
  • --inspect-brk: Starts the debugger and pauses execution on the very first line, waiting for you to connect.
  1. Bash

node --inspect-brk my-server.js
  1. After running the command, you'll see a message like: Debugger listening on ws://127.0.0.1:9229/....
  2. Open Google Chrome and navigate to chrome://inspect. Your Node.js application should appear as a remote target. Click "inspect" to open a dedicated DevTools window.

Now you can click in the line number gutter within the "Sources" tab to set breakpoints, and then resume execution. Your code will run until it hits a breakpoint, allowing you to inspect everything.

3. Introduction to Profiling

Debugging is about finding out why your code is wrong. Profiling is about finding out why your code is slow. A profiler helps you identify performance bottlenecks by measuring how much time and memory your functions are using.

Node.js has a built-in profiler that can be activated with the --prof flag.

  1. Run your app with the profiler:
  2. Bash

node --prof my-app.js
  1. This will generate a "tick file" (e.g., isolate-....-v8.log) in your project directory. This file is not human-readable.
  2. Process the log file to generate a summary:
  3. Bash

node --prof-process isolate-....-v8.log > profiler-output.txt

The profiler-output.txt file will contain a summary of where your application spent the most time, helping you pinpoint slow functions that need optimization. For a more visual representation, tools like 0x can generate interactive flame graphs from the profiler data.