12k
All articles

Rust aus Node.js aufrufen mit napi-rs

Erstellen Sie native Node.js-Add-ons mit Rust und napi-rs. Exportieren Sie Funktionen, Objekte und asynchrone Tasks und veröffentlichen Sie vorgefertigte Binärdateien auf npm.

OpenReplay Team
OpenReplay Team
Rust aus Node.js aufrufen mit napi-rs

Um Rust mit napi-rs v3 aus Node.js aufzurufen, legen Sie ein Projekt mit npx @napi-rs/cli new an, kennzeichnen Rust-Funktionen mit #[napi], führen den Build aus und binden die generierte index.js per require wie jedes andere Modul ein.

Vielleicht bremst eine Hashing-Schleife Ihre Event Loop aus, oder Sie benötigen eine native Bibliothek und haben keine Lust, sich wieder mit binding.gyp herumzuschlagen. Der Weg über ein C++-Add-on mit node-gyp funktioniert zwar, aber am Ende braucht jeder Rechner Ihrer Nutzer Python und einen Compiler. Dieser Leitfaden baut ein funktionsfähiges Rust-Add-on, ergänzt einen Objekt-Rückgabetyp sowie eine asynchrone Funktion und zeigt, wie vorkompilierte Binaries über npm zu den Nutzern gelangen.

Das Wichtigste in Kürze

  • napi-rs kompiliert mit #[napi] annotierten Rust-Code zu einem .node-Binary und generiert zusätzlich einen JavaScript-Loader (index.js) sowie TypeScript-Deklarationen (index.d.ts).
  • Ein napi-rs-v3-Projekt erfordert Rust 1.88+ sowie für die CLI Node.js ^20.17.0, ^22.13.0 oder 23.5.0+. Diese CLI-Anforderung ist unabhängig von den Node-Versionen, die das fertige Add-on unterstützt.
  • Eine exportierte async fn benötigt das Feature async oder tokio_rt im napi-Crate und wird mit einem Promise als Rückgabetyp typisiert.
  • Ein napi-rs-Paket wird als Root-Paket plus je ein optionales Paket pro Plattform ausgeliefert, sodass die Nutzer, die es installieren, niemals Rust benötigen.

Was ist napi-rs?

napi-rs ist ein Framework zum Erstellen nativer Node.js-Add-ons in Rust. Sie kennzeichnen Rust-Funktionen mit #[napi], und der Build erzeugt ein .node-Binary, einen JavaScript-Loader und TypeScript-Deklarationen, die aus den Rust-Signaturen generiert werden.

napi-rs baut auf Node-API auf, der ABI-stabilen C-Schnittstelle von Node für Add-ons. Da die Schnittstelle ABI-stabil ist, lässt sich ein gegen ein bestimmtes Node-API-Level kompiliertes Binary in der Regel ohne Neukompilierung in späteren Node.js-Releases laden, die dieses Level weiterhin bereitstellen. Aufrufer importieren das Add-on wie ein normales Modul und erhalten typisierte Autovervollständigung.

napi-rs vs. WebAssembly: Was sollten Sie verwenden?

Wählen Sie napi-rs, wenn Ihr Code auf dem Server läuft und Zugriff auf das Dateisystem, native Threads oder eine bestehende native Bibliothek benötigt. Wählen Sie Wasm, wenn derselbe Code auch im Browser laufen muss. napi-rs und Wasm schließen sich nicht gegenseitig aus: napi-rs kann einen optionalen WASI-Build erzeugen, auf den der generierte Loader zurückgreifen kann.

napi-rsWebAssemblynode-gyp C++
Dateisystem und native ThreadsJaEingeschränkt, abhängig vom HostJa
Einbindung bestehender nativer/C-BibliothekenJaNur wenn nach Wasm kompiliertJa
Plattformspezifische Builds erforderlichJa, in der CI gebautNeinJa, oder Kompilierung bei der Installation
Optionaler WASI-Build mit Loader-FallbackJaN/ANein
Toolchain, die der Nutzer bei der Installation benötigtKeineKeineHäufig Python und ein C++-Compiler
Generierte TS-TypenJaAbhängig vom ToolingNein

