# thedebugger

<!-- [START badges] -->
[![Build Status](https://api.travis-ci.org/sfninja/thedebugger.svg?branch=master)](https://travis-ci.org/sfninja/thedebugger)
[![NPM thedebugger package](https://img.shields.io/npm/v/thedebugger.svg)](https://npmjs.org/package/thedebugger)
<!-- [END badges] -->

<img src="https://raw.githubusercontent.com/ChromeDevTools/devtools-logo/master/192.png" height="200" align="right">

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

## Installation

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


```bash
# global install with npm:
npm install -g thedebugger


# alternatively, with yarn:
yarn global add thedebugger
```

Global installation may fail with different permission errors, you can find help in this [thread](https://github.com/sfninja/thedebugger/issues/20).

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 thedebugger available from an npm script (eg. `npm run debug` runs `thedebugger index.js`), you can install it as a development dependency:

```bash
# local install with npm:
npm install --save-dev thedebugger


# alternatively, with yarn:
yarn add thedebugger --dev
```

You can then [set up an npm script](https://docs.npmjs.com/misc/scripts#examples). In this case, thedebugger 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 `thedebugger` instead of the `node` command

```bash
thedebugger server.js

# Alternatively, you can prepend `thedebugger`
thedebugger node server.js
```

- Prepend `thedebugger` in front of any other binary

```bash
# If you use some other binary, just prepend `thedebugger`
## npm run unit
thedebugger npm run unit

# Debug any globally installed package
## mocha
thedebugger mocha

# To use a local binary, use `npx` and prepend before it
thedebugger npx mocha
```

- Launch `thedebugger` as a standalone application 
   - Then, debug any npm script from your `package.json`, e.g. unit tests

```bash
# cd to your project folder (with a package.json)
thedebugger .
# In Sources panel > "NPM Scripts" sidebar, click the selected "Run" button 
```

- Run any node command from within thedebugger's integrated terminal and thedebugger will connect automatically
- Run any open script source by using 'Run this script' context menu item, thedebugger will connect automatically as well

## What can I do?

`thedebugger` has some powerful features exclusively for Node.js:
1. Child processes are detected and attached to.
1. You can place breakpoints before the modules are required.
1. You can edit your files within the UI. On Ctrl-S/Cmd-S, DevTools will [save the changes to disk](https://developers.google.com/web/tools/chrome-devtools/workspaces/).
1. By default, thedebugger [blackboxes](https://developers.google.com/web/tools/chrome-devtools/javascript/reference#blackbox) 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](https://medium.com/@paul_irish/debugging-node-js-nightlies-with-chrome-devtools-7c4a1b95ae27):
- breakpoint debugging, async stacks (AKA long stack traces), [async stepping](https://developers.google.com/web/updates/2018/01/devtools#async), etc...
- console (top-level await, object inspection, advanced filtering)
- [eager evaluation](https://developers.google.com/web/updates/2018/05/devtools#eagerevaluation) in console (requires Node >= 10)
- JS sampling profiler
- memory profiler

### Screenshot
![image](https://user-images.githubusercontent.com/39191/43023843-14a085a6-8c21-11e8-85b7-b9fd3405938a.png)


## Contributing

Check out [contributing guide](https://github.com/sfninja/thedebugger/blob/master/CONTRIBUTING.md) to get an overview of thedebugger development.