Debugger setup tuning for using VS Code with the mern.io starter kit

[egamma]

// CC @chrisdias

http://mern.io/ defines a starter kit for MERN. I was looking with @weinand into the best VS Code debugger setup.

The idea is to use an NPM launch configuration so that the vscode independent launching details can be defined inside the package.son and do not have to be defined inside the vscode specific launch configuration.

I've added the following script to the starter kit's package.json in the scripts section:

"start:debug": "cross-env BABEL_DISABLE_CACHE=1 NODE_ENV=development nodemon --nolazy --inspect=5858 index.js",

With the following launch configuration we could launch and debug the target from VS Code.

The script sets restart to true since the starterkit is using nodemon and we want to reattach when nodemon restarts the target program.

        {
            "name": "Launch via NPM",
            "type": "node",
            "request": "launch",
            "protocol": "inspector",
            "cwd": "${workspaceRoot}",
            "runtimeExecutable": "npm",
            "windows": {
                "runtimeExecutable": "npm.cmd"
            },
            "runtimeArgs": [
                "run-script",
                "start:debug"
            ],
            "timeout": 20000,
            "restart": true,
            "port": 5858
        }

We've ran into the following glitches:

• using the inspector protocol worked but we did not see all the console output (e.g. the webpack built time) in the DebugConsole.
• when using the legacy protocol and the --debug option you get a timeout error.
• with the working setup above you need to use the task manager to kill the target program. We tried to configure the launch configuration to use the internal terminal so that we can kill the target from the terminal. When using the internal terminal then the launching failed.

[weinand]

Issue 3 from above is the result of a changed API. See #22409 for details. It is fixed in the Insiders by now.

[chrisdias]

Perhaps we can make a variant of the mern-starter that includes the launch.json and updated package.json, then make a PR on the mern-cli. See "make your mern" at http://mern.io/ .

[chrisdias]

added

"console": "integratedTerminal"

And was able to launch the app under the debugger. However, I could only ever get it to hit a breakpoint one time.

[michelkaporin]

FYI When using legacy protocol with --debug-brk instead of --debug option, debugger could successfully attach and run MERN but some of the breakpoints could not be hit (e.g. index.js was hit, post.controller.js not). Debugger was also stopping its execution (Continue action became enabled) with no UI indication where it has stopped.

[michelkaporin]

Closing the issue as:

• webpack built time is shown in the console output (Windows/Mac verified).
• using node legacy protocol is tricky because babel-register is used, which compiles files on the fly when require() is called. This complicates much the legacy protocol to get access to the dynamically compiled files.
• launching through integrated terminal works fine, breakpoints can be hit many times (Windows/Mac verified).

[chrisdias]

@michelkaporin thanks for the update!

I'm reopening this because I don't know what to do as a user still :) Imagine I'm new to VS Code and I'm learning MERN. I read our docs and press F5 and nothing seems to work. What do I do?

Our model is to configure the launch.json in such a way that F5 just works. The suggestion above to launch through the integrated terminal sounds like a workaround?

My question then is, what is the proper setup in VS Code to get debugging to just work here, and how can we make that easier?

[michelkaporin]

@chrisdias The proper setup is described in the initial post here by @egamma, which works good and verified with respect to raised bullet points for this issue.

Regards the process simplifying I would propose to create a mern-starter kit for VS Code developers. As you pointed out we can do it with the help of "make your mern" at http://mern.io, where we can add the debug configuration listed above that works fine and enables a debugging for a user.

Doing auto-detection of MERN stack on F5 seems also a nice idea, although I don't know how this works now and how we can integrate it, maybe @weinand can give a light on it.

[ramya-rao-a]

Once debugging is stopped, you see the below in the terminal:

[nodemon] app crashed - waiting for file changes before starting...

nodemon should exit when user exits the debug session

[weinand]

@chrisdias some comments:

We have verified that the proposed launch config (see below) works as expected: pressing F5 runs MERN's own "npm run start" but with debugging enabled. It takes some time (30 secs) until everything has been build and webpacked but in the end the user sees a "MERN is running on port: 8000! Build something amazing!"

The launch config has to use the integrated terminal because "npm run start" uses "nodemon" which is an interactive tool that reads from stdin (nodemon outputs: "to restart at any time, enter rs"). Reading from stdin is not supported in the debug console (REPL). So using the integrated terminal is not a workaround but recommended practice for interactive programs (see VS Code doc).

This is the definitive launch config (which relies on a new start:debug script in the package.json):

{
        "name": "Launch via NPM script",
        "type": "node",
        "request": "launch",
        "protocol": "inspector",
        "cwd": "${workspaceRoot}",
        "runtimeExecutable": "npm",
        "windows": {
            "runtimeExecutable": "npm.cmd"
        },
        "runtimeArgs": [
            "run-script",
            "start:debug"
        ],
        "timeout": 20000,
        "restart": true,
        "port": 5858,
        "console": "integratedTerminal",
        "internalConsoleOptions": "neverOpen"
    }

We could try to detect MERN in the node extension and generate the launch config from above automatically, but I don't think that this approach is sustainable because we would have to track all changes in the underlying frameworks and adapt our launch config generation code frequently. A better approach is to let MERN maintain the launch config on their side.

There are two remaining issues (which are independent from MERN and are covered by separate issues):

• a "restart" in a launch config of request type "launch" does not only "re-attach" to node but runs the program again (in this case the npm start script). This is "restart" for request type "launch" does a re-run instead of a re-attach #24278.
• terminating the debug session kills the node process, but not nodemon. Nodemon must be killed by using Control-C in the integrated terminal. This looks like a small annoyance but is exactly the same that a user would have to do if running the npm start script from the command line. See terminating a debug session does not kill the launcher program but just the node process #24279. This is the issue reported by @ramya-rao-a above.

[weinand]

I've added experimental support for MERN launching: if MERN starter kit is detected a corresponding launch config is generated (if none exist).

[weinand]

The automatically generated launch config assumes that "nodemon" is installed globally.
This assumption can be removed as soon as microsoft/vscode-node-debug2#98 has been addressed.

[chrmarti]

--inspect seems to be missing, the debugger fails to attach:

Adding "runtimeArgs": [ "--inspect=5858" ] to the generated launch config makes it work out-of-the-box (assuming MongoDB is running...).

[chrmarti]

Btw., I'm still asked for the environment before the generated launch is used, is that by design?

[weinand]

I've added the "runtimeArgs": [ "--inspect=5858" ].

[weinand]

A first cut of a "MERN Recipe" is available here: https://github.com/weinand/vscode-recipes/tree/master/MERN-Starter