Debug Node.js native addon with Xcode

3 min readMar 4, 2020

While I was working on a native addon for Node.js I had the need to debug my native code. In this article I want to share my experience on how to execute the debug through Xcode.

What many developers don’t know is that you can use node-gyp to create an Xcode project. This is possible following few steps:

Go inside the folder of your project
Execute the following command:

node-gyp build &&
node-gyp configure --debug -- -f xcode

At the end of the execution of the previous command a new folder called build has been generated on your project and inside it you can find two new files:

binding.xcodeproj
config.gypi

Now you can open the file binding.xcodeproj through Xcode and use this IDE to edit, debug and build your native addon.

Edit and build your code is a simple task you only have to select the source file change it and then press the button Build and run …

Now it’s time to configure the debug and like first thing you need to select the project addon and then Edit Scheme …

In the tab info set the executable that Xcode will use when you want to execute the debug operation. In this case you have to set the executable to the path of your Node.js installation that you can retrieve with the following command:

which node

The result of the command should be something like this:

/usr/local/bin/node

In the tab arguments you have to set the script that you want to start on executing the debug. In my case it is the index.js file placed in the root folder of my project.