Cookies are used for the best experience on my website.

Accept Cookie Policy

No internet detected

Check your connection and try again.

Logo Image

No match found

Buy a coffee

I launched this blog in 1995. Since then, we have published 1603 articles. It's all free and means a lot of work in my spare time. I enjoy sharing knowledge and experiences with you.

Your support

Have you learned something new by reading, listening, or watching my content? With your help, I can spend enough time to keep publishing great content in the future.

Or, select an option below:

A small slice of my data processing time each month

It's ongoing work running this site and what's really great is ongoing support. Here's a sense of what goes into this site: research topics for discussion. Manage the Tech stuff: website, SEO, graphics, email, back-end servers, DNS routing, edge servers. Create advertisements and load the campaigns in Google Ads. Manage the social media forums (Facebook, Reddit, Twitter). Write updates to the blog. Keep GitHub up-to-date.

$4.50 — A large cappuccino at my local

Things just work better with coffee! I like to take the kids to school then grab a cappuccino from my local on the way home before beginning the things that take mental energy.

$8.99 — A month of Netflix for some quiet nights in

A lot of the work on this happens after hours when I should be relaxing on the couch. Help me make it so and I promise to keep off the devices for a bit!

$11.50 — Fund a month of email delivery

This site sends out thousands of emails every month. For that volume and to ensure deliverability, I need to pay MailChimp.

$20 — Pay for one month of AWS storage fees

Websites are not free. The storage alone takes some cash. If you are willing to lighten the burden, we can keep this site up online.

$30 — One hour's pay for a graphics artist

Art doesn't create itself without a hand to guide it. I can't draw, so I need to pay others to help.

$45 — Pay a full-stack web developer for one hour

Much of the work on this site happens on weekends which means giving up time with the kids. Help me pay the developers so I can give my kids more time.

Debugging HEXO in VScode

Be it for your custom theme or new NPM plugin for your ⋯


Richie Bartlett, Jr.

  • 1255

  • 9554

  • 20

  • 3

  • 3

Intro 🔗

This is part three of a mini series on my journey to build my own blogging site without using WordPress or any blogging site like Tumbler or Medium. I want full control of my published thoughts. This includes if and how I should share my data with advertisers and crawlers.

History 🔗

I remember the days when you had to print console statements in your code to troubleshoot odd behavior. When you needed to dig into the variables and insides the functions and scopes. As long as there was a developer console I could see the output, I was good to go.

However, this left a few undesirable “features” in the code. Either you wrote a custom error function that you could turn off using a global variable… Or, you had to go back through and manually remove all those print statements to clean-up the code before pushing to production.

If you opted for the custom error function (or class), then you ended up with bloated code that consumed memory overhead — even if it wasn’t used.

Setup the IDE 🔗

Now, you can simply forego the print statements and inspect the in-memory variables inside VScode. (You still need to output “user errors,” however.)

Extensions 🔗

You need to have JavaScript Debugger and Hexo Utils extensions installed.

launch.json 🔗

In addition to installing the extensions, you’ll need to configure the debugger in VScode. Below is the basic config recommended to add:

