1# Setup
2
3## Prerequisites
4
5Before starting to use **Node-API** you need to assure you have the following
6prerequisites:
7
8* **Node.JS** see: [Installing Node.js](/)
9
10* **Node.js native addon build tool**
11
12  - **[node-gyp](node-gyp.md)**
13
14## Installation and usage
15
16To use **Node-API** in a native module:
17
18  1. Add a dependency on this package to `package.json`:
19
20     ```json
21       "dependencies": {
22         "node-addon-api": "*",
23       }
24     ```
25
26  2. Decide whether the package will enable C++ exceptions in the Node-API
27     wrapper, and reference this package as a dependency in `binding.gyp`.
28     The base ABI-stable C APIs do not throw or handle C++ exceptions, but the
29     Node-API C++ wrapper classes may _optionally_
30     [integrate C++ and JavaScript exception-handling
31     ](/node-addon-api/blob/HEAD/doc/error_handling.md).
32
33     To use without C++ exceptions, add the following to `binding.gyp`:
34
35     ```gyp
36       'dependencies': [
37         "<!(node -p \"require('node-addon-api').targets\"):node_addon_api",
38       ],
39     ```
40
41     To enable that capability, add an alternative dependency in `binding.gyp`:
42
43     ```gyp
44       'dependencies': [
45         "<!(node -p \"require('node-addon-api').targets\"):node_addon_api_except",
46       ],
47     ```
48
49     If you decide to use node-addon-api without C++ exceptions enabled, please
50     consider enabling node-addon-api safe API type guards to ensure the proper
51     exception handling pattern:
52
53     ```gyp
54       'dependencies': [
55         "<!(node -p \"require('node-addon-api').targets\"):node_addon_api_maybe",
56       ],
57     ```
58
59  3. If you would like your native addon to support OSX, please also add the
60     following settings in the `binding.gyp` file:
61
62       ```gyp
63       'conditions': [
64         ['OS=="mac"', {
65             'cflags+': ['-fvisibility=hidden'],
66             'xcode_settings': {
67               'GCC_SYMBOLS_PRIVATE_EXTERN': 'YES', # -fvisibility=hidden
68             }
69         }]
70       ]
71       ```
72
73  4. Include `napi.h` in the native module code.
74     To ensure only ABI-stable APIs are used, DO NOT include
75     `node.h`, `nan.h`, or `.h`.
76
77     ```C++
78     #include "napi.h"
79     ```
80
81At build time, the Node-API back-compat library code will be used only when the
82targeted node version *does not* have Node-API built-in.
83
84The preprocessor directive `NODE_ADDON_API_DISABLE_DEPRECATED` can be defined at
85compile time before including `napi.h` to skip the definition of deprecated APIs.
86
87By default, throwing an exception on a terminating environment (eg. worker
88threads) will cause a fatal exception, terminating the Node process. This is to
89provide feedback to the user of the runtime error, as it is impossible to pass
90the error to JavaScript when the environment is terminating. In order to bypass
91this behavior such that the Node process will not terminate, define the
92preprocessor directive `NODE_API_SWALLOW_UNTHROWABLE_EXCEPTIONS`.
93