Suggest an edit

Improve this article

Refine the answer for “What are native modules in Node.js?”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

## 1. What native modules are

**Native modules** in Node.js are modules written **in C or C++** that **plug into Node.js through a special API (Node-API / N-API)** and let you:

- run **low-level operations** faster than in plain JavaScript;
- interact with **system libraries** or external C libraries;
- **extend Node.js** with functionality that JS cannot reach on its own.

Examples:

- `bcrypt` (hashing), uses a C++ implementation under the hood;
- `canvas` (2D graphics rendering), uses the native Cairo library;
- `sqlite3`, connects to the SQLite library, written in C;
- `node-sass`, uses the native LibSass library.

## 2. How it works

When JS code calls a function from a native module, this happens:

1. JS calls the function from the module:

```javascript
  const addon = require('./build/Release/addon');
  console.log(addon.hello());
  ```
2. Node.js calls the corresponding C++ function through **bindings**.
3. The C++ code does the work (for example, calling a system API).
4. The result comes back to JavaScript through V8.

In short, a native module is a *bridge* between **JavaScript** and **C/C++**.

## 3. A simple native module example

### File `addon.cc`:

```javascript
#include <napi.h>

Napi::String Hello(const Napi::CallbackInfo& info) {
  return Napi::String::New(info.Env(), "Hello from C++!");
}

Napi::Object Init(Napi::Env env, Napi::Object exports) {
  exports.Set("hello", Napi::Function::New(env, Hello));
  return exports;
}

NODE_API_MODULE(addon, Init)
```

### `binding.gyp` (build instructions):

```javascript
{
  "targets": [
    {
      "target_name": "addon",
      "sources": ["addon.cc"]
    }
  ]
}
```

### Commands:

```javascript
npm install -g node-gyp
node-gyp configure
node-gyp build
```

After building, a binary file `build/Release/addon.node` appears.

### Using it in JS:

```javascript
const addon = require('./build/Release/addon');
console.log(addon.hello()); // → "Hello from C++!"
```

## 4. What native modules build on

Native modules use one of Node.js's **C/C++ APIs**:

| API | Purpose |
|---|---|
| **Node-API (N-API)** | A modern, stable interface for writing native modules. Independent of the V8 version. |
| **V8 API** | Low-level access to JS objects inside V8 (the older approach). Requires manual type and memory handling. |
| **Nan (Native Abstraction for Node.js)** | A layer that simplifies compatibility across Node.js and V8 versions. |

**N-API** is now the recommended choice, since it guarantees **compatibility across Node.js versions**.

## 5. Advantages of native modules

| Advantage | Description |
|---|---|
| High performance | C/C++ code runs faster than JS, especially for heavy computation. |
| Access to system APIs | Can call OS functions, drivers and libraries directly. |
| Extensibility | Lets you add new Node.js core functionality without modifying its sources. |
| Reuse of native libraries | Existing C/C++ libraries can be wrapped with a JS interface. |

## 6. Drawbacks and risks

| Drawback | Description |
|---|---|
| Development complexity | Requires knowing C++ and the internal structures of V8/Node.js. |
| Per-platform compilation | The module must be built for Windows, Linux, macOS (different binaries). |
| Version incompatibility | Older modules that use the V8 API directly can break on a Node.js upgrade. |
| Memory issues | Bugs in the C++ code can cause leaks or crash the process. |

## 7. Examples of popular native modules

| Module | Purpose |
|---|---|
| `bcrypt` | Password hashing (C++/OpenSSL) |
| `node-sass` | Compiling SCSS to CSS (C++) |
| `canvas` | Image and graphics work (C++) |
| `sqlite3` | Working with an SQLite database (C) |
| `sharp` | Image optimization (C++) |
| `grpc` | Fast serialization/deserialization for gRPC (C++) |
| `ffi-napi` | Calling native C libraries directly from JS |

## 8. Terms worth telling apart:

| Term | Meaning |
|---|---|
| **Core modules** | Built into Node.js (`fs`, `http`, `os`), part of the Node.js source itself. |
| **Native modules** | Written in C/C++ and loaded via `require()` as binaries (`.node`). |
| **JS modules** | Plain JavaScript modules (`.js`), loaded via `require` or `import`. |

## 9. Visualization

```javascript
┌──────────────────────────┐
│ JavaScript (V8)          │
│ require('addon.node')    │
└──────────┬───────────────┘
           ▼
┌──────────────────────────┐
│ Node.js C++ Bindings     │
│ (N-API / Nan / V8 API)   │
└──────────┬───────────────┘
           ▼
┌──────────────────────────┐
│ Native C/C++ library     │
│ (OpenSSL, SQLite, Cairo) │
└──────────────────────────┘
```

## 10. Quick summary

| Characteristic | Description |
|---|---|
| Format | `.node` (a compiled binary module) |
| Implementation language | C / C++ |
| API | Node-API (N-API), Nan, V8 API |
| Purpose | Extends Node.js with native functionality |
| Example | `const addon = require('./build/Release/addon')` |
| Used in | `bcrypt`, `sharp`, `sqlite3`, `canvas`, `node-sass` |

Markdown · drag & drop images · ⌘B / ⌘I shortcuts747 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.