Table of Contents

• Debugger

  • Watchers

  • Command reference

    • Stepping
    • Breakpoints
    • Information
    • Execution control
    • Various

  • Advanced Usage

    • V8 Inspector Integration for Node.js

Debugger#

Node.js includes an out-of-process debugging utility accessible via aV8 Inspector and built-in debugging client. To use it, start Node.jswith theinspect argument followed by the path to the script to debug; aprompt will be displayed indicating successful launch of the debugger:

$ node inspect myscript.js< Debugger listening on ws://127.0.0.1:9229/80e7a814-7cd3-49fb-921a-2e02228cd5ba< For help, see: https://nodejs.org/en/docs/inspector< Debugger attached.Break on start in myscript.js:1> 1 (function (exports, require, module, __filename, __dirname) { global.x = 5;  2 setTimeout(() => {  3   console.log('world');debug>

Node.js's debugger client is not a full-featured debugger, but simple step andinspection are possible.

Inserting the statementdebugger; into the source code of a script willenable a breakpoint at that position in the code:

// myscript.jsglobal.x = 5;setTimeout(() => {  debugger;  console.log('world');}, 1000);console.log('hello');

Once the debugger is run, a breakpoint will occur at line 3:

$ node inspect myscript.js< Debugger listening on ws://127.0.0.1:9229/80e7a814-7cd3-49fb-921a-2e02228cd5ba< For help, see: https://nodejs.org/en/docs/inspector< Debugger attached.Break on start in myscript.js:1> 1 (function (exports, require, module, __filename, __dirname) { global.x = 5;  2 setTimeout(() => {  3   debugger;debug> cont< hellobreak in myscript.js:3  1 (function (exports, require, module, __filename, __dirname) { global.x = 5;  2 setTimeout(() => {> 3   debugger;  4   console.log('world');  5 }, 1000);debug> nextbreak in myscript.js:4  2 setTimeout(() => {  3   debugger;> 4   console.log('world');  5 }, 1000);  6 console.log('hello');debug> replPress Ctrl + C to leave debug repl> x5> 2 + 24debug> next< worldbreak in myscript.js:5  3   debugger;  4   console.log('world');> 5 }, 1000);  6 console.log('hello');  7debug> .exit

Therepl command allows code to be evaluated remotely. Thenext commandsteps to the next line. Typehelp to see what other commands are available.

Pressingenter without typing a command will repeat the previous debuggercommand.

Watchers#

It is possible to watch expression and variable values while debugging. Onevery breakpoint, each expression from the watchers list will be evaluatedin the current context and displayed immediately before the breakpoint'ssource code listing.

To begin watching an expression, typewatch('my_expression'). The commandwatchers will print the active watchers. To remove a watcher, typeunwatch('my_expression').

Command reference#

Stepping#

• cont,c - Continue execution
• next,n - Step next
• step,s - Step in
• out,o - Step out
• pause - Pause running code (like pause button in Developer Tools)

Breakpoints#

• setBreakpoint(),sb() - Set breakpoint on current line
• setBreakpoint(line),sb(line) - Set breakpoint on specific line
• setBreakpoint('fn()'),sb(...) - Set breakpoint on a first statement infunctions body
• setBreakpoint('script.js', 1),sb(...) - Set breakpoint on first line ofscript.js
• clearBreakpoint('script.js', 1),cb(...) - Clear breakpoint inscript.json line 1

It is also possible to set a breakpoint in a file (module) thatis not loaded yet:

$ node inspect main.js< Debugger listening on ws://127.0.0.1:9229/4e3db158-9791-4274-8909-914f7facf3bd< For help, see: https://nodejs.org/en/docs/inspector< Debugger attached.Break on start in main.js:1> 1 (function (exports, require, module, __filename, __dirname) { const mod = require('./mod.js');  2 mod.hello();  3 mod.hello();debug> setBreakpoint('mod.js', 22)Warning: script 'mod.js' was not loaded yet.debug> cbreak in mod.js:22 20 // USE OR OTHER DEALINGS IN THE SOFTWARE. 21>22 exports.hello = function() { 23   return 'hello from module'; 24 };debug>

Information#

• backtrace,bt - Print backtrace of current execution frame
• list(5) - List scripts source code with 5 line context (5 lines before andafter)
• watch(expr) - Add expression to watch list
• unwatch(expr) - Remove expression from watch list
• watchers - List all watchers and their values (automatically listed on eachbreakpoint)
• repl - Open debugger's repl for evaluation in debugging script's context
• exec expr - Execute an expression in debugging script's context

Execution control#

• run - Run script (automatically runs on debugger's start)
• restart - Restart script
• kill - Kill script

Various#

• scripts - List all loaded scripts
• version - Display V8's version

Advanced Usage#

V8 Inspector Integration for Node.js#

V8 Inspector integration allows attaching Chrome DevTools to Node.jsinstances for debugging and profiling. It uses theChrome DevTools Protocol.

V8 Inspector can be enabled by passing the--inspect flag when starting aNode.js application. It is also possible to supply a custom port with that flag,e.g.--inspect=9222 will accept DevTools connections on port 9222.

To break on the first line of the application code, pass the--inspect-brkflag instead of--inspect.

$ node --inspect index.jsDebugger listening on 127.0.0.1:9229.To start debugging, open the following URL in Chrome:    chrome-devtools://devtools/bundled/js_app.html?experiments=true&v8only=true&ws=127.0.0.1:9229/dc9010dd-f8b8-4ac5-a510-c1a114ec7d29

(In the example above, the UUID dc9010dd-f8b8-4ac5-a510-c1a114ec7d29at the end of the URL is generated on the fly, it varies in differentdebugging sessions.)

If the Chrome browser is older than 66.0.3345.0,useinspector.html instead ofjs_app.html in the above URL.