Skip to content
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

Jump to bottom

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

Closed
wants to merge 15 commits into from
Closed

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

Changes from 3 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
29 changes: 24 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,30 @@ 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 are additive and versioned
mhdawson marked this conversation as resolved.
Show resolved Hide resolved
independently from Node.js. For example, version 4 is an extension to version
3 in that it has all of the APIs from version 3 with some additions. Each
mhdawson marked this conversation as resolved.
Show resolved Hide resolved
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 updates to run with
mhdawson marked this conversation as resolved.
Show resolved Hide resolved
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 addon opts into a
mhdawson marked this conversation as resolved.
Show resolved Hide resolved
higher Node-API version. This approach provides the flexibility
of better optimizing existing Node-API functions while maintaing ABI stability.
mhdawson marked this conversation as resolved.
Show resolved Hide resolved
Existing addons can continue to run without recompilation using an earlier
version of Node-API. If an addon 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 addon initialization macros will bake
mhdawson marked this conversation as resolved.
Show resolved Hide resolved
in the requested Node-API version that will be used at runtime into the addon.
mhdawson marked this conversation as resolved.
Show resolved Hide resolved
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