Skip to content

doc: add information about Node-API versions >=9 #50168

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
mhdawson wants to merge 15 commits into from
Closed

doc: add information about Node-API versions >=9 #50168

Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
f84e39b
doc: add information about Node-API versions >=9
mhdawson Oct 12, 2023
87155ef
Update n-api.md
mhdawson Oct 13, 2023
aaad700
squash: make linter happy
mhdawson Oct 13, 2023
626e1a2
Update doc/api/n-api.md
mhdawson Oct 17, 2023
fd3279c
Update n-api.md
mhdawson Oct 17, 2023
cfcc153
Update doc/api/n-api.md
mhdawson Oct 20, 2023
91db079
Update doc/api/n-api.md
mhdawson Oct 20, 2023
59552c9
Update doc/api/n-api.md
mhdawson Oct 20, 2023
bcaaf77
Update doc/api/n-api.md
mhdawson Oct 20, 2023
ef41a2f
Update doc/api/n-api.md
mhdawson Oct 20, 2023
ec30e4f
Update doc/api/n-api.md
mhdawson Oct 20, 2023
ef5fc04
Update doc/api/n-api.md
mhdawson Oct 20, 2023
0231b66
Update doc/api/n-api.md
mhdawson Oct 20, 2023
7fa9d66
Update n-api.md
mhdawson Oct 23, 2023
e7fda3c
Update n-api.md
mhdawson Oct 23, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 26 additions & 5 deletions doc/api/n-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -239,11 +239,32 @@ available to the module code.

## Node-API version matrix

Node-API versions are additive and versioned independently from Node.js.
Version 4 is an extension to version 3 in that it has all of the APIs
from version 3 with some additions. This means that it is not necessary
to recompile for new versions of Node.js which are
listed as supporting a later version.
Up until version 9, Node-API versions were additive and versioned
independently from Node.js. This meant that any version was
an extension to the previous version in that it had all of
the APIs from the previous version with some additions. Each
Node.js version only supported a single Node-API version.
For example v18.15.0 supports only Node-API version 8. ABI stability was
achieved because 8 was a strict superset of all previous versions.

As of version 9, while Node-API versions continue to be versioned
independently an add-on that ran with Node-API version 9 may need
code updates to run with Node-API version 10. ABI stability
is maintained, however, because Node.js versions that support
Node-API versions higher than 8 will support all versions
between 8 and the highest version they support and will default
to providing the version 8 APIs unless an add-on opts into a
higher Node-API version. This approach provides the flexibility
of better optimizing existing Node-API functions while
maintaining ABI stability. Existing add-ons can continue to run without
recompilation using an earlier version of Node-API. If an add-on
needs functionality from a newer Node-API version, changes to existing
code and recompilation will be needed to use those new functions anyway.

In versions of Node.js that support Node-API version 9 and later, defining
`NAPI_VERSION=X` and using the existing add-on initialization macros
will bake in the requested Node-API version that will be used at runtime
into the add-on. If `NAPI_VERSION` is not set it will default to 8.

This table may not be up to date in older streams, the most up to date
information is in the latest API documentation in:
Expand Down