←  back to blog
Debugging Node.js applications in Theia

Debugging Node.js applications in Theia

Gitpod is based on the open-source Theia IDE Framework, which is highly inspired by VS Code, reuses its major components like the Monaco editor and intelligent-language support and is designed to run as a web application.

At TypeFox, we use Gitpod to develop Theia and all its satellite projects, like Theia extensions and language servers. We’ve discovered that for most use cases we don’t need to go to local development anymore. Development, testing, and the review processes are streamlined, leading from source code to a proper developer environment accessible from a browser with a single click.

Up to now, there was one important use case that forced us back to local tools, because it was not supported by Gitpod: Debugging.

Now, it is available, and I would like to give you a run through the basics of Node.js debugging in Gitpod based on an example.

Step 0: Open Node.js Shopping Cart example in Gitpod

Start a new workspace for the example GitHub repository: https://gitpod.io/#https://github.com/gitpod-io/nodejs-shopping-cart

Start a new Gitpod workspace for the shopping cart example via prefixing the URL with gitpod.io#

A new Gitpod workspace will be opened. Required dependencies are installed automatically since the repository is configured with a .gitpod.yml file. You can see it in the terminal, opened in the bottom area.

Step 1: Start debugging

Gitpod workspace

In order to start debugging, you should open the debug view first. You can do it via Viewmain menu or with Ctrl/Cmd+Shift+D.

The debug view allows you to configure launch configurations, start and manage debug sessions. Configurations are persisted debugging setups. They are stored in a VS Code compatible format in a launch.json JSON-file located in your workspace’s .theia folder. If your project already has the VS Code launch file, then Gitpod will recognize and use it instead.

Node.js Shopping Cart is an Express.js web-application. The repository already has a pre-configured Launch Program configuration, which starts the web server Node.js process in the debug mode. Let’s run it with F5 or by pressing the run button left to the configuration drop-down.

Gitpod Debug Tab

Step 2: Preview the application

A notification should pop-up suggesting you open an application side-by-side with an editor or externally, in a new browser tab. Let’s open it side-by-side to be able to debug and use our app at the same time.

Gitpod Preview Notification

Take your time and play with the app. You can review items to buy and in your cart, move them into or out of your cart.

Gitpod workspace shopping cart application preview

Step 3: Pause on a breakpoint

In this step we debug what happens when a user navigates to the homepage.

First, we need to add a breakpoint to the routing logic. It is defined in routes/index.js. You can open that file from the navigator or using the quick file palette (Ctrl/Cmd+P) .

Gitpod quick file pallete

Next, add a breakpoint in the editor margin against a line which you want to debug. A route callback handling / path looks promising.

Debugging: BreakpointsBreakpoints are displayed in the debug view and applied to currently running sessions.

Now, in the app, try navigating to the homepage. The debug session will pause on the breakpoint. You can traverse the current stack trace, inspect variables and control the execution flow with the debug actions toolbar:

Gitpod Debug Menu

Step 4: Inspect and modify data

There are several ways to see variables’ values:

  • you can traverse current scopes and variables in the debug view;

  • you can hover over expressions in the editor to evaluate them with a current session;

  • or you can use the debug console (REPL) to evaluate custom expressions.

You can always double-click on any variable to modify its value.

Debug: Inspect and Modify data

Next steps

Debugging is an important feature to provide the complete development experience. The Node.js debugging support is the first step for Gitpod in this direction. We are working to bring more debug features and add support for more runtimes. We would also love to hear what features and runtimes you want to see supported. Tell us.

Join developers, everywhere.

Development environments pre-configured with the tools and dependencies needed to get inspired and start building.

Related articles

Monthly Newsletter

Subscribe to get a summary of what we've shipped over the last month, plus everything you need to know around developer experience.

By submitting this form, I confirm that I acknowledge the collection and processing of personal data by Gitpod, as further described in the Privacy Policy.