From c5a9af7dd89693c3f6f00aff6181ffcecc9121d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bartek=20Iwa=C5=84czuk?= Date: Mon, 30 Sep 2024 12:19:13 +0100 Subject: [PATCH] Node-API addons (#920) --- runtime/fundamentals/node.md | 18 ++++++++++++++++++ runtime/reference/cli/install.md | 22 ++++++++++++++++++++++ 2 files changed, 40 insertions(+) diff --git a/runtime/fundamentals/node.md b/runtime/fundamentals/node.md index 800e58a1e..1dcf4c7e6 100644 --- 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 index e080d8e43..6d11e3ebf 100644 --- 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=` 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: