Tips for debugging Node.js programs

Nov 28, 2019Node.js

1. Instead of console.log everywhere (sometimes together with some extra symbols in order to identify) trying to trace some values or errors, just set up debugger and go through the call stacks and inspect all the variables and expressions.

2. Use --inspect-brk option to start the program. It pauses the process at the beginning to let the debugging client to attach to it. This gives the debugging client enough of time to start and sync breakpoints with the Node.js process.

3. Both Chrome DevTools and Visual Studio Code debugger are excellent debugging client. Generally, DevTools is a little bit faster, more stable and it's able to resolve the correct path of the [[FunctionLocation]] property (jump to the function definition). VS Code debugger has more functionalities and easy to share the debugging configuration presets with others.

4. In order to attach debugger automatically when a new debugging process is started, install Node.js V8 --inspector Manager (NiM) extension for Chrome DevTools and set Debug: Toggle Auto Attach in VS Code.

4. Use debugger statement to set advanced breakpoints programmatically where it's hard to reach step-by-step.

for (let i = 0; i < 10000; i++) {
  if (i === 5000) {
try {
  // some super complicated tasks
} catch (error) {

5. Executable entrypoints of locally installed npm packages can be found in node_modules/.bin. Use node --inspect-brk node_modules/.bin/program-name to debug those cli programs.

6. Create alias in your shell profile as shortcuts to start debugging. Example:

alias nib="node --inspect-brk"
alias nin="node --inspect-brk node_modules/.bin"

7. For debugging program that starts with babel-node or ts-node, change the command to:

node --inspect-brk --require babel-register index.js
node --inspect-brk --require ts-node/register index.js

8. Node.js process has to be spawned with --inspect / --inspect-brk options in order to expose the debugging server. So when the child processes are spawned programmatically without such options, the debugger won't be able to break at the breakpoints in the source code of child processes. Testing libraries leverage child processes to execute test cases in parallel but it won't be helpful when debugging. So seek out for single process solution if the breakpoint is not breaking.

node --inspect-brk node_modules/.bin/jest --runInBand
node --inspect-brk node_modules/.bin/_mocha # watch the underscore

9. DevTools sometimes run into a blank page, that's where the source map exists but the source code does not (usually it's installed node modules where the source code is not published with the npm library). You can go to the DevTools settings > Preference > Sources, turn off he "Enable JavaScript source map" option.

10. Alway take a glance at the variable section during debugging to have a better understanding on which scope each variables belong to and how closure works. When the variables are object, try to trace the prototype chain and internal properties. When the execution point get into some Node.js internal modules, don't be panic and it's actually a good chance to take a look at how the Node.js internal modules code was written. Overall, using debugger is a efficient and institutive way to learn how JavaScript and Node.js works.

Powered by Gatsby. Theme inspired by end2end.

© 2014-2020. Made with by mdluo.