Before starting to use N-API you need to assure you have the following prerequisites:
-
Node.JS see: Installing Node.js
-
Node.js native addon build tool
To use N-API in a native module:
- Add a dependency on this package to
package.json
:
"dependencies": {
"node-addon-api": "*",
}
- Reference this package's include directory and gyp file in
binding.gyp
:
'include_dirs': ["<!@(node -p \"require('node-addon-api').include\")"],
- Decide whether the package will enable C++ exceptions in the N-API wrapper.
The base ABI-stable C APIs do not throw or handle C++ exceptions, but the
N-API C++ wrapper classes may optionally
integrate C++ and JavaScript exception-handling
.
To enable that capability, C++ exceptions must be enabled in
binding.gyp
:
'cflags!': [ '-fno-exceptions' ],
'cflags_cc!': [ '-fno-exceptions' ],
'xcode_settings': {
'GCC_ENABLE_CPP_EXCEPTIONS': 'YES',
'CLANG_CXX_LIBRARY': 'libc++',
'MACOSX_DEPLOYMENT_TARGET': '10.7',
},
'msvs_settings': {
'VCCLCompilerTool': { 'ExceptionHandling': 1 },
},
Alternatively, disable use of C++ exceptions in N-API:
'defines': [ 'NAPI_DISABLE_CPP_EXCEPTIONS' ],
- If you would like your native addon to support OSX, please also add the
following settings in the
binding.gyp
file:
['OS=="mac"', {
'cflags+': ['-fvisibility=hidden'],
'xcode_settings': {
'GCC_SYMBOLS_PRIVATE_EXTERN': 'YES', # -fvisibility=hidden
}
}]
- Include
napi.h
in the native module code. To ensure only ABI-stable APIs are used, DO NOT includenode.h
,nan.h
, orv8.h
.
#include "napi.h"
At build time, the N-API back-compat library code will be used only when the targeted node version does not have N-API built-in.
The preprocessor directive NODE_ADDON_API_DISABLE_DEPRECATED
can be defined at
compile time before including napi.h
to skip the definition of deprecated APIs.