🐛 Debugging Build Process

A bi-product of Hydrogen being based on Node.js is that we are able to support debugging of any JavaScript during the Hydrogen build process, just the way you would do with any other Node.js applications.

Let's see how we can do this!

Using Node.js Devtools in Chrome

Chrome has a built-in tool called the Node.js V8 inspector which allows us to debug Node.js applications in Chrome Devtools

1. Run the command below in the project root

      npx --node-arg="--inspect-brk" hydrogen build --dev

2. You will see output like this

      Debugger listening on ws://
      For help, see: https://nodejs.org/en/docs/inspector

3. Open the Chrome dev tools and you will see the Node logo popup right next to the Elements tab, click on it and you will go to the Node devtools

4. Once the Node Devtools are open, you will need to add your project folder to the workspace by clicking on "Add folder to workspace"

Now you can debug your JavaScript

Debugging in VS Code

There are two ways we could setup debugging in VS Code, either with VS Code's auto attaching feature or with a launch.json file

Auto attaching

1. Go to settings and search "auto attach" and turn the setting on

2. Set a breakpoint anywhere in your JavaScript

3. Run the command below

      npx --node-arg="--inspect-brk" hydrogen build --dev

VS Code will automatically attach to the Node.js debugging process and stop by your breakpoint

Setting up launch.json

1. Go to the Debug Explorer and click on the cogwheel on the top right, it will open up a launch.json file

2. Copy and paste the below JSON config to your launch.json file

        "version": "0.2.0",
        "configurations": [
            "type": "node",
            "request": "launch",
            "name": "Debug Hydrogen CLI",
            "skipFiles": [
            "program": "${workspaceFolder}/node_modules/hydrogen-cli/bin/run",
            "cwd": "${workspaceFolder}",
            "args": ["build", "--dev"],

Make sure to set a breakpoint

3. Go back to the Debug Explorer and run the debug "Debug Hydrogen CLI"