@@ -239,11 +239,32 @@ available to the module code. |
239 | 239 |
|
240 | 240 | ## Node-API version matrix |
241 | 241 |
|
242 | | -Node-API versions are additive and versioned independently from Node.js. |
243 | | -Version 4 is an extension to version 3 in that it has all of the APIs |
244 | | -from version 3 with some additions. This means that it is not necessary |
245 | | -to recompile for new versions of Node.js which are |
246 | | -listed as supporting a later version. |
| 242 | +Up until version 9, Node-API versions were additive and versioned |
| 243 | +independently from Node.js. This meant that any version was |
| 244 | +an extension to the previous version in that it had all of |
| 245 | +the APIs from the previous version with some additions. Each |
| 246 | +Node.js version only supported a single Node-API version. |
| 247 | +For example v18.15.0 supports only Node-API version 8. ABI stability was |
| 248 | +achieved because 8 was a strict superset of all previous versions. |
| 249 | + |
| 250 | +As of version 9, while Node-API versions continue to be versioned |
| 251 | +independently an add-on that ran with Node-API version 9 may need |
| 252 | +code updates to run with Node-API version 10. ABI stability |
| 253 | +is maintained, however, because Node.js versions that support |
| 254 | +Node-API versions higher than 8 will support all versions |
| 255 | +between 8 and the highest version they support and will default |
| 256 | +to providing the version 8 APIs unless an add-on opts into a |
| 257 | +higher Node-API version. This approach provides the flexibility |
| 258 | +of better optimizing existing Node-API functions while |
| 259 | +maintaining ABI stability. Existing add-ons can continue to run without |
| 260 | +recompilation using an earlier version of Node-API. If an add-on |
| 261 | +needs functionality from a newer Node-API version, changes to existing |
| 262 | +code and recompilation will be needed to use those new functions anyway. |
| 263 | + |
| 264 | +In versions of Node.js that support Node-API version 9 and later, defining |
| 265 | +`NAPI_VERSION=X` and using the existing add-on initialization macros |
| 266 | +will bake in the requested Node-API version that will be used at runtime |
| 267 | +into the add-on. If `NAPI_VERSION` is not set it will default to 8. |
247 | 268 |
|
248 | 269 | This table may not be up to date in older streams, the most up to date |
249 | 270 | information is in the latest API documentation in: |
|