Welche Option schneller ist, hängt vom Workload ab – führen Sie also Benchmarks für Ihren eigenen Hot Path durch. Wenn Sie sich weiter mit Wasm beschäftigen möchten, lesen Sie mehr über das Ausführen von Hochleistungscode mit Wasm und das Veröffentlichen von WebAssembly-Paketen für npm.

Ein napi-rs-Projekt erstellen

Um ein napi-rs-Projekt zu erstellen, führen Sie napi new über das Paket @napi-rs/cli aus. Die Getting-Started-Dokumentation nennt die Voraussetzungen: Rust 1.88 oder neuer, Node.js ^20.17.0, ^22.13.0 oder 23.5.0+ für die CLI, Git und einen C-Linker. Auf welchen Node-Versionen Ihr fertiges Add-on läuft, ist eine separate Frage, die vom Node-API-Level abhängt, gegen das es kompiliert wird.

Mit dem Yarn-Template:

yarn dlx @napi-rs/cli new hash-rs
cd hash-rs
yarn install
yarn build

Mit dem pnpm-Template:

pnpm dlx @napi-rs/cli new hash-rs --package-manager pnpm
cd hash-rs
pnpm install
pnpm build

Es werden ausschließlich Yarn- und pnpm-Templates unterstützt. Die Abfragen von napi new erfassen Pfad, Paketnamen, Node-API-Level, Targets und Lizenz sowie die Frage, ob ein CI-Workflow generiert werden soll. Das Grundgerüst enthält folgende Dateien:

  • src/lib.rs: Ihre exportierten Rust-Funktionen.
  • Cargo.toml: deklariert crate-type = ["cdylib"] und die napi-rs-v3-Crates. Behalten Sie die eingetragenen Versionen bei und prüfen Sie, ob das gewählte Node-API-Feature-Level enthalten ist.
  • build.rs: generiert und erforderlich. Die Datei ruft napi_build::setup() auf und muss im Crate-Root verbleiben – bearbeiten Sie sie also nicht.
  • package.json: Das build-Skript führt napi build --platform --release aus. Der napi-Block enthält Ihre Konfiguration:
{
  "napi": {
    "binaryName": "hash-rs",
    "targets": ["x86_64-apple-darwin", "aarch64-apple-darwin", "x86_64-unknown-linux-gnu", "x86_64-pc-windows-msvc"]
  }
}

Übernehmen Sie die Feldwerte aus Ihrer generierten Datei. Jeder Build schreibt hash-rs.<platform>.node (zum Beispiel hash-rs.darwin-arm64.node) sowie index.js und index.d.ts.

Für napi-rs v2 geschriebener Code funktioniert nicht unverändert. Wenn Sie Code aus einem älteren Tutorial übernommen haben, gleichen Sie ihn mit dem Migrationsleitfaden von v2 zu v3 ab:

v2v3
napi.namenapi.binaryName
napi.triplesflaches napi.targets-Array
napi.package.namenapi.packageName
napi create-npm-dirnapi create-npm-dirs
JsObject, JsFunctiontypisierte v3-APIs; die alten Typen stehen hinter dem unsicheren Feature compat-mode

Eine CPU-intensive napi-rs-Funktion schreiben

Exportieren Sie eine Rust-Funktion, indem Sie #[napi] zu einer pub fn hinzufügen. Fügen Sie zunächst ein Hashing-Crate hinzu:

cargo add sha2

Ersetzen Sie anschließend src/lib.rs durch diesen napi-rs-v3-Code:

use napi_derive::napi;
use sha2::{Digest, Sha256};

/// Hash `input` with SHA-256, `rounds` times.
#[napi]
pub fn sha256_rounds(input: String, rounds: u32) -> String {
  let mut data = input.into_bytes();
  for _ in 0..rounds.max(1) {
    data = Sha256::digest(&data).to_vec();
  }
  data.iter().map(|b| format!("{:02x}", b)).collect()
}

