Skip to content

Commit a3599a5

Browse files
mhdawsonrvagg
authored andcommitted
doc: better linkage to node-addon-api
One of the comments we got at the N-API workshop at NodeConfEU was that we should have a better link to node-addon-api and the docs in the main API docs for N-API. The goal being to help people find node-addon-api and potentially start with the node-addon-api docs instead if they are using C++. This expands and strengthens the link along with a recommendation that starting with the node-addon-api docs might make sense. PR-URL: #24371 Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Franziska Hinkelmann <franziska.hinkelmann@gmail.com>
1 parent 5f747f1 commit a3599a5

File tree

1 file changed

+45
-7
lines changed

1 file changed

+45
-7
lines changed

doc/api/n-api.md

+45-7
Original file line numberDiff line numberDiff line change
@@ -34,13 +34,51 @@ properties:
3434
handling section [Error Handling][].
3535

3636
The N-API is a C API that ensures ABI stability across Node.js versions
37-
and different compiler levels. However, we also understand that a C++
38-
API can be easier to use in many cases. To support these cases we expect
39-
there to be one or more C++ wrapper modules that provide an inlineable C++
40-
API. Binaries built with these wrapper modules will depend on the symbols
41-
for the N-API C based functions exported by Node.js. These wrappers are not
42-
part of N-API, nor will they be maintained as part of Node.js. One such
43-
example is: [node-addon-api](https://github.com/nodejs/node-addon-api).
37+
and different compiler levels. A C++ API can be easier to use.
38+
To support using C++, the project maintains a
39+
C++ wrapper module called
40+
[node-addon-api](https://github.com/nodejs/node-addon-api).
41+
This wrapper provides an inlineable C++ API. Binaries built
42+
with `node-addon-api` will depend on the symbols for the N-API C-based
43+
functions exported by Node.js. `node-addon-api` is a more
44+
efficient way to write code that calls N-API. Take, for example, the
45+
following `node-addon-api` code. The first section shows the
46+
`node-addon-api` code and the second section shows what actually gets
47+
used in the addon.
48+
49+
```C++
50+
Object obj = Object::New(env);
51+
obj["foo"] = String::New(env, "bar");
52+
```
53+
54+
```C++
55+
napi_status status;
56+
napi_value object, string;
57+
status = napi_create_object(env, &object);
58+
if (status != napi_ok) {
59+
napi_throw_error(env, ...);
60+
return;
61+
}
62+
63+
status = napi_crate_string_utf8(env, "bar", NAPI_AUTO_LENGTH, &string);
64+
if (status != napi_ok) {
65+
napi_throw_error(env, ...);
66+
return;
67+
}
68+
69+
status = napi_set_named_property(env, object, "foo", string);
70+
if (status != napi_ok) {
71+
napi_throw_error(env, ...);
72+
return;
73+
}
74+
```
75+
76+
The end result is that the addon only uses the exported C APIs. As a result,
77+
it still gets the benefits of the ABI stability provided by the C API.
78+
79+
When using `node-addon-api` instead of the C APIs, start with the API
80+
[docs](https://github.com/nodejs/node-addon-api#api-documentation)
81+
for `node-addon-api`.
4482

4583
## Implications of ABI Stability
4684

0 commit comments

Comments
 (0)