Skip to content
If the desired entry point to debugging is unclear (e.g. within webpack configurations) this tool will help you by not just entering the debugger but also launching it from scratch.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.vscode Updates image locations. Mar 15, 2019
demo Implements options to specify port. Improves clipboard error handling. Mar 22, 2019
docs
entries
example
src
.gitignore
.prettierrc.json
CHANGELOG.md
LICENSE.md
README.md
package.json
tsconfig.json Implements options to specify port. Improves clipboard error handling. Mar 22, 2019
tslint.json
yarn.lock

README.md

Easy Attach

A helper tool that makes launching the debugger to step through node applications where the entry point is unclear (e.g. webpack configurations) extremely easy.

Like Debugger.Break() from C#. Everything the debugger; statement should be.

Why debugger; doesn't do it

debugger; does nothing if no debugger is attached.

This means you have to either launch the process in debug mode from the start (which is complicated if you don't control how the process is launched) or be quick to attach it before the line you want to break at is executed.

With this project you can just paste one line and it will launch a debugger of your choice (VSCode or Chrome) while suspending the running process, regardless of how it was started.

Requirements

Developed on Windows, tested on Windows and Linux.

Installation

easy-attach should best be installed globally:

yarn global add easy-attach

Or if you use npm:

npm install --global easy-attach

Demo

demo

Usage

Run easy-attach to see instructions:

cli

Then, in the script you want to debug, insert the code from the instructions:

function obscureFunction(args) {
	// this require call launches the debugger and waits
	require("C:\\Users\\henni\\AppData\\Local\\Yarn\\Data\\global\\node_modules\\easy-attach\\debugger")();
	anotherObscureFunction(args.data);
}

When the require("[...]\\debugger")() is called, a chrome window is launched with further instructions. By pasting the displayed link into chrome you can debug your node js application! This even works in node repl!

You can also pass a label to the call so that you don't mix up various breakpoints:

require("...\\easy-attach\\debugger")({ label: "Server" });

If you don't want the debugger to halt, you can pass a continue flag:

require("...\\easy-attach\\debugger")({ continue: true });

Flags

You can specify flags by passing an object:

require("...\\easy-attach\\debugger")({ ...flags });

These flags are supported:

export interface EasyAttachArgs {
	/**
	 * Sets a label for the debug target.
	 * Defaults to `undefined`..
	 */
	label?: string;
	/**
	 * If enabled, it does not break after attaching the debugger.
	 * Defaults to `false`.
	 */
	continue?: boolean;
	/**
	 * Specifies the port to use for the debug port.
	 * Use `preconfigured` when the debugger was already launched.
	 * Defaults to `random`;
	 */
	debugPort?: DebugPortConfig;
	/**
	 * Specifies the port to use for the debug proxy.
	 * This is usefull if you want to forward this port.
	 * Defaults to `random`;
	 */
	debugProxyPort?: PortConfig;
	/**
	 * Use this option when the debug proxy does not recognize connection attempts and does not close automatically. Defaults to `false`.
	 */
	eagerExitDebugProxy?: boolean;
	/**
	 * Print logs from background worker. Defaults to `false`.
	 */
	logBackgroundWorker?: boolean;
	/**
	 * Use this option to control whether the UI is shown.
	 * If only the VS Code Extension is used, disabling the UI speeds up the auto attach feature.
	 * Defaults to `true`.
	 */
	showUI?: boolean;
}

export type PortConfig = "random" | number | number[];
export type DebugPortConfig = PortConfig | "preconfigured";

Design Notes

Actually, going from debugger; to C#'s Debugger.Break() was unexpectedly easy (in terms of a node js developer).

This sequence diagram roughly describes what is needed for that little upgrade:

sequence-diagram

background-worker

The background-worker process is required as we don't want to return from the require call before a debugger successfully attached, otherwise we would miss the debugger; breakpoint. Thus, we cannot use the event loop of the debugee and have to spawn a new process and wait for it to exit synchronously.

debugger-proxy

The debugger-proxy is used to inform the background-worker that a debugger has attached. There seems to be no other way. Care has to be taken that is exits neither too early nor never.

Used Dependencies

Utility functions:

For typed communicating between background-worker and debugger-proxy:

For proxying node debug:

For the CLI:

To get the chrome debug url and launch chrome:

To notify vscode:

To find free ports:

Known Problems

  • Sometimes, when launchend, the background-worker appears for a short moment as black terminal window. I don't know why.
You can’t perform that action at this time.