Die Funktion hasht ihre eigene Ausgabe rounds-mal erneut – genau die Art enger Schleife, die einen JavaScript-Thread blockiert. Ein Rust-String wird auf einen JS-String abgebildet, ein u32 auf eine JS-Number. Die Hex-Kodierung erfolgt über eine manuelle Schleife und ist damit nicht von versionsspezifischer Formatierung in sha2 abhängig. Bauen Sie mit yarn build neu. Die Funktion erscheint in index.d.ts unter dem camelCase-Namen sha256Rounds.

Rufen Sie sie aus einer CommonJS-Datei wie try.cjs auf:

const { sha256Rounds } = require('./index.js')
console.log(sha256Rounds('hello', 1))
// 2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824

Die Anleitung für ein einfaches Paket verwendet denselben Ablauf aus Build und anschließendem require.

Objekte und Promises zurückgeben

Verwenden Sie in napi-rs #[napi(object)], um einfache JS-Objekte zurückzugeben, und async fn, um Promises zurückzugeben. Laut der Konzeptseite zu Objekten muss jedes Feld eines #[napi(object)]-Structs pub sein. Das Struct kann dann als Argument oder Rückgabetyp dienen, und sein Wert wird beim Überschreiten der Grenze kopiert.

Für asynchrone Funktionen aktivieren Sie das Feature async (oder tokio_rt) für napi und fügen Tokio für Datei-I/O hinzu:

[dependencies]
# keep the features the scaffold wrote, and append "async"
napi = { version = "3", features = ["async"] }
cargo add tokio --features fs

Hängen Sie Folgendes an die bestehende src/lib.rs an, die das napi-Makro und Sha256 bereits importiert. Das ? nach fs::read funktioniert, weil napi std::io::Error in seinen eigenen Error-Typ konvertiert.

use napi::bindgen_prelude::*;
use tokio::fs;

#[napi(object)]
pub struct FileHash {
  pub path: String,
  pub bytes: u32,
  pub sha256: String,
}

#[napi]
pub async fn hash_file(path: String) -> Result<FileHash> {
  let content = fs::read(&path).await?;
  let sha256: String = Sha256::digest(&content)
    .iter()
    .map(|b| format!("{:02x}", b))
    .collect();
  Ok(FileHash { bytes: content.len() as u32, path, sha256 })
}

Eine exportierte napi-rs-async fn läuft auf einer Tokio-Runtime, die von napi-rs verwaltet wird. In den generierten Typen gibt hashFile ein Promise zurück, das zu einem FileHash-Objekt aufgelöst wird, und ein Rust-Err wird zu einem abgelehnten (rejected) Promise. async fn eignet sich für I/O-Aufgaben wie diese. Für lang laufende, rein CPU-gebundene Jobs bietet napi-rs AsyncTask, das die Arbeit außerhalb des Haupt-Threads ausführt.

Wie veröffentlicht man ein napi-rs-Paket auf npm?

Wer ein napi-rs-Paket installiert, benötigt kein Rust. Ein napi-rs-Paket wird als kleines Root-Paket plus je ein optionales Paket pro Plattform ausgeliefert, und der Paketmanager installiert nur das Binary, dessen package.json-Felder os, cpu und (sofern relevant) libc zum Rechner passen.

Folgendes passiert bei der Installation:

  1. Der Nutzer installiert das Root-Paket.
  2. Der Paketmanager überspringt optionale Pakete, deren Felder os, cpu oder libc nicht passen.
  3. Das passende Plattformpaket installiert eine vorkompilierte .node-Datei.
  4. index.js findet dieses Binary und lädt es.

napi.targets listet alle Plattformen auf, die Sie ausliefern. Ein lokales napi build kompiliert jedoch nur ein einziges Target – Ihren Host –, sofern Sie nicht --target angeben. Die übrigen Binaries stammen aus dem generierten GitHub-Actions-Workflow. Dessen Publish-Job führt napi create-npm-dirs aus, um pro Target ein npm-Paketverzeichnis anzulegen, und verschiebt anschließend jedes gebaute Artefakt vor der Veröffentlichung in das passende Verzeichnis.

Jedes Target benötigt einen eigenen Paketnamen, verwenden Sie daher einen npm-Scope:

{
  "name": "@yourscope/hash-rs",
  "optionalDependencies": {
    "@yourscope/hash-rs-darwin-arm64": "1.0.0",
    "@yourscope/hash-rs-linux-x64-gnu": "1.0.0",
    "@yourscope/hash-rs-win32-x64-msvc": "1.0.0"
  }
}

Fazit

Sie verfügen jetzt über ein Rust-Add-on, das Node wie jedes andere Modul lädt – mit generierten Typen und vorkompilierten plattformspezifischen Binaries, sodass Ihre Nutzer nie eine Rust-Toolchain installieren müssen. Als Nächstes verlagern Sie Ihre langsamste CPU-gebundene Funktion in src/lib.rs, messen sie mit realen Eingaben gegen die JavaScript-Version und pushen ein Tag, damit die generierte CI alle Targets baut.

Weiteren Lesestoff zu Rust finden Sie in Getting Started with Loco, Rust’s Answer to Rails.

FAQs

Was ist der Unterschied zwischen async fn und AsyncTask in napi-rs?

Eine async fn läuft auf der von napi-rs verwalteten Tokio-Runtime und eignet sich für asynchrones I/O. AsyncTask führt Task::compute im libuv-Threadpool von Node aus und eignet sich für begrenzte blockierende oder CPU-gebundene Arbeit. Beide geben an JavaScript ein Promise zurück. Der libuv-Pool wird mit den Dateisystem-, DNS- und Krypto-Operationen von Node geteilt, und ein AbortSignal kann einen AsyncTask nur abbrechen, bevor dessen compute-Schritt beginnt.

Was passiert, wenn Rust-Code innerhalb einer napi-rs-Funktion einen Panic auslöst?

Ohne die Option catch_unwind bricht ein Rust-Panic, der die Node-API-Grenze erreicht, den gesamten Node.js-Prozess ab, statt eine Exception zu werfen. Kennzeichnen Sie die Funktion mit #[napi(catch_unwind)], um den Panic in einen JavaScript-Error umzuwandeln, der aus der Panic-Payload erzeugt wird. Dies setzt die standardmäßige Panic-Strategie unwind voraus und kann keinen abbrechenden (abort) Panic abfangen. Für erwartete Fehler geben Sie stattdessen ein Result zurück: Ein Err aus einer synchronen Funktion wird als JavaScript-Error geworfen.

Funktionieren napi-rs-Add-ons in Bun und Deno?

Die Unterstützung für Bun erfolgt nach dem Best-Effort-Prinzip. Das napi-rs-Repository führt einen CI-Job mit der neuesten Bun-Version aus, Fehler unter Bun blockieren jedoch keine napi-rs-Releases – testen Sie Ihr eigenes Add-on also in Bun. Native Add-ons unter Deno sind nicht Teil der CI-Matrix des napi-rs-Quellcodes, und die napi-rs-Dokumentation warnt davor, allein aufgrund der Node-API-Kompatibilität von Deno-Unterstützung auszugehen. Auch der optionale WASI-Fallback weist in beiden Runtimes bekannte Lücken auf.

Welches Node-API-Level sollte ein napi-rs-Add-on anvisieren?

Das Node-API-Level legt die älteste Runtime fest, auf der Ihr Add-on geladen werden kann. Ein gegen Node-API-Level N gebautes Binary lässt sich in der Regel auf späteren Node.js-Releases laden, die Level N weiterhin bereitstellen, ohne dass für jede Node-Major-Version neu gebaut werden muss. Ein höheres Level ermöglicht den Zugriff auf neuere Node-API-Funktionen, hebt aber diese Untergrenze an. Funktionen, die nach dem gewählten Level hinzugekommen sind, stehen nicht zur Verfügung.

DevTools for the frontend

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers.

Star on GitHub12k

We use cookies to improve your experience. By using our site, you accept cookies.