12k
All articles

Comment appeler du code Rust depuis Node.js avec napi-rs

Créez des modules natifs Node.js avec Rust et napi-rs. Exportez fonctions, objets et tâches asynchrones, puis publiez des binaires précompilés sur npm.

OpenReplay Team
OpenReplay Team
Comment appeler du code Rust depuis Node.js avec napi-rs

Pour appeler du code Rust depuis Node.js avec napi-rs v3, générez la structure d’un projet avec npx @napi-rs/cli new, annotez vos fonctions Rust avec #[napi], lancez le build, puis chargez le fichier index.js généré avec require, comme n’importe quel autre module.

Une boucle de hachage ralentit peut-être votre event loop, ou bien vous avez besoin d’une bibliothèque native sans vouloir revivre les déboires de binding.gyp. La voie des add-ons C++ via node-gyp fonctionne, mais chaque machine utilisateur finit par exiger Python et un compilateur. Ce guide construit un add-on Rust fonctionnel, y ajoute un type de retour objet et une fonction asynchrone, puis montre comment les binaires précompilés parviennent aux utilisateurs via npm.

Points clés

  • napi-rs compile le code Rust annoté avec #[napi] en un binaire .node, et génère également un chargeur JavaScript (index.js) ainsi que des déclarations TypeScript (index.d.ts).
  • Un projet napi-rs v3 nécessite Rust 1.88+, ainsi que Node.js ^20.17.0, ^22.13.0 ou 23.5.0+ pour la CLI. Cette exigence propre à la CLI est indépendante des versions de Node prises en charge par l’add-on final.
  • Une async fn exportée nécessite la feature async ou tokio_rt sur la crate napi, et son type de retour est une Promise.
  • Un package napi-rs est distribué sous la forme d’un package racine accompagné d’un package optionnel par plateforme : les utilisateurs qui l’installent n’ont donc jamais besoin de Rust.

Qu’est-ce que napi-rs ?

napi-rs est un framework permettant de développer des add-ons natifs Node.js en Rust. Vous annotez vos fonctions Rust avec #[napi], et le build produit un binaire .node, un chargeur JavaScript et des déclarations TypeScript générées à partir des signatures Rust.

napi-rs repose sur Node-API, l’interface C de Node destinée aux add-ons, dont l’ABI est stable. Grâce à cette stabilité d’ABI, un binaire compilé pour un niveau Node-API donné peut généralement être chargé, sans recompilation, par les versions ultérieures de Node.js qui fournissent toujours ce niveau. Les appelants importent l’add-on comme un module classique et bénéficient d’une autocomplétion typée.

napi-rs ou WebAssembly : que choisir ?

Choisissez napi-rs lorsque votre code s’exécute côté serveur et a besoin du système de fichiers, de threads natifs ou d’une bibliothèque native existante. Choisissez Wasm lorsque le même code doit également s’exécuter dans le navigateur. napi-rs et Wasm ne s’excluent pas mutuellement : napi-rs peut produire un build WASI optionnel, sur lequel le chargeur généré peut se rabattre.

napi-rsWebAssemblyC++ via node-gyp
Système de fichiers et threads natifsOuiLimité, dépend de l’hôteOui
Liaison avec des bibliothèques natives/C existantesOuiUniquement si compilées en WasmOui
Builds par plateforme nécessairesOui, réalisés en CINonOui, ou compilation à l’installation
Build WASI optionnel avec repli dans le chargeurOuiSans objetNon
Chaîne d’outils requise chez l’utilisateur à l’installationAucuneAucuneSouvent Python et un compilateur C++
Types TS générésOuiSelon l’outillageNon

L’option la plus rapide dépend de la charge de travail : mesurez donc les performances de votre propre chemin critique. Pour approfondir Wasm, consultez nos articles sur l’exécution de code haute performance avec Wasm et sur la publication de packages WebAssembly sur npm.

Créer un projet napi-rs

Pour créer un projet napi-rs, exécutez napi new via le package @napi-rs/cli. La documentation de démarrage liste les prérequis : Rust 1.88 ou version ultérieure, Node.js ^20.17.0, ^22.13.0 ou 23.5.0+ pour la CLI, Git et un éditeur de liens C. Les versions de Node sur lesquelles votre add-on final s’exécute constituent une question distincte, qui dépend du niveau Node-API ciblé à la compilation.

