• Stars
    star
    2,162
  • Rank 21,326 (Top 0.5 %)
  • Language
    C++
  • License
    MIT License
  • Created almost 8 years ago
  • Updated 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Module for using Node-API from C++

NOTE: The default branch has been renamed! master is now named main

If you have a local clone, you can update it by running:

git branch -m master main
git fetch origin
git branch -u origin/main main

node-addon-api module

This module contains header-only C++ wrapper classes which simplify the use of the C based Node-API provided by Node.js when using C++. It provides a C++ object model and exception handling semantics with low overhead.

There are three options for implementing addons: Node-API, nan, or direct use of internal V8, libuv, and Node.js libraries. Unless there is a need for direct access to functionality that is not exposed by Node-API as outlined in C/C++ addons in Node.js core, use Node-API. Refer to C/C++ addons with Node-API for more information on Node-API.

Node-API is an ABI stable C interface provided by Node.js for building native addons. It is independent of the underlying JavaScript runtime (e.g. V8 or ChakraCore) and is maintained as part of Node.js itself. It is intended to insulate native addons from changes in the underlying JavaScript engine and allow modules compiled for one version to run on later versions of Node.js without recompilation.

The node-addon-api module, which is not part of Node.js, preserves the benefits of the Node-API as it consists only of inline code that depends only on the stable API provided by Node-API. As such, modules built against one version of Node.js using node-addon-api should run without having to be rebuilt with newer versions of Node.js.

It is important to remember that other Node.js interfaces such as libuv (included in a project via #include <uv.h>) are not ABI-stable across Node.js major versions. Thus, an addon must use Node-API and/or node-addon-api exclusively and build against a version of Node.js that includes an implementation of Node-API (meaning an active LTS version of Node.js) in order to benefit from ABI stability across Node.js major versions. Node.js provides an ABI stability guide containing a detailed explanation of ABI stability in general, and the Node-API ABI stability guarantee in particular.

As new APIs are added to Node-API, node-addon-api must be updated to provide wrappers for those new APIs. For this reason, node-addon-api provides methods that allow callers to obtain the underlying Node-API handles so direct calls to Node-API and the use of the objects/methods provided by node-addon-api can be used together. For example, in order to be able to use an API for which the node-addon-api does not yet provide a wrapper.

APIs exposed by node-addon-api are generally used to create and manipulate JavaScript values. Concepts and operations generally map to ideas specified in the ECMA262 Language Specification.

The Node-API Resource offers an excellent orientation and tips for developers just getting started with Node-API and node-addon-api.

Current version: 6.1.0

(See CHANGELOG.md for complete Changelog)

NPM NPM

node-addon-api is based on Node-API and supports using different Node-API versions. This allows addons built with it to run with Node.js versions which support the targeted Node-API version. However the node-addon-api support model is to support only the active LTS Node.js versions. This means that every year there will be a new major which drops support for the Node.js LTS version which has gone out of service.

The oldest Node.js version supported by the current version of node-addon-api is Node.js 14.x.

Setup

API Documentation

The following is the documentation for node-addon-api.

Examples

Are you new to node-addon-api? Take a look at our examples

Tests

To run the node-addon-api tests do:

npm install
npm test

To avoid testing the deprecated portions of the API run

npm install
npm test --disable-deprecated

To run the tests targeting a specific version of Node-API run

npm install
export NAPI_VERSION=X
npm test --NAPI_VERSION=X

where X is the version of Node-API you want to target.

To run a specific unit test, filter conditions are available

Example: compile and run only tests on objectwrap.cc and objectwrap.js

  npm run unit --filter=objectwrap

Multiple unit tests cane be selected with wildcards

Example: compile and run all test files ending with "reference" -> function_reference.cc, object_reference.cc, reference.cc

   npm run unit --filter=*reference

Multiple filter conditions can be joined to broaden the test selection

Example: compile and run all tests under folders threadsafe_function and typed_threadsafe_function and also the objectwrap.cc file npm run unit --filter='*function objectwrap'

Debug

To run the node-addon-api tests with --debug option:

npm run-script dev

If you want a faster build, you might use the following option:

npm run-script dev:incremental

Take a look and get inspired by our test suite

Benchmarks

You can run the available benchmarks using the following command:

npm run-script benchmark

See benchmark/README.md for more details about running and adding benchmarks.

More resource and info about native Addons

As node-addon-api's core mission is to expose the plain C Node-API as C++ wrappers, tools that facilitate n-api/node-addon-api providing more convenient patterns for developing a Node.js add-on with n-api/node-addon-api can be published to NPM as standalone packages. It is also recommended to tag such packages with node-addon-api to provide more visibility to the community.

Quick links to NPM searches: keywords:node-addon-api.

Other bindings

Badges

The use of badges is recommended to indicate the minimum version of Node-API required for the module. This helps to determine which Node.js major versions are supported. Addon maintainers can consult the Node-API support matrix to determine which Node.js versions provide a given Node-API version. The following badges are available:

Node-API v1 Badge Node-API v2 Badge Node-API v3 Badge Node-API v4 Badge Node-API v5 Badge Node-API v6 Badge Node-API v7 Badge Node-API v8 Badge Node-API Experimental Version Badge

Contributing

We love contributions from the community to node-addon-api! See CONTRIBUTING.md for more details on our philosophy around extending this module.

Team members

Active

Name GitHub Link
Anna Henningsen addaleax
Chengzhong Wu legendecas
Jack Xia JckXia
Kevin Eady KevinEady
Michael Dawson mhdawson
Nicola Del Gobbo NickNaso
Vladimir Morozov vmoroz

Emeritus

Name GitHub Link
Arunesh Chandra aruneshchandra
Benjamin Byholm kkoopa
Gabriel Schulhof gabrielschulhof
Hitesh Kanwathirtha digitalinfinity
Jason Ginchereau jasongin
Jim Schlight jschlight
Sampson Gao sampsongao
Taylor Woll boingoing

Licensed under MIT

More Repositories

1

node

Node.js JavaScript runtime ✨🐢🚀✨
JavaScript
97,973
star
2

node-v0.x-archive

Moved to https://github.com/nodejs/node
34,533
star
3

node-gyp

Node.js native addon build tool
Python
9,275
star
4

docker-node

Official Docker Image for Node.js 🐳 🐢 🚀
Dockerfile
7,872
star
5

http-parser

http request/response parser for c
C
6,223
star
6

undici

An HTTP/1.1 client, written from scratch for Node.js
JavaScript
6,182
star
7

nodejs.org

The Node.js® Website
TypeScript
6,020
star
8

Release

Node.js Release Working Group
3,803
star
9

nan

Native Abstractions for Node.js
C++
3,277
star
10

corepack

Zero-runtime-dependency package acting as bridge between Node projects and their package managers
TypeScript
2,542
star
11

node-addon-examples

Node.js C++ addon examples from http://nodejs.org/docs/latest/api/addons.html
C++
2,332
star
12

nodejs.dev

A redesign of Nodejs.org built using Gatsby.js with React.js, TypeScript, and Remark.
TypeScript
2,293
star
13

node-chakracore

Node.js on ChakraCore ✨🐢🚀✨
JavaScript
1,921
star
14

node-convergence-archive

Archive for node/io.js convergence work pre-3.0.0
JavaScript
1,837
star
15

llhttp

Port of http_parser to llparse
TypeScript
1,665
star
16

help

✨ Need help with Node.js? File an Issue here. 🚀
1,473
star
17

llnode

An lldb plugin for Node.js and V8, which enables inspection of JavaScript states for insights into Node.js processes and their core dumps.
C++
1,151
star
18

readable-stream

Node-core streams for userland
JavaScript
1,003
star
19

examples

A repository of runnable Node.js examples that go beyond "hello, world!"
JavaScript
652
star
20

TSC

The Node.js Technical Steering Committee
JavaScript
592
star
21

llparse

Generating parsers in LLVM IR
TypeScript
586
star
22

mentorship

Node.js Mentorship Program Initiative
585
star
23

citgm

Canary in the Gold Mine
JavaScript
567
star
24

http2

Working on an HTTP/2 implementation for Node.js Core
JavaScript
520
star
25

diagnostics

Node.js Diagnostics Working Group
513
star
26

security-wg

Node.js Ecosystem Security Working Group
JavaScript
495
star
27

next-10

Repository for discussion on strategic directions for next 10 years of Node.js
480
star
28

build

Better build and test infra for Node.
Shell
469
star
29

node-eps

Node.js Enhancement Proposals for discussion on future API additions/changes to Node core
442
star
30

education

A place to discover and contribute to education initiatives in Node.js
417
star
31

node-v8

Experimental Node.js mirror on V8 lkgr ✨🐢🚀✨
Shell
416
star
32

modules

Node.js Modules Team
413
star
33

package-maintenance

Repository for work for discussion of helping with maintenance of key packages in the ecosystem.
407
star
34

nodejs-zh-CN

node.js 中文化 & 中文社区
SCSS
395
star
35

performance

Node.js team focusing on performance
Shell
376
star
36

node-inspect

Code that's now part of node, previously `node debug` for `node --inspect`
JavaScript
340
star
37

node-report

Delivers a human-readable diagnostic summary, written to file.
C++
326
star
38

single-executable

This team aims to advance the state of the art in packaging Node.js applications as single standalone executables (SEAs) on all supported operating systems.
306
star
39

quic

This repository is no longer active.
JavaScript
301
star
40

github-bot

@nodejs-github-bot's heart and soul
JavaScript
267
star
41

community-committee

The Node.js Community Committee (aka CommComm)
263
star
42

nodejs-ko

node.js 한국 커뮤니티
Stylus
263
star
43

amaro

Node.js TypeScript wrapper
JavaScript
261
star
44

node-core-utils

CLI tools for Node.js Core collaborators
JavaScript
253
star
45

unofficial-builds

Unofficial binaries for Node.js
Shell
252
star
46

evangelism

Letting the world know how awesome Node.js is and how to get involved!
242
star
47

abi-stable-node

Repository used by the Node-API team to manage work related to Node-API and node-addon-api
JavaScript
241
star
48

abi-stable-node-addon-examples

Node Add-on Examples with PoC ABI stable API for native modules
C++
237
star
49

changelog-maker

A git log to CHANGELOG.md tool
JavaScript
230
star
50

uvwasi

WASI syscall API built atop libuv
C
228
star
51

cjs-module-lexer

Fast lexer to extract named exports via analysis from CommonJS modules
JavaScript
226
star
52

iojs.org

JavaScript
219
star
53

installer

Electron based installer for Node.js.
JavaScript
194
star
54

getting-started

Getting started in Node.js!
193
star
55

postject

Easily inject arbitrary read-only resources into executable formats (Mach-O, PE, ELF) and use it at runtime.
JavaScript
186
star
56

web-server-frameworks

A place for Node.js Web-Server Framework authors and users to collaborate
182
star
57

repl

REPL rewrite for Node.js ✨🐢🚀✨
JavaScript
178
star
58

tooling

Advancing Node.js as a framework for writing great tools
170
star
59

snap

Node.js snap source and updater
Shell
168
star
60

code-and-learn

A series of workshop sprints for Node.js.
Dockerfile
164
star
61

benchmarking

Node.js Benchmarking Working Group
Shell
161
star
62

admin

Administrative space for policies of the TSC
JavaScript
157
star
63

docker-iojs

Official Docker images from the io.js project
Shell
156
star
64

full-icu-npm

convenience loader for 'small-icu' node builds
JavaScript
152
star
65

i18n

The Node.js Internationalization Working Group – A Community Committee initiative.
150
star
66

roadmap

This repository and working group has been retired.
135
star
67

gyp-next

A fork of the GYP build system for use in the Node.js projects
Python
131
star
68

loaders

ECMAScript Modules Loaders
128
star
69

nodejs-pt

Internacionalização & tradução para português referente ao site nodejs.org
108
star
70

dev-policy

node-foundation dev policy **draft**
108
star
71

promises

Promises Working Group Repository
107
star
72

nodejs-zh-TW

Node.js zh-TW
CSS
107
star
73

NG

Next Generation JavaScript IO Platform
103
star
74

nodejs-ja

Node.js 日本語ローカリゼーション
101
star
75

nodejs.org-archive

[DEPRECATED] Website repository for the Node.js project
Nginx
101
star
76

website-redesign

Facilitating the redesign of the nodejs.org website
99
star
77

node-core-test

Node 18's node:test, as an npm package
JavaScript
95
star
78

worker

Figuring out native (Web?)Worker support for Node
JavaScript
87
star
79

post-mortem

This WG is in the process of being folded into the Diagnostics WG.
85
star
80

typescript

TypeScript support in Node.js core
83
star
81

inclusivity

Improving inclusivity in the node community
80
star
82

CTC

Node.js Core Technical Committee & Collaborators
80
star
83

nodejs-ru

Перевод io.js на русский язык
JavaScript
79
star
84

ecmascript-modules

A fork of Node.js to hash out ideas related to ESModules
JavaScript
73
star
85

docs

A place for documentation. (this repository is inactive)
71
star
86

webcrypto

This repository has been archived. The WebCrypto API has been implemented in recent versions of Node.js and does not require additional packages.
JavaScript
69
star
87

import-in-the-middle

Like `require-in-the-middle`, but for ESM import
JavaScript
67
star
88

automation

Better automation for the Node.js project
66
star
89

api

API WG
61
star
90

email

MX server management for iojs.org (and eventually nodejs.org)
JavaScript
60
star
91

user-feedback

Node.js User Feedback Initiative
56
star
92

loaders-test

Examples demonstrating the Node.js ECMAScript Modules Loaders API
JavaScript
54
star
93

core-validate-commit

Validate commit messages for Node.js core
JavaScript
52
star
94

board

The Node Foundation Board of Directors
JavaScript
52
star
95

branch-diff

A tool to list print the commits on one git branch that are not on another using loose comparison
JavaScript
52
star
96

logos

Logo ideas
51
star
97

promise-use-cases

Short lived repository in order to discuss Node.js promise use cases in Collaborator Summit Berlin 2018
JavaScript
50
star
98

open-standards

Node.js Open Standards Team
43
star
99

version-management

Discussion Group for Version Management
42
star
100

hardware

Hardware Working Group
42
star