explaingit

nodejs/node-gyp

10,614PythonAudience · developerComplexity · 3/5Setup · moderate

TLDR

A command-line tool that compiles C and C++ native addons for Node.js, letting your JavaScript app use low-level system features that plain JavaScript cannot reach.

Mindmap

mindmap
  root((node-gyp))
    What it does
      Compile C++ addons
      For Node.js
      Cross-platform builds
    Workflow
      Configure step
      Build step
      Output .node file
    Config file
      binding.gyp
      Lists source files
    Platform prereqs
      Python
      C++ compiler
      Visual Studio Windows
    Use cases
      Low-level system access
      Electron addons
      npm native packages
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Compile a C++ native addon so a Node.js app can call low-level system APIs that JavaScript cannot access.

USE CASE 2

Build native Node.js modules that work across Windows, macOS, and Linux using the same commands.

USE CASE 3

Compile addons against a specific Node.js version or an Electron runtime for desktop app compatibility.

USE CASE 4

Set up a build pipeline that automatically compiles native dependencies when a user runs npm install.

Tech stack

PythonC++Node.jsnpm

Getting it running

Difficulty · moderate Time to first run · 30min

Requires Python plus a C++ compiler, GCC or Clang on Linux/macOS, Visual C++ Build Tools on Windows, before npm install will work.

In plain English

node-gyp is a command-line tool that compiles native addons for Node.js. A native addon is a piece of code written in C or C++ that Node.js can load and run directly, giving programs access to low-level system features that plain JavaScript cannot reach. node-gyp takes care of the compilation step so that developers do not have to manage that process by hand. Before using it, you need a few system tools already installed. On Linux and macOS those are Python, make, and a C++ compiler. On Windows you need Python plus the Visual C++ build tools that come with Visual Studio. Once those are in place, you install node-gyp via npm like any other package. The typical workflow has three steps. First you run the configure command inside your addon folder, which reads a file called binding.gyp and generates the platform-appropriate build files. Then you run the build command, which compiles the code. The result is a .node file that your Node.js application can load. There is also a rebuild command that combines both steps, and a clean command to remove previous build output. The binding.gyp file is a JSON-like configuration file that sits alongside package.json at the root of your addon project. It tells node-gyp the name of your target and which source files to compile. The format is flexible enough to handle complex multi-file projects, though a minimal addon only needs a target name and a list of source files. node-gyp works on all major platforms with the same commands, and it supports building against different versions of Node.js, including third-party runtimes such as Electron that ship their own headers.

Copy-paste prompts

Prompt 1
Walk me through writing a minimal C++ Node.js native addon using node-gyp: the binding.gyp file, the C++ source, and the steps to configure, build, and require it in a Node.js script.
Prompt 2
I'm getting node-gyp rebuild errors on Windows. What Visual C++ build tools do I need installed, and how do I point node-gyp to the right Python version?
Prompt 3
How do I set up my package.json so that node-gyp automatically compiles my C++ addon when a user runs npm install on my package?
Prompt 4
Show me a binding.gyp file for a multi-file C++ addon that links against an external library on Linux and macOS.
Open on GitHub → Explain another repo

← nodejs on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.