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

Signed-off-by: Michael Dawson <[email protected]> PR-URL: #50168 Reviewed-By: Chengzhong Wu <[email protected]>
nodejs · Nov 11, 2023 · d62e812 · d62e812
1 parent 586ec48
commit d62e812
Showing 1 changed file with 26 additions and 5 deletions.
diff --git a/doc/api/n-api.md b/doc/api/n-api.md
@@ -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: