# @adhdev/ghostty-vt-node > Native Node binding for libghostty-vt Latest version **1.0.46** (published 2026-08-14) · AGPL-3.0-or-later license · 0 weekly downloads ## Install ```sh npm install @adhdev/ghostty-vt-node pnpm add @adhdev/ghostty-vt-node yarn add @adhdev/ghostty-vt-node bun add @adhdev/ghostty-vt-node ``` ## Health **Score 60/100 (C)** — status: active. Positive: has types; no vulnerabilities; recently updated; high maintenance score. Warnings: low downloads; no esm support; large bundle. ## Facts | | | |---|---| | Version | 1.0.46 | | Published | 2026-08-14 | | First published | 2026-04-02 | | Weekly downloads | 0 | | License | AGPL-3.0-or-later | | TypeScript types | bundled | | Module format | CommonJS | | Dependencies | 1 | | Unpacked size | 64.1 MB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 97 | | Author | vilmire | | Maintainers | vilmire | ## Links - npm: https://www.npmjs.com/package/@adhdev/ghostty-vt-node - Repository: https://github.com/vilmire/adhdev - Homepage: https://github.com/vilmire/adhdev#readme - Issues: https://github.com/vilmire/adhdev/issues - npm.io page: https://npm.io/package/@adhdev/ghostty-vt-node ## Dependencies (1) - [node-addon-api](https://npm.io/package/node-addon-api.md) ^8.7.0 ## Recent versions - 1.0.46 (latest) — 2026-08-14 - 1.0.0 — 2026-07-18 - 0.8.51 — 2026-04-13 - 0.8.2 — 2026-04-05 - 0.7.43 — 2026-04-04 - 0.7.35 — 2026-04-02 - 0.7.33 — 2026-04-02 - 0.7.31 — 2026-04-02 ## README # @adhdev/ghostty-vt-node Native Node binding for `libghostty-vt` — exposes a headless ghostty virtual terminal (`createTerminal`) used by daemon-core's `GhosttyVtTerminalBackend`. ## ABI portability (read this first) The addon is a pure **Node-API (N-API)** binding (it exports `napi_register_module_v1`). N-API is **ABI-stable across Node major versions**, so a single compiled `.node` loads on every Node runtime that supports the N-API version it targets — **independent of `process.versions.modules`** (`NODE_MODULE_VERSION`, a.k.a. the "ABI" number: 115 ≈ node20, 127 ≈ node22, 137 ≈ node24). Practically: you do **not** need a separate native build per Node version. The per-`nodeNNN` directory names under `prebuilt/` are an addressing convenience, not a hard requirement — the binaries are byte-identical per platform/arch. ### Why prebuilts are committed `prebuilt/` is committed to git (only the `*-node137` triplet per platform) so that worktree/CI clones load the binding **without a build toolchain**. A clone with no committed prebuilt would fall through to compiling from source (cmake-js + zig + a `libghostty` fetch); when that toolchain is absent the loader throws `ghostty-vt binding unavailable`, which previously surfaced as an environment blocker on node24/ABI137 runners. Shipped triplets: ``` prebuilt/darwin-arm64-node137/ # macOS Apple Silicon prebuilt/linux-x64-node137/ # Linux x64 prebuilt/win32-x64-node137/ # Windows x64 ``` ## Loader resolution order (`index.js`) 1. `ADHDEV_GHOSTTY_VT_PREBUILT_DIR//ghostty_vt_node.node` (explicit override) 2. `ADHDEV_GHOSTTY_VT_PREBUILT_DIR/ghostty_vt_node.node` 3. `build/Release` or `build/Debug` (a local compile) 4. `prebuilt//ghostty_vt_node.node` 5. **N-API fallback** — any `prebuilt/--node*/ghostty_vt_node.node` for the same platform/arch (this is what makes a brand-new ABI such as a future node26 work without shipping a new directory). If nothing loads, the thrown error **names the running triplet and the list of available prebuilt triplets**, so an environment-blocker report is precise: ``` Unable to load @adhdev/ghostty-vt-node native binding for running triplet "darwin-arm64-node137". Available prebuilt triplets: [darwin-arm64-node137, linux-x64-node137, win32-x64-node137]. ... ``` ## Producing / refreshing a prebuilt Build on the **target platform/arch** (cross-builds are not wired here) with the toolchain present (`cmake`, a C/C++ compiler, and `zig` for `libghostty`; set `ZIG_EXECUTABLE` if zig is not on `PATH`): ```bash # Build for the running platform-arch and emit it into prebuilt// ADHDEV_GHOSTTY_VT_EMIT_PREBUILT=1 npm run build -w oss/packages/ghostty-vt-node # Then keep the node137-named dir (per ABI-portability) and commit it: # git add oss/packages/ghostty-vt-node/prebuilt/--node137/ ``` Because the output is ABI-portable, you only need to build **once per platform/arch**; rename/keep the directory as the `node137` triplet and the runtime fallback covers all other Node versions on that platform. - macOS arm64 and Linux x64 can be produced on the corresponding native runner. - Windows x64 must be built on a Windows runner (MSVC; see the `if(MSVC)` block in `CMakeLists.txt` for the required dynamic-CRT link flags). ## Skipping the native build Set `ADHDEV_SKIP_GHOSTTY_VT_BUILD=1` to skip compilation when no prebuilt matches (useful in environments that intentionally run without the terminal backend). --- _Source: https://npm.io/package/@adhdev/ghostty-vt-node · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._