/
Profound.js Debugging with VS Code

Profound.js Debugging with VS Code

Before you start!

The first step is to install Profound.js onto your local machine by using npm install profoundjs. Click here for more detailed installation instructions.

Please note...

You can and are welcome to use any Node.js debugger you prefer with Profound.js; however, this walk-through illustrates using VS Code, as it is one of the more popular, free, and easy to use debuggers for Node.

Overview

VS Code: The What and Why

VS Code is a cross-platform, multi-language code editor. With inline IntelliSense, debugging support for multiple languages, inline git support and an extensible API for plugins, it's the editor that has no boundaries.

Its inline debugging support is perfect for Profound.js as it provides the functionality to start and stop Profound.js locally, set breakpoints, and see the values of variables at runtime, all through a friendly user interface.

To download and read more about VS Code, check out the following links:

There are several methods to debug your Profound.js program in VS Code:

  • Launch config - Serves as the conventional method for configuring debugging. It offers a comprehensive range of options to effectively run intricate applications.

  • Attach to a process - This allows you to connect the debugger to an already running process or application. This is useful when you want to debug a program that’s already running.

Written Tutorial

Using the Launch Config Method

  1. In VS Code, open your Profound.js installation directory in the Explorer.

    • Select File > Open Folder…

    • Select the directory where you installed Profound.js.

  2. Navigate to the Run and Debug tab.

  3. Click on create a launch.json file. This will open a new launch.json file with no configurations just yet in your directory.

    Your new launch.json file may look similar to this:

  4. The next step is to add your configurations to your launch.json file, which would look like this:

    .vscode/launch.json

    { "version": "0.2.0", "configurations": [ { "type": "node", "request": "launch", "name": "Launch PJS Debugger", "skipFiles": [ "<node_internals>/**" ], "program": "${workspaceFolder}\\start.js" } ] }

    To break this down:

    • "version": "0.2.0" - This is the Visual Studio Code debugger version.

    • "configurations" - This is your array of configurations.

    • "type": "node" - This tells us that we are debugging a Node.js application.

    • "request": "launch" - This signals that VS Code should start a new instance of the Node.js runtime for debugging.

    • "name": "Launch PJS Debugger" - This is just a name for the debug configuration. It’s what you’ll see in the dropdown menu in the Debug view.

    • "skipFiles" - This is optional. Here you specify which files the debugger should skip during debugging. The <node_internals>/** notation means that it’s going to skip all Node.js internal files.

    • "program" - This points VS Code to the entry point of your application, which is start.js. On macOS and Linux, use a forward slash: ${workspaceFolder}/start.js.

    Older versions of this configuration also included "args": ["--no-worker"], because Profound.js used to run the server in a worker process. Current releases no longer do, so the argument is not required. Passing it is harmless, but it has no effect.

    For more Launch configuration attributes, see https://code.visualstudio.com/docs/nodejs/nodejs-debugging#_launch-configuration-attributes.

  5. To test this, press the Play button.

  6. When your debugger starts running, you should see the following in your DEBUG CONSOLE:

  7. Once you have your Profound.js server running from VS Code, that means you are now able to debug.

Debugging a Profound.js Module

For this example, we will be debugging a module called connect4.js, which is included in Profound.js.

  1. In the VS Code explorer, open modules/pjssamples/connect4.js.

    Make sure your Profound.js Module has been set correctly in the config.js file of Profound.js. Here is an example:

  2. Once the file is open, place a breakpoint at the desired location where you want the program to pause. You can place a breakpoint by clicking just to the left of the line number where you intend to pause the program.

  3. After this, start debugging within VS Code and launch the application in your browser using the URL displayed in the debug console.

  4. When the program pauses, VS Code will become the active window, and the current debugged line of code will be highlighted in yellow.

  5. From this point forward, you can proceed to step through your module and debug the application.

Using the Attach to a Process Method

  1. Open your remote SSH terminal. You need to start the server in debug mode. The command to do that will look similar to this:

    $ node --inspect=host_name:port start $ node --inspect-brk=host_name:port start

    Use --inspect-brk instead of --inspect to add a breakpoint at the beginning of your script, so that the process waits for the debugger to attach before proceeding.

    Older versions of this procedure also passed a --no-worker switch, because Profound.js used to run the server in a worker process. Current releases no longer do, so the switch is not required.

  2. Then create a launch.json file – refer to the Launch config method for steps on how to do this.

    launch.json

    { "version": "0.2.0", "configurations": [ { "request": "attach", "name": "Debug PJS", // Address and port reported by --inspect on the remote system. "address": "10.0.0.1", "port": 9229, // remoteRoot is the Profound.js directory on the IFS; localRoot is // the matching copy of the source on your workstation. "remoteRoot": "/profoundjs", "localRoot": "C:\\Users\\yourname\\profoundjs", "type": "node", "skipFiles": [ "<node_internals>/**" ] } ] }

    • "request": "attach" - This tells VS Code you’re attaching to an already running process.

    • "name": "Debug PJS" - This is just a name for the debug configuration. It’s what you’ll see in the dropdown menu in the Debug view.

    • "address" & "port" - The address and port of the remote system (or your local machine) where the Node.js process you want to debug is running.

    • "remoteRoot" & "localRoot" - Used to help VS Code map your local source code to the remote source code.

    • "type": "node" - The debug type.

    • "skipFiles" - Optional, but handy when you don’t want to sift through certain files during debugging.

  3. To run the launch file, click on the play button.

  4. Once you have the Debugger attached message on your terminal, you can start debugging.

Video Tutorial