Avec le template Yarn :

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

Avec le template pnpm :

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

Seuls les templates Yarn et pnpm sont pris en charge. Les questions posées par napi new portent sur le chemin, le nom du package, le niveau Node-API, les cibles, la licence et la génération éventuelle d’un workflow de CI. Le projet généré contient les fichiers suivants :

  • src/lib.rs : vos fonctions Rust exportées.
  • Cargo.toml : déclare crate-type = ["cdylib"] et les crates napi-rs v3. Conservez les versions qui y sont inscrites, et vérifiez-y le niveau de feature Node-API que vous avez choisi.
  • build.rs : généré et indispensable. Il appelle napi_build::setup() et doit rester à la racine de la crate ; ne le modifiez pas.
  • package.json : le script build exécute napi build --platform --release. Le bloc napi contient votre configuration :
{
  "napi": {
    "binaryName": "hash-rs",
    "targets": ["x86_64-apple-darwin", "aarch64-apple-darwin", "x86_64-unknown-linux-gnu", "x86_64-pc-windows-msvc"]
  }
}

Reprenez les valeurs de ces champs depuis votre fichier généré. Chaque build produit hash-rs.<platform>.node (par exemple hash-rs.darwin-arm64.node), ainsi que index.js et index.d.ts.

Le code écrit pour napi-rs v2 ne fonctionnera pas tel quel. Si vous l’avez repris d’un ancien tutoriel, comparez-le au guide de migration de la v2 vers la v3 :

v2v3
napi.namenapi.binaryName
napi.triplestableau plat napi.targets
napi.package.namenapi.packageName
napi create-npm-dirnapi create-npm-dirs
JsObject, JsFunctionAPI typées de la v3 ; les anciens types sont accessibles via la feature non sûre compat-mode

Écrire une fonction napi-rs gourmande en CPU

Pour exporter une fonction Rust, ajoutez #[napi] à une pub fn. Commencez par ajouter une crate de hachage :

cargo add sha2

Remplacez ensuite le contenu de src/lib.rs par ce code napi-rs v3 :

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()
}

La fonction rehache sa propre sortie rounds fois : c’est typiquement le genre de boucle serrée qui bloque un thread JavaScript. Le type Rust String correspond à une chaîne JS, et u32 à un nombre JS. L’encodage hexadécimal est réalisé par une boucle manuelle, afin de ne pas dépendre d’un formatage propre à une version de sha2. Relancez le build avec yarn build. La fonction apparaît dans index.d.ts sous le nom en camelCase sha256Rounds.

Appelez-la depuis un fichier CommonJS, par exemple try.cjs :

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

Le tutoriel sur la création d’un package simple suit la même boucle : build, puis require.

Renvoyer des objets et des Promises

Avec napi-rs, utilisez #[napi(object)] pour renvoyer des objets JS simples, et async fn pour renvoyer des Promises. D’après la page consacrée au concept d’objet, tous les champs d’une struct #[napi(object)] doivent être pub. La struct peut alors servir d’argument ou de type de retour, et sa valeur est copiée lorsqu’elle franchit la frontière entre Rust et JavaScript.

Pour les fonctions asynchrones, activez la feature async (ou tokio_rt) sur napi, et ajoutez Tokio pour les E/S fichiers :

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

Ajoutez le code suivant à la fin du fichier src/lib.rs existant, qui importe déjà la macro napi et Sha256. L’opérateur ? après fs::read fonctionne parce que napi convertit std::io::Error en son propre type Error.

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 })
}

Une async fn exportée par napi-rs s’exécute sur un runtime Tokio géré par napi-rs. Dans les types générés, hashFile renvoie une Promise résolue avec un objet FileHash, et une Err Rust se traduit par une Promise rejetée. async fn convient à ce type de travail orienté E/S. Pour les longues tâches purement CPU, napi-rs fournit AsyncTask, qui exécute le travail en dehors du thread principal.

Comment publier un package napi-rs sur npm ?

