N-API: Next generation APIs for Node.js native addons available across all LTS release lines

This blog was written by Arunesh Chandra, Senior Program Manager of Microsoft Edge, and Michael Dawson, IBM Community Lead for Node.js. It covers the current status of N-API, how you can use this technology, and modules that are adopting N-API. If you are attending Node Summit, there are multiple ways to learn more about N-API (more information on this in the post below).

You may have heard that Node.js has experimental support for N-API, a new API for native modules. Not anymore! N-API is now a stable and fully supported feature of Node.js as of version 10. It is also available as an experimental feature in Node.js 8 and 6.

As we discussed previously, N-API provides an ABI-stable abstraction over native JavaScript APIs to enable a more robust native module ecosystem. Why? The lack of an ABI-stable interface for Node.js modules creates a fragile ecosystem that gets impacted with every new Node.js release. This fragility creates friction in the growth of Node.js as a mature platform.

It not only adds to the maintenance burden for native module maintainers, but it also presents a major barrier to upgrading Node.js versions in production for module consumers, who have mission critical native code dependencies in their production deployments.

With N-API, native module developers can compile their module once per platform and architecture, and make it available for any version of Node.js that implements N-API. This holds true even for versions of Node.js that are built with a different VM, e.g. Node-ChakraCore.

N-API was put in as an experimental feature in Node.js 8.0, and after meeting rigorous exit criteria defined by the community, it has been promoted to a supported feature in Node.js 10. It has also been backported to all LTS release lines. Having N-API with the same API across all LTS releases is a great milestone and we believe this is a significant step towards enabling its adoption. Many thanks to Gabriel Schulhof who put in a tremendous amount of effort to backport this feature across these versions.

Using N-API across versions

As of version 8.11.2 all of the LTS release lines provide the same set of APIs for N-API. The status of each is as follows:

• 10.x — stable
• 8.x — experimental with warning. This will become stable in the next SemVer minor release (8.12)
• 6.x — experimental, no warning. In backporting the updated APIs to 6.x, we believed a period of testing was necessary before making it stable. In addition, since 6.x is in maintenance mode, we’ll need to build consensus in the TSC in order to get the approval to make it stable in the future. Want to help? Please test with 6.x and provide feedback. Your feedback will help us determine if this feature is ready to be stable in 6.x.

Node-pre-gyp

For native module authors, Node-pre-gyp is a great tool to publish binary packages that end-users can install. Since it’s such a crucial part of the existing Node.js native module ecosystem, the N-API team worked with the maintainer of node-pre-gyp to integrate support for building and publishing N-API modules. Many thanks to Jim Schlight and Dane Springmeyer who made this happen.

Having Node-pre-gyp ready to support the N-API addons is another great milestone that we believe is a significant step towards enabling adoption.

If you would like to learn more about using node-pre-gyp with N-API, check out the node-pre-gyp documentation here: https://github.com/mapbox/node-pre-gyp#n-api-considerations

Node-addon-api

While N-API provides a C interface, many module developers use C++. The node-addon-api module provides an inlined wrapper that allows developers to use C++ and easily migrate from nan. The node-addon-api module was updated to use the N-API built-into 6.X such that it uses the built-in version of N-API for the latest versions of 6.x, 8.x and 10.x. There is a growing list of dependents on this module.

The N-API team continues to focus on filling out the documentation for node-addon-api and addressing reported issues as we continue to see increased usage.

N-API in use — Module Showcase

We are pleased to see that developers embracing this feature and have started publishing N-API based native addons on npm. In addition to the N-API addon dependencies shown above, there are also a number of packages tagged as N-API.

As adoption grows, we’d like to take the opportunity to regularly provide updates on some of the modules, which are adopting N-API. If you have a module that uses N-API in a unique or interesting way, or that you are just very proud of, let us know on the N-API repo so that we can highlight it for future updates.

Today, we are highlighting Log++, which demonstrates N-API being used for logging into an application with high performance requirements.

Fast logging is crucial to getting great performance for any application that depends on reliable diagnostic telemetry. Loggers in the past have been written in JavaScript because of the development and maintenance overhead of native modules, but N-API allows this (often critical) component of an app to be written as native code, and also runs the same binary across multiple versions of Node.js. Additionally, it has the following benefits:

• Compute-intensive formatting is implemented in high performance C++
• The formatting task is offloaded to a background processing thread

The result is a logger that is 4–7 times faster than existing logging solutions.

Get Involved

Want to get more involved? Check out these documentation links below:

• N-API documentation for the C API is available as part of the Node.js API docs: https://nodejs.org/dist/latest/docs/api/n-api.html
• Documentation for the C++ node-addon-api is available here: https://github.com/nodejs/node-addon-api (still a work in progress as we fill in more sections).

While we have made great progress on N-API, we can always use more help. Here are some ways you can help out:

• Porting your own native module to use N-API.
• Porting a module that your app depends on and upstream it.
• Submitting PRs to help complete the documentation for node-addon-api. While we have complete documentation for the core C APIs we still have some work to complete the documentation for node-addon-api
• Adding features from N-API to node-addon-api. As features get added to N-API, we need the corresponding wrappers for node-addon-api.
• Additional Testing for node-addon-api. We still need to complete the full test suite for node-addon-api.

In addition, you are always welcome to attend the weekly N-API team meetingon Thursdays at 1:30 EST.

If you’re attending the upcoming Node Summit conference, then there are additional resources that you can leverage to learn more about N-API. There are two N-API talks that will give you an overview of N-API and also a technical deep dive. In addition, there will be an N-API workshop on Day Zero to get some hands-on experience writing or porting native modules to N-API. It will be a great way to kick off your N-API development.

We hope to see you there!

 

SOURCE: https://medium.com/the-node-js-collection/n-api-next-generation-apis-for-node-js-native-addons-available-across-all-lts-release-lines-4f35b781f00e

 

Written by