RFC: `npm debug` command

[about-code]

This RFC proposes an npm debug command to simplify debugging npm packages.

Prior discussions at https://github.com/npm/feedback/discussions/585

[ljharb]

I believe that setting NODE_OPTIONS='--inspect-brk' would make debugging Just Work with any node-based command you wanted to run. Does that work for you?

[about-code]

I believe that setting NODE_OPTIONS='--inspect-brk' would make debugging Just Work with any node-based command you wanted to run. Does that work for you?

From a purely technical point of view, yes, it works (similar to how node --inspect-brk <some-path> would do it, as well). Just note: this RFC is less about making debugging just work but should be perceived as being about developer experience and how to make debugging particular packages more approachable using the npm command and its implict knowledge of packages. Edit: Your proposal might be applicable internally in an implementation of npm debug

From a usability perspective I consider NODE_OPTIONS or a run-script uncomfortable for users for two reasons:

• they'd need to set up such run-scripts for every new project they start, even though debugging is a recurrent development task quite similar to init, start, test or publish a package.
• in an npm workspace with multiple CLI packages they'd need a separate run-script for every such package in the workspace

Possible Use Cases

1: Authoring an npm package with a CLI

Instead of crafting a command-line or run-script with

NODE_OPTIONS='--inspect-brk' node ./bin/foo.js

this RFC proposes to provide something by npm out of the box which allows typing

npm debug

2: Workspace with one or more project packages having a CLI

Instead of crafting a command-line or run-script

NODE_OPTIONS='--inspect-brk' node ./packages/foo-package/bin/foo.js

this RFC proposes to provide something by npm out of the box which allows typing

npm debug foo

3: Debugging tools and 3rd-party packages in a node_modules folder

Consider a project with a package like eslint installed within its node_modules folder. So the package has a CLI. Except, the tool not being eslint but a less prominent one foo with less maintainers and less quality.

• As a user of such package you've tried everything to make it work, but it doesn't. You want to confirm by debugging the tool that the bug is not in the way you use it but in the tool itself.
• As a maintainer of such package you request a sample repository for debugging your tool's usage within that sample repository.

Instead of crafting a command-line or run-script

NODE_OPTIONS='--inspect-brk' node ./node_modules/.bin/foo.js

this RFC proposes to provide something by npm out of the box which allows typing

npm debug foo