Les utilisateurs qui installent un package napi-rs n’ont pas besoin de Rust. Un package napi-rs est distribué sous la forme d’un package racine léger accompagné d’un package optionnel par plateforme, et le gestionnaire de paquets n’installe que le binaire dont les champs package.json os, cpu et, le cas échéant, libc correspondent à la machine.

Voici ce qui se passe à l’installation :

  1. L’utilisateur installe le package racine.
  2. Le gestionnaire de paquets ignore les packages optionnels dont les champs os, cpu ou libc ne correspondent pas.
  3. Le package de la plateforme correspondante installe un fichier .node précompilé.
  4. index.js localise ce binaire et le charge.

napi.targets liste toutes les plateformes que vous distribuez. Un napi build local ne compile toutefois qu’une seule cible : votre machine hôte, sauf si vous passez --target. Les autres binaires sont produits par le workflow GitHub Actions généré. Son job de publication exécute napi create-npm-dirs pour créer un répertoire de package npm par cible, puis déplace chaque artefact compilé dans le répertoire correspondant avant la publication.

Chaque cible nécessite son propre nom de package : utilisez donc un scope npm :

{
  "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"
  }
}

Conclusion

Vous disposez désormais d’un add-on Rust que Node charge comme n’importe quel autre module, avec des types générés et des binaires précompilés pour chaque plateforme : vos utilisateurs n’ont jamais à installer de chaîne d’outils Rust. Prochaine étape : déplacez votre fonction CPU-bound la plus lente dans src/lib.rs, comparez-la à la version JavaScript sur des données réelles, puis poussez un tag pour laisser la CI générée compiler toutes les cibles.

Pour aller plus loin avec Rust, consultez Getting Started with Loco, Rust’s Answer to Rails.

FAQ

Quelle est la différence entre async fn et AsyncTask dans napi-rs ?

Une async fn s'exécute sur le runtime Tokio géré par napi-rs et convient aux E/S asynchrones. AsyncTask exécute Task::compute sur le pool de threads libuv de Node et convient aux travaux bloquants de durée limitée ou CPU-bound. Les deux renvoient une Promise à JavaScript. Le pool libuv est partagé avec les opérations de système de fichiers, de DNS et de cryptographie de Node, et un AbortSignal ne peut annuler une AsyncTask qu'avant le démarrage de son étape compute.

Que se passe-t-il lorsque du code Rust panique dans une fonction napi-rs ?

Sans l'option catch_unwind, une panique Rust qui atteint la frontière Node-API interrompt l'ensemble du processus Node.js au lieu de lever une exception. Annotez la fonction avec #[napi(catch_unwind)] pour convertir la panique en Error JavaScript construite à partir du payload de la panique. Cela nécessite la stratégie de panique par défaut (unwind), et ne permet pas d'intercepter une panique en mode abort. Pour les échecs prévisibles, renvoyez plutôt un Result : une Err renvoyée par une fonction synchrone est levée sous forme d'Error JavaScript.

Les add-ons napi-rs fonctionnent-ils avec Bun et Deno ?

La prise en charge de Bun est assurée au mieux (best effort). Le dépôt napi-rs exécute un job de CI sur la dernière version de Bun, mais les échecs sous Bun ne bloquent pas les releases de napi-rs : testez donc votre propre add-on avec Bun. Les add-ons natifs pour Deno ne figurent pas dans la matrice de CI du code source de napi-rs, et la documentation de napi-rs déconseille de présumer une compatibilité avec Deno sur la seule base de la compatibilité Node-API. Le repli WASI optionnel présente également des lacunes connues dans ces deux runtimes.

Quel niveau Node-API un add-on napi-rs doit-il cibler ?

Le niveau Node-API détermine le runtime le plus ancien sur lequel votre add-on peut être chargé. Un binaire compilé pour le niveau Node-API N peut généralement être chargé par les versions ultérieures de Node.js qui fournissent toujours le niveau N, sans recompilation pour chaque version majeure de Node. Un niveau plus élevé donne accès à des fonctions Node-API plus récentes, mais relève ce seuil minimal. Les fonctions ajoutées après le niveau choisi ne sont pas disponibles.

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.