SIGN IN SIGN UP
denoland / deno UNCLAIMED

A modern runtime for JavaScript and TypeScript.

0 0 16 Rust

fix(runtime): suggest N-API alternatives for legacy V8/nan addons (#34695)

Native addons built against the legacy Node.js `NODE_MODULE` / `nan` ABI
(such as `better-sqlite3`) link against V8 C++ internals that Deno does
not expose. Since #34683, Deno rejects them with a clear
`UnsupportedLegacyAddon` error instead of crashing — but the error
offered no guidance on what to do next.

This adds an actionable fix-suggestion in `runtime/fmt_errors.rs`
(`get_suggestions_for_terminal_errors`) that fires on the legacy-addon
error and points users at Node-API alternatives:

- **`better-sqlite3`** is special-cased (the error message includes the
`.node` path) to recommend the built-in `node:sqlite` module and the
`npm:libsql` / `npm:@libsql/client` packages (the latter expose a
`better-sqlite3`-compatible API).
- Any other legacy addon gets a generic hint to switch to / migrate the
addon to Node-API.

### Why not actually run `better-sqlite3`?

Running these addons would require Deno to expose V8's C++ API and
node:: helper symbols and to be ABI-compatible with the V8 the addon was
built against. Deno's `rusty_v8` is several major V8 versions ahead of
the V8 that prebuilt `better-sqlite3` binaries target (Node 20, V8
11.x), so exported symbols would not be ABI-compatible. That is a large,
separate effort; this PR improves the failure UX in the meantime,
directly addressing the most-reported package in the issue.

### Test

`tests/specs/run/node_addon_legacy_suggestion/` exercises both the
`better-sqlite3`-specific and the generic suggestion by throwing the
error string (no native build needed, mirroring the existing
`node_addon_bindings_suggestion` spec test).

```
cargo test --test specs -- run::node_addon_legacy_suggestion
```

Refs #26034

Closes denoland/divybot#408

Co-authored-by: divybot <divybot@users.noreply.github.com>
Co-authored-by: Divy Srivastava <me@littledivy.com>
E
em committed
c9e800da2a70e137248fce2a3a8761f55af71672
Parent: 619742f
Committed by GitHub <noreply@github.com> on 6/2/2026, 6:59:35 AM