ndb README

The project's README from github.com/GoogleChromeLabs/ndb. As one markdown file: README.md.

ndb

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

Installation

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).

# global install with npm:
npm install -g ndb


# alternatively, with yarn:
yarn global add ndb

Global installation may fail with different permission errors, you can find help in this thread.

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

Local install

If you want ndb available from an npm script (eg. npm run debug runs ndb index.js), you can install it as a development dependency:

# local install with npm:
npm install --save-dev ndb


# alternatively, with yarn:
yarn add ndb --dev

You can then set up an npm script. In this case, ndb will not be available in your system path.

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

Use Ctrl/Cmd + R to restart last run
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
Use --prof flag to profile your app, Ctrl/Cmd + R restarts profiling

ndb --prof npm run unit

What can I do?

ndb has some powerful features exclusively for Node.js:

Child processes are detected and attached to.
You can place breakpoints before the modules are required.
You can edit your files within the UI. On Ctrl-S/Cmd-S, DevTools will save the changes to disk.
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

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.

debugger

Searching Database…

10.9K ·GitHub

archived

What is this?

ndb is an improved debugging experience for Node.js built on Chrome DevTools: you debug your apps in the familiar DevTools UI, with extra features made specifically for Node.

So is this a terminal-only debugger, or does it have a graphical interface?

It's a graphical debugger, not a terminal one: ndb opens the Chrome DevTools UI as its own desktop app. You can launch it standalone, and it even includes an integrated terminal for running node commands that connect automatically.

How do I install it, and how big is the download?

Install it globally with npm (npm install -g @ndbjs/ndb). It requires Node >=8.0.0 and works best on Node >=10. Be ready for a big download: Puppeteer pulls in Chromium (~170MB on Mac, ~280MB on Linux and Windows).

Are there any known installation pitfalls?

Yes, a couple. Global installs can fail with permission errors, and on Windows the build may fail while compiling native dependencies — running npm install -g windows-build-tools usually fixes it.

Is ndb still maintained?

No. The GitHub repository has been archived, so it's read-only and no longer receives updates or bug fixes. You can still install and use it, but expect friction with the newest Node versions.

Why is it called ndb?

The name has history: in early 2011 @smtlaissezfaire released the first serious debugger for Node.js under the ndb package name. Google's team thanked him for donating the name, and the original project is preserved at github.com/smtlaissezfaire/ndb.

What are similar projects?

node-inspector, electron, claude-devtools, eruda, vConsole, LightTable, proxypin, chrome-devtools-mcp

Which topics is it in?

debugger, chromium, chrome, devtools, npm-package, debugging, deprecated, gui, free, npm, desktop-app, terminal

Creator: GoogleChromeLabs
Size: 0.7 MB
Stars: 10.9K
Updated: CommitSep 12
Age: 8y
Commits · 90 Days