{"id":13765303,"url":"https://github.com/hediet/easy-attach","last_synced_at":"2025-08-21T15:32:24.346Z","repository":{"id":34050504,"uuid":"167552779","full_name":"hediet/easy-attach","owner":"hediet","description":"If the desired entry point to debugging is unclear (e.g. within webpack configurations) this tool will help you by not just waiting for a debugger to connect but also launching it from scratch. Don't use the excuse that attaching a debugger is cumbersome next time you use console.log for debugging!","archived":false,"fork":false,"pushed_at":"2023-04-30T07:54:45.000Z","size":1934,"stargazers_count":109,"open_issues_count":10,"forks_count":6,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-12-10T00:51:54.911Z","etag":null,"topics":["javascript","nodejs","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hediet.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-01-25T13:36:52.000Z","updated_at":"2024-01-04T16:30:09.000Z","dependencies_parsed_at":"2024-01-07T18:10:06.023Z","dependency_job_id":"18c57916-9b2c-48fe-8f1c-4119ca29e28f","html_url":"https://github.com/hediet/easy-attach","commit_stats":{"total_commits":62,"total_committers":3,"mean_commits":"20.666666666666668","dds":"0.12903225806451613","last_synced_commit":"63dd292b5597685774a1967408aec6897ecfe2ae"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hediet%2Feasy-attach","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hediet%2Feasy-attach/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hediet%2Feasy-attach/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hediet%2Feasy-attach/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hediet","download_url":"https://codeload.github.com/hediet/easy-attach/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230520393,"owners_count":18238948,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","nodejs","typescript"],"created_at":"2024-08-03T16:00:36.763Z","updated_at":"2024-12-20T01:15:39.317Z","avatar_url":"https://github.com/hediet.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","Helper Components"],"sub_categories":[],"readme":"# Easy Attach\n\n[![](https://img.shields.io/twitter/follow/hediet_dev.svg?style=social)](https://twitter.com/intent/follow?screen_name=hediet_dev)\n\nA helper tool that makes launching the debugger to step through node applications where the entry point is unclear (e.g. webpack configurations) extremely easy.\n\nLike `Debugger.Break()` from C#. Everything the `debugger;` statement should be.\n\n## Why `debugger;` doesn't do it\n\n`debugger;` does nothing if no debugger is attached.\n\nThis 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.\n\nWith 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.\n\n## Requirements\n\n-   You need Chrome or VS Code with [the RPC Server extension](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-rpc-server) to be installed.\n\nDeveloped on Windows, tested on Windows and Linux.\n\n## Installation\n\n`easy-attach` should best be installed globally:\n\n```\nyarn global add easy-attach\n```\n\nOr if you use npm:\n\n```\nnpm install --global easy-attach\n```\n\n## Demo\n\n![demo](docs/demo.gif)\n\n## Usage\n\nRun `easy-attach` to see instructions:\n\n![cli](docs/cli.png)\n\nThen, in the script you want to debug, insert the code from the instructions:\n\n```js\nfunction obscureFunction(args) {\n\t// this require call launches the debugger and waits\n\trequire(\"C:\\\\Users\\\\henni\\\\AppData\\\\Local\\\\Yarn\\\\Data\\\\global\\\\node_modules\\\\easy-attach\\\\debugger\")();\n\tanotherObscureFunction(args.data);\n}\n```\n\nWhen the `require(\"[...]\\\\debugger\")()` is called, a chrome window is launched with further instructions.\nBy pasting the displayed link into chrome you can debug your node js application!\nThis even works in node repl!\n\nYou can also pass a label to the call so that you don't mix up various breakpoints:\n\n```js\nrequire(\"...\\\\easy-attach\\\\debugger\")({ label: \"Server\" });\n```\n\nIf you don't want the debugger to halt, you can pass a `continue` flag:\n\n```js\nrequire(\"...\\\\easy-attach\\\\debugger\")({ continue: true });\n```\n\n## Connect with JetBrains (Webstorm / IntelliJ IDEA / etc...)\n\nRequired plugins: **JavaScript and TypeScript, JavaScript Debugger, Node.js**\n\nYou can connect to the node js application by following these steps:\n\n- Add a `require(\"[...]\\\\debugger\")({ debugProxyPort: PORT })` with some random port, e.g. 54834\n- Create an `Attach to Node.js/Chrome - Run/Debug Configuration`\n- Paste the port into the `Port` section\n- Make sure `Reconnect automatically` is checked, so whenever you restart the TypeScript Service, it can reconnect automatically\n- Wait for the statement to open a new chrome window\n- Click on the debug button to start debugging your application\n\n## Flags\n\nYou can specify flags by passing an object:\n\n```js\nrequire(\"...\\\\easy-attach\\\\debugger\")({ ...flags });\n```\n\nThese flags are supported:\n\n```ts\nexport interface EasyAttachArgs {\n\t/**\n\t * Sets a label for the debug target.\n\t * Defaults to `undefined`..\n\t */\n\tlabel?: string;\n\t/**\n\t * If enabled, it does not break after attaching the debugger.\n\t * Defaults to `false`.\n\t */\n\tcontinue?: boolean;\n\t/**\n\t * Specifies the port to use for the debug port.\n\t * Use `preconfigured` when the debugger was already launched.\n\t * Defaults to `random`;\n\t */\n\tdebugPort?: DebugPortConfig;\n\t/**\n\t * Specifies the port to use for the debug proxy.\n\t * This is usefull if you want to forward this port.\n\t * Defaults to `random`;\n\t */\n\tdebugProxyPort?: PortConfig;\n\t/**\n\t * Use this option when the debug proxy does not recognize connection attempts and does not close automatically. Defaults to `false`.\n\t */\n\teagerExitDebugProxy?: boolean;\n\t/**\n\t * Print logs from background worker. Defaults to `false`.\n\t */\n\tlogBackgroundWorker?: boolean;\n\t/**\n\t * Use this option to control whether the UI is shown.\n\t * If only the VS Code Extension is used, disabling the UI speeds up the auto attach feature.\n\t * Defaults to `true`.\n\t */\n\tshowUI?: boolean;\n}\n\nexport type PortConfig = \"random\" | number | number[];\nexport type DebugPortConfig = PortConfig | \"preconfigured\";\n```\n\n## Design Notes\n\nActually, going from `debugger;` to C#'s `Debugger.Break()` was unexpectedly easy (in terms of a node js developer).\n\nThis sequence diagram roughly describes what is needed for that little upgrade:\n\n![sequence-diagram](docs/exported/main/Main.png)\n\n### background-worker\n\nThe 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.\nThus, we cannot use the event loop of the debugee and have to spawn a new process and wait for it to exit synchronously.\n\n### debugger-proxy\n\nThe debugger-proxy is used to inform the background-worker that a debugger has attached.\nThere seems to be no other way.\nCare has to be taken that is exits neither too early nor never.\n\n## Used Dependencies\n\nUtility functions:\n\n-   [@hediet/std](https://www.npmjs.com/package/@hediet/std)\n\nFor typed communicating between background-worker and debugger-proxy:\n\n-   [@hediet/typed-json-rpc](https://www.npmjs.com/package/@hediet/typed-json-rpc)\n-   [@hediet/typed-json-rpc-streams](https://www.npmjs.com/package/@hediet/typed-json-rpc-streams)\n\nFor proxying node debug:\n\n-   [http-proxy](https://www.npmjs.com/package/http-proxy)\n-   [@types/http-proxy](https://www.npmjs.com/package/@types/http-proxy)\n-   [simples](https://www.npmjs.com/package/simples)\n\nFor the CLI:\n\n-   [chalk](https://www.npmjs.com/package/chalk)\n-   [clipboardy](https://www.npmjs.com/package/clipboardy)\n\nTo get the chrome debug url and launch chrome:\n\n-   [node-fetch](https://www.npmjs.com/package/node-fetch)\n-   [chrome-launcher](https://www.npmjs.com/package/chrome-launcher)\n\nTo notify vscode:\n\n-   [vscode-rpc](https://www.npmjs.com/package/vscode-rpc)\n\nTo find free ports:\n\n-   [get-port](https://www.npmjs.com/package/get-port)\n\n## Known Problems\n\n-   Sometimes, when launchend, the background-worker appears for a short moment as black terminal window. I don't know why.\n\n# Changelog\n\n-   2.0.0\n    -   Migrated from `_debugProcess` to `inspector.open`. This solves some race conditions.\n    -   Removed debug entry points.\n    -   Uses debug API to automatically step out or continue.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhediet%2Feasy-attach","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhediet%2Feasy-attach","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhediet%2Feasy-attach/lists"}