Node-API addons (denoland#920)

fwqaaq · Sep 30, 2024 · c5a9af7 · c5a9af7
1 parent e89157f
commit c5a9af7
Show file tree

Hide file tree

Showing 2 changed files with 40 additions and 0 deletions.
diff --git a/runtime/fundamentals/node.md b/runtime/fundamentals/node.md
@@ -282,6 +282,24 @@ subclasses instead.
 
 - `__dirname` - use `import.meta.dirname` instead.
 
+## Node-API addons
+
+Deno supports [Node-API addons](https://nodejs.org/api/n-api.html) that are used
+by popular npm packages like [`esbuild`](https://www.npmjs.com/package/esbuild),
+[`npm:sqlite3`](https://www.npmjs.com/package/sqlite3) or
+[`npm:duckdb`](https://www.npmjs.com/package/duckdb).
+
+You can expect all packages that use public and documented Node-APIs to work.
+
+:::info
+
+Most packages using Node-API addons rely on npm "lifecycle scripts", like
+`postinstall`. While Deno supports them, they are not run by default due to
+security considerations. Read more in
+[`deno install` docs](/runtime/reference/cli/install/).
+
+:::
+
 ## Runtime permissions in Deno
 
 Consider the following simple [Express](https://expressjs.com/) server:

diff --git a/runtime/reference/cli/install.md b/runtime/reference/cli/install.md
@@ -174,6 +174,28 @@ example installation command to your repository:
 $ deno install -n awesome_cli https://example.com/awesome/cli.ts
 ```
 
+## Native Node.js addons
+
+A lot of popular packages npm packages like
+[`npm:sqlite3`](https://www.npmjs.com/package/sqlite3) or
+[`npm:duckdb`](https://www.npmjs.com/package/duckdb) depend on
+["lifecycle scripts"](https://docs.npmjs.com/cli/v10/using-npm/scripts#life-cycle-scripts),
+eg. `preinstall` or `postinstall` scripts. Most often running these scripts is
+required for a package to work correctly.
+
+Unlike npm, Deno does not run these scripts by default as they pose a potential
+security vulnerability.
+
+You can still run these scripts by passing the `--allow-scripts=<packages>` flag
+when running `deno install`:
+
+```shell
+deno install --allow-scripts=npm:sqlite3
+```
+
+_Install all dependencies and allow `npm:sqlite3` package to run its lifecycle
+scripts_.
+
 ## Uninstall
 
 You can uninstall dependencies or binary script with `deno uninstall` command: