User Story: 'npm debug' command

[about-code]

User Story:

As author of an executable npm package (one having a bin key in package.json) I sometimes whish to have a npm debug command as a shortcut for node --inspect-brk <bin-script.js> [args] or custom run scripts in order to debug <bin-script> with an "ad-hoc" argument vector.

Rationale

• npm run scripts always require typing a script name before executing. When passing arguments via CLI they require and additional -- arg separator which gets annoying at some point, especially since debugging is a regular dev task repeated many times.
• IDEs and Editors often allow for saving run configurations or launch configurations in order to debug a particular command line. They require a separate run configuration for each argument vector making it hard to debug argument vectors in a particular ad-hoc manner.

Proposal

In general npm debug [workspace] [args] should run a JavaScript similar to a command line node --inspect-brk <script.js> [args]. npm debug should not have own arguments apart from an optional workspace selector in order to allow passing any [args] directly to process.argv of the script that is to be debugged (it should not require additional -- like npm run does. Setups which require custom debug options (e.g. a custom node debug port) should be able to execute a customized "debug" npm run script.

The command should apply the following rules until the terminal symbol ! is found:

1. It should select a workspace
   1. it should check package.json for the existence of workspaces and if present
      1. it should try selecting a workspace based on the first argument npm debug <workspace> [args] and if workspace is present
         1. it should select the given workspace
         2. it should continue at 2
      2. it should check package.json (root workspace) for the existence of a "debug" script and if present
         1. it should select the root workspace
         2. it should continue at 2
      3. it should terminate with exit code 1 and npm ERR!
   2. it should select the current working directory with its package.json as the workspace
2. it should execute within the selcted workspace
3. it should look into package.json for some "script": { "debug": "..." }, first (similar to npm test) and if present
   1. it should execute the script passing any CLI arguments to the script similar to npm run debug -- [args]
   2. it should terminate with the script and exit code of the script!
4. it should look for a "bin" entry in package.json and if present
   1. it should execute the given <bin-script.js> using node --inspect-brk <bin-script.js> [args]
   2. it should terminate with the script and exit code of the script!
5. (to be discussed) it should look for a "main" entry in package.json and if present
   1. it should execute the given <main-script.js> using node --inspect-brk <main-script.js> [args]
   2. it should terminate with the script and exit code of the script!
6. it should terminate with an exit code 1 and: npm ERR (after having tried and not succeeded with any previous attempt)!

Summary

In general there is good tool support for debugging. Current options add some inconveniences when it comes to debugging particular argument vectors in an ad-hoc manner. A npm debug command could improve developer experience. Since debugging is a frequent development task it would be a reasonable addition to other npm CLI lifecycle commands like npm test or npm publish.

Questions to be discussed

1. Has this already been discussed somewhere (I could not find in the issues)?
2. Everything considered?
3. Support npx debug [args] Runs third-party debug package.
   1. as well
   2. or instead
4. Is this detailed enough and suited as an RFC in https://github.com/npm/rfcs

---

Use upvotes / downvotes to show support or objection, particularly if not wanting to explain it.

[ljharb]

npx debug already works to invoke the debug package.

You can define a debug script and npm run debug -- [args] already, and pass inspect-brk in the script - or you can set NODE_OPTIONS='--inspect-brk'`.

‘Either way, this seems like something better filed at https://github.com/npm/rfcs ?

[about-code]

@ljharb Thank you very much for your response.

npx debug already works to invoke the debug package.

Of course. Rules out point 3. Didn't thought of the debug package. Regarding your npm run debug proposal: have addressed this in the original post. run-scripts help a lot and are a blessing, indeed. From a developer workflow the inconvenience they leave is

• having to add them to every project again although debugging is a routine task like testing
• they require eight additional characters for run and argument separator --

I admit, the latter might sound like I am ridiculously lazy. It's the kind of thing which slowly but steadily adds to a whish for more convenience. Not sure if others feel the same.

npm run debug -- --arg1 --arg2
npm debug --arg1 --arg2

[ljharb]

I agree that that’s what it boils down to - the convenience of avoiding those extra characters. I’d suggest filing an RFC so it can be discussed :-)

[about-code]

Eventually, RFC filed at npm/rfcs#618