/ndb

ndb is an improved debugging experience for Node.js, enabled by Chrome DevTools

Primary LanguageJavaScriptApache License 2.0Apache-2.0

ndb

NPM ndb package

ndb is an improved debugging experience for Node.js, enabled by Chrome DevTools

Installation

npm install -g ndb

Compatibility: ndb requires Node >=8.0.0. It works best with Node >=10.

Installation: ndb depends on Puppeteer which downloads a recent version of Chromium (~170MB Mac, ~280MB Linux, ~280MB Win).

Windows users: Installation may fail on Windows during compilation the native dependencies. The following command may help: npm install --g --production windows-build-tools

Getting Started

You can start debugging your Node.js application using one of the following ways:

  • Use ndb instead of the node command
ndb server.js

# Alternatively, you can prepend `ndb`
ndb node server.js
  • Prepend ndb in front of any other binary
# If you use some other binary, just prepend `ndb`
## npm run unit
ndb npm run unit

# Debug any globally installed package
## mocha
ndb mocha

# To use a local binary, use `npx` and prepend before it
ndb npx mocha
  • Launch ndb as a standalone application
    • Then, debug any npm script from your package.json, e.g. unit tests
# cd to your project folder (with a package.json)
ndb .
# In Sources panel > "NPM Scripts" sidebar, click the selected "Run" button 
  • Run any node command from within ndb's integrated terminal and ndb will connect automatically
  • Run any open script source by using 'Run this script' context menu item, ndb will connect automatically as well

What can I do?

ndb has some powerful features exclusively for Node.js:

  1. Child processes are detected and attached to.
  2. You can place breakpoints before the modules are required.
  3. You can edit your files within the UI. On Ctrl-S/Cmd-S, DevTools will save the changes to disk.
  4. By default, ndb blackboxes all scripts outside current working directory to improve focus. This includes node internal libraries (like _stream_wrap.js, async_hooks.js, fs.js) This behaviour may be changed by "Blackbox anything outside working dir" setting.

In addition, you can use all the DevTools functionality that you've used in typical Node debugging:

  • breakpoint debugging, async stacks (AKA long stack traces), async stepping, etc...
  • console (top-level await, object inspection, advanced filtering)
  • eager evaluation in console (requires Node >= 10)
  • JS sampling profiler
  • memory profiler

Screenshot

image

Contributing

Check out contributing guide to get an overview of ndb development.

Thanks to the 'OG' ndb

In early 2011, @smtlaissezfaire released the first serious debugger for Node.js, under the ndb package name. It's still preserved at github.com/smtlaissezfaire/ndb. We thank Scott for generously donating the package name.