Platform Support

The following chart shows the availability of each N-API function on each platform. The functions point to the related part of the official N-API documentation.

Supported features	Linux (Ubuntu)
napi_add_env_cleanup_hook	O
napi_async_complete_callback	O
napi_async_destroy	O
napi_async_execute_callback	O
napi_async_init	O
napi_callback	O
napi_callback_info	O
napi_call_function	O
napi_cancel_async_work	O
napi_close_callback_scope	O
napi_close_escapable_handle_scope	O
napi_close_handle_scope	O
napi_coerce_to_bool	O
napi_coerce_to_number	O
napi_coerce_to_object	O
napi_coerce_to_string	O
napi_create_array	O
napi_create_arraybuffer	O
napi_create_array_with_length	O
napi_create_async_work	O
napi_create_buffer	O
napi_create_buffer_copy	O
napi_create_dataview	O
napi_create_double	O
napi_create_error	O
napi_create_external	O
napi_create_external_arraybuffer	O
napi_create_external_buffer	O
napi_create_function	O
napi_create_int32	O
napi_create_int64	O
napi_create_object	O
napi_create_promise	O
napi_create_range_error	O
napi_create_reference	O
napi_create_string_latin1	O
napi_create_string_utf16	O
napi_create_string_utf8	O
napi_create_symbol	O
napi_create_threadsafe_function	O
napi_create_typedarray	O
napi_create_type_error	O
napi_create_uint32	O
napi_define_class	O
napi_define_properties	O
napi_delete_async_work	O
napi_delete_element	O
napi_delete_property	O
napi_delete_reference	O
napi_env	O
napi_escapable_handle_scope	O
napi_escape_handle	O
napi_extended_error_info	O
napi_fatal_error	O
napi_fatal_exception	O
napi_finalize	O
napi_get_and_clear_last_exception	O
napi_get_arraybuffer_info	O
napi_get_array_length	O
napi_get_boolean	O
napi_get_buffer_info	O
napi_get_cb_info	O
napi_get_dataview_info	O
napi_get_element	O
napi_get_global	O
napi_get_last_error_info	O
napi_get_named_property	O
napi_get_new_target	O
napi_get_node_version	O
napi_get_null	O
napi_get_property	O
napi_get_property_names	O
napi_get_prototype	O
napi_get_reference_value	O
napi_get_typedarray_info	O
napi_get_undefined	O
napi_get_uv_event_loop	O
napi_get_value_bool	O
napi_get_value_double	O
napi_get_value_external	O
napi_get_value_int32	O
napi_get_value_int64	O
napi_get_value_string_latin1	O
napi_get_value_string_utf16	O
napi_get_value_string_utf8	O
napi_get_value_uint32	O
napi_get_version	O
napi_handle_scope	O
napi_has_element	O
napi_has_named_property	O
napi_has_own_property	O
napi_has_property	O
napi_instanceof	O
napi_is_array	O
napi_is_arraybuffer	O
napi_is_buffer	O
napi_is_dataview	O
napi_is_error	O
napi_is_exception_pending	O
napi_is_promise	O
napi_is_typedarray	O
napi_make_callback	O
napi_new_instance	O
napi_open_callback_scope	O
napi_open_escapable_handle_scope	O
napi_open_handle_scope	O
napi_property_attributes	O
napi_property_descriptor	O
napi_queue_async_work	O
napi_ref	O
napi_reference_ref	O
napi_reference_unref	O
napi_reject_deferred	O
napi_remove_env_cleanup_hook	O
napi_remove_wrap	O
napi_resolve_deferred	O
napi_set_element	O
napi_set_named_property	O
napi_set_property	O
napi_status	O
napi_strict_equals	O
napi_throw	O
napi_throw_error	O
napi_throw_range_error	O
napi_throw_type_error	O
napi_typedarray_type	O
napi_typeof	O
napi_unwrap	O
napi_value	O
napi_valuetype	O
napi_wrap	O

The API does not support the following features:

• napi_threadsafe_function
• napi_threadsafe_function_release_mode
• napi_threadsafe_function_call_mode
• napi_threadsafe_function_call_js
• napi_create_bigint_int64
• napi_create_bigint_uint64
• napi_create_bigint_words
• napi_get_value_bigint_int64
• napi_get_value_bigint_uint64
• napi_get_value_bigint_words
• napi_add_finalizer
• Asynchronous Thread-safe Function Calls:
  • napi_create_threadsafe_function
  • napi_get_threadsafe_function_context
  • napi_call_threadsafe_function
  • napi_acquire_threadsafe_function
  • napi_release_threadsafe_function
  • napi_ref_threadsafe_function
  • napi_unref_threadsafe_function

N-API

Based on Node.js v10.15 (LTS)

N-API (pronounced N as in the letter, followed by API) is an API for building native Addons. N-API is generally used to create and manipulate JavaScript values. You can read more about N-API here.

Our implementation works with either ES2015 enabled or disabled. All of the N-API ES2015 features throw an exception when IoT.js isn't compiled with ES2015 yet they are used.

Building N-API with IoT.js

You need to append the --n-api parameter to the build command (e.g. tools/build.py --n-api). This automatically adds the N-API module to IoT.js.

To run N-API test you should also append --n-api after the testrunner.py.

Building a simple module

node-gyp

C++ code needs to be compiled into executable form whether it be as an object file to linked with others, a shared library, or a standalone executable.

The main reason for this is that we need to link to the Node.js dependencies and headers correctly, another reason is that we need a cross platform way to build C++ source into binary for the target platform.

Until now node-gyp is the de-facto standard build tool for writing Node.js addons. It's based on Google's gyp build tool, which abstract away many of the tedious issues related to cross platform building.

node-gyp uses a file called binding.gyp that is located on the root of your addon project.

binding.gyp file, contains all building configurations organized with a JSON like syntax. The most important parameter is the target that must be set to the same value used on the initialization code of the addon as in the examples reported below:

binding.gyp

{
  "targets": [
    {
      # myModule is the name of your native addon
      "target_name": "myModule",
      "sources": ["src/my_module.cc", ...],
      ...
  ]
}

my_module.cc

#include <napi.h>

// ...

/**
* This code is our entry-point. We receive two arguments here, the first is the
* environment that represent an independent instance of the JavaScript runtime,
* the second is exports, the same as module.exports in a .js file.
* You can either add properties to the exports object passed in or create your
* own exports object. In either case you must return the object to be used as
* the exports for the module when you return from the Init function.
*/
Napi::Object Init(Napi::Env env, Napi::Object exports) {

  // ...

  return exports;
}

/**
* This code defines the entry-point for the Node addon, it tells Node where to go
* once the library has been loaded into active memory. The first argument must
* match the "target" in our *binding.gyp*. Using NODE_GYP_MODULE_NAME ensures
* that the argument will be correct, as long as the module is built with
* node-gyp (which is the usual way of building modules). The second argument
* points to the function to invoke. The function must not be namespaced.
*/
NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init)

node-gyp reference

• Installation
• How to use
• The binding.gyp file
• Commands
• Command options
• Configuration

Sometimes finding the right settings for binding.gyp is not easy so to accomplish at most complicated task please refer to:

• GYP documentation
• node-gyp wiki The most important parameter is the target that must be set to the same value used on the initialization code of the addon. To use the N-API functions you need to include node-api.h in your native module.