📖 Find the attribute definitions here:

  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit:
  "version": "0.2.0",
  "configurations": [
          "type": "node",
          "request": "launch",
          "name": "HEXO server",
          "program": "${workspaceFolder}/node_modules/hexo-cli/bin/hexo",
          "args": [
              "-p 4000"
          "restart": true,
          "runtimeExecutable": "node",
          "runtimeArgs": [
          "stopOnEntry": true,
          "sourceMaps": true,
          "cwd": "${workspaceFolder}"
          "type": "node",
          "request": "launch",
          "name": "HEXO generate",
          "program": "${workspaceFolder}/node_modules/hexo-cli/bin/hexo",
          "args": [
          "sourceMaps": true,
          "cwd": "${workspaceFolder}"

Take this file and save it to ~/project/.vscode/launch.json. This is where VScode will look to find the debugger config. (Replace the /project folder with the root of your project.) You may also wish to update your .gitignore file if you don’t wish to publish to your repo. In my case, I want the team to benefit from the same config, so I leave it in.

Debug it within the IDE 🔗

Now that we have the extensions and config setup, it’s time to start debugging Hexo.

Be sure to exit out of Hexo if it’s already running to avoid conflicts.

Basic Debugger | Microsoft

Click on the Run and debug icon (shift + command + D) and from the VScode debugger side-panel, select Debug HEXO server from the drop-down options.

As we already configured the stopOnEntry option, it will pause the code after starting it. However, it’s also a good idea to create your breakpoints within your code to troubleshoot it faster.

Now tap F5 to start the debugger.

Stepping through the Matrix 🔗

See the RUN menu for breakpoint options

You should see a toolbar at the top of VScode. Each of these buttons are defined below.

Be sure to check the options for Caught Exceptions and Uncaught Exceptions.


You should see something similar to this:

Debugging HEXO

From here, you can start to step through the code and troubleshoot its behavior. In the Variables panel, you can review the current status of values (and functions). The Call Stack panel displays the list of functions that are called (most recent is at the top). Loaded Scripts shows all the modules called by HEXO. Watch is where you can add variables to see changes within the current context or scope of the function you are stepping through. And, if you are outputting anything to the Debug Console, it would show up at the bottom of the screen.

As you can see, VScode makes it easy to dive deeper into the code and follow along. Additionally, you can learn how the code works faster by reviewing the Global variables and functions in the Variables panel. Watch the Call Stack to see how functions are called.

In the code, you can hover your mouse above a variable to see its value. Additionally, you can add it to the Watch panel to see how it changes over runtime.

🎥 Debugging a Hexo plugin | Video (19:06 minutes)

Debugging the Theme 🔗

The above illustrates how to debug the JS files in the node_modules folder (and your HEXO plugins)… However, VScode doesn’t step through your (EJS) theme files by default. To achieve that, you must attach the debugger to the NodeJS process.

First, add the following configuration block to your launch.json file.

      "type": "node",
      "name": "Hexo Theme inspector",
      "request": "attach",
      "program": "${workspaceFolder}/node_modules/hexo-cli/bin/hexo",
      "args": [
          "-p 4001",
      "runtimeExecutable": "node",
      "runtimeArgs": [
      "processId": "${command:PickProcess}",
      "protocol": "inspector",
      "address": "localhost",
      "port": 4001,
      "restart": true,
      "sourceMaps": true,
      "outFiles": [
      "localRoot": "${workspaceFolder}",
      "remoteRoot": "${workspaceFolder}",
      "cwd": "${workspaceFolder}",
      "console": "internalConsole"

Second, run the following command from within the terminal console of VScode.

 hexo clean && node --inspect-brk=4001 $(which hexo) server -p 4001

Next, select Hexo Theme inspector from the dropdown of the debugger panel. Click the green run button. You will be prompted to select the nodeJS process for HEXO.

You should see “Debugger listening on …” and “Debugger attached.”

🎥 Walk-through on Debugging Hexo in VScode | Video (11:50 minutes)

Performance Monitoring 🔗

For analyzing the performance of your HEXO (plugin) project, you’ll need to add another extension to VScode. Flame Chart Visualizer for JavaScript Profiles

Flame Chart Visualizer for JavaScript Profiles

While running or debugging a JavaScript debug target (a launch type of node, chrome, msedge, extensionHost, or their pwa- prefixed versions), the realtime performance view is shown in the Debug view:

Realtime Performance

By default, this view shows chronological “snapshots” of your program’s stack taken roughly each millisecond. You can zoom and explore the flamechart, and ctrl or cmd+click on stacks to jump to the stack location.

Flame charts

The flame chart also supports a “left heavy” view, toggled by clicking the button in the upper-right corner of the chart.

Other troubleshooting tools 🔗

🎥 Demo of Node Clinic with Matteo Collina | Video (12:07 minutes)
To find out more about Node Clinic visit:

Reference 🔗

This license allows reusers to distribute, remix, adapt, and build upon the material in any medium or format, so long as attribution is given to the creator. The license allows for commercial use. If you remix, adapt, or build upon the material, you must license the modified material under identical terms.