12k
All articles

Cómo llamar a Rust desde Node.js con napi-rs

Crea complementos nativos para Node.js con Rust y napi-rs. Exporta funciones, objetos y tareas asíncronas, y publica binarios precompilados en npm.

OpenReplay Team
OpenReplay Team
Cómo llamar a Rust desde Node.js con napi-rs

Para llamar a Rust desde Node.js con napi-rs v3, genera la estructura del proyecto con npx @napi-rs/cli new, marca las funciones de Rust con #[napi], ejecuta la compilación y carga el index.js generado con require como cualquier otro módulo.

Quizá un bucle de hashing esté ralentizando tu event loop, o necesites una biblioteca nativa sin volver a pelearte con binding.gyp. La vía de los add-ons en C++ mediante node-gyp funciona, pero obliga a que la máquina de cada usuario tenga Python y un compilador. En esta guía se construye un add-on de Rust funcional, se añaden un tipo de retorno de objeto y una función asíncrona, y se muestra cómo llegan los binarios precompilados a los usuarios a través de npm.

Puntos clave

  • napi-rs compila el código Rust anotado con #[napi] en un binario .node y, además, genera un cargador de JavaScript (index.js) y declaraciones de TypeScript (index.d.ts).
  • Un proyecto con napi-rs v3 requiere Rust 1.88 o superior, además de Node.js ^20.17.0, ^22.13.0 o 23.5.0+ para la CLI. Este requisito de la CLI es independiente de las versiones de Node que admite el add-on final.
  • Una async fn exportada necesita la feature async o tokio_rt en el crate napi, y su tipo de retorno es una Promise.
  • Un paquete de napi-rs se distribuye como un paquete raíz más un paquete opcional por plataforma, de modo que quienes lo instalan nunca necesitan Rust.

¿Qué es napi-rs?

napi-rs es un framework para crear add-ons nativos de Node.js en Rust. Marcas las funciones de Rust con #[napi] y la compilación genera un binario .node, un cargador de JavaScript y declaraciones de TypeScript derivadas de las firmas de Rust.

napi-rs se apoya en Node-API, la interfaz C de Node para add-ons con ABI estable. Gracias a esa estabilidad de ABI, un binario compilado contra un nivel de Node-API puede, por lo general, cargarse sin recompilar en versiones posteriores de Node.js que sigan ofreciendo ese nivel. Quien lo usa importa el add-on como un módulo normal y obtiene autocompletado tipado.

napi-rs vs. WebAssembly: ¿cuál conviene usar?

Elige napi-rs cuando tu código se ejecute en el servidor y necesite el sistema de archivos, hilos nativos o una biblioteca nativa existente. Elige Wasm cuando ese mismo código también deba ejecutarse en el navegador. napi-rs y Wasm no son excluyentes: napi-rs puede generar una compilación WASI opcional, y el cargador generado puede recurrir a ella como alternativa.

napi-rsWebAssemblynode-gyp C++
Sistema de archivos e hilos nativosSíLimitado, depende del hostSí
Enlaza bibliotecas nativas/C existentesSíSolo si se compilan a WasmSí
Requiere compilaciones por plataformaSí, se compilan en CINoSí, o se compilan durante la instalación
Compilación WASI opcional con fallback en el cargadorSíN/ANo
Toolchain que necesita el usuario al instalarNingunaNingunaA menudo Python y un compilador de C++
Tipos de TS generadosSíDepende de las herramientasNo

Qué opción es más rápida depende de la carga de trabajo, así que haz benchmarks de tu propia ruta crítica. Para profundizar en Wasm, consulta cómo ejecutar código de alto rendimiento con Wasm y cómo publicar paquetes de WebAssembly en npm.

Crear un proyecto con napi-rs

Para crear un proyecto con napi-rs, ejecuta napi new a través del paquete @napi-rs/cli. La documentación de primeros pasos enumera los requisitos previos: Rust 1.88 o superior, Node.js ^20.17.0, ^22.13.0 o 23.5.0+ para la CLI, Git y un linker de C. Las versiones de Node en las que se ejecuta el add-on final son otra cuestión, determinada por el nivel de Node-API contra el que se compila.

Con la plantilla de Yarn:

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

Con la plantilla de pnpm:

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

Solo se admiten las plantillas de Yarn y pnpm. Las preguntas de napi new solicitan la ruta, el nombre del paquete, el nivel de Node-API, los targets, la licencia y si se debe generar un workflow de CI. La estructura generada contiene estos archivos:

  • src/lib.rs: las funciones de Rust que exportas.
  • Cargo.toml: declara crate-type = ["cdylib"] y los crates de napi-rs v3. Conserva las versiones que escribe y comprueba que refleje el nivel de features de Node-API que elegiste.
  • build.rs: generado y obligatorio. Llama a napi_build::setup() y debe permanecer en la raíz del crate, así que no lo modifiques.
  • package.json: el script build ejecuta napi build --platform --release. El bloque napi contiene tu configuración:
{
  "napi": {
    "binaryName": "hash-rs",
    "targets": ["x86_64-apple-darwin", "aarch64-apple-darwin", "x86_64-unknown-linux-gnu", "x86_64-pc-windows-msvc"]
  }
}

Copia los valores de los campos de tu archivo generado. Cada compilación genera hash-rs.<platform>.node (por ejemplo, hash-rs.darwin-arm64.node), junto con index.js e index.d.ts.

El código escrito para napi-rs v2 no funciona sin cambios. Si lo copiaste de un tutorial antiguo, revísalo con la guía de migración de v2 a v3:

v2v3
napi.namenapi.binaryName
napi.triplesarray plano napi.targets
napi.package.namenapi.packageName
napi create-npm-dirnapi create-npm-dirs
JsObject, JsFunctionAPIs tipadas de v3; los tipos antiguos quedan detrás de la feature insegura compat-mode

Escribir una función de napi-rs con uso intensivo de CPU

Para exportar una función de Rust, añade #[napi] a una pub fn. Primero, agrega un crate de hashing:

cargo add sha2

Después, reemplaza src/lib.rs con este código de 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 función vuelve a aplicar el hash sobre su propia salida rounds veces, justo el tipo de bucle intensivo que bloquea un hilo de JavaScript. Un String de Rust se corresponde con un string de JS, y u32, con un number de JS. La codificación hexadecimal se hace con un bucle manual, de modo que no depende de un formato específico de una versión de sha2. Vuelve a compilar con yarn build. La función aparece en index.d.ts con el nombre en camelCase sha256Rounds.

Llámala desde un archivo CommonJS como try.cjs:

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

El tutorial del paquete simple sigue el mismo ciclo de compilar y luego hacer require.

Devolver objetos y Promises

En napi-rs, usa #[napi(object)] para devolver objetos JS planos y async fn para devolver Promises. Según la página de conceptos sobre Object, todos los campos de un struct #[napi(object)] deben ser pub. Así, el struct puede usarse como argumento o como tipo de retorno, y su valor se copia al cruzar la frontera entre ambos lenguajes.

Para las funciones asíncronas, activa la feature async (o tokio_rt) en napi y añade Tokio para la E/S de archivos:

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

Añade lo siguiente al src/lib.rs existente, que ya importa la macro napi y Sha256. El ? después de fs::read funciona porque napi convierte std::io::Error en su propio tipo 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 })
}

Una async fn exportada de napi-rs se ejecuta en un runtime de Tokio que gestiona napi-rs. En los tipos generados, hashFile devuelve una Promise que se resuelve con un objeto FileHash, y un Err de Rust se convierte en una Promise rechazada. async fn es adecuada para trabajo de E/S como este. Para tareas largas puramente de CPU, napi-rs ofrece AsyncTask, que ejecuta el trabajo fuera del hilo principal.

¿Cómo se publica un paquete de napi-rs en npm?

Quienes instalan un paquete de napi-rs no necesitan Rust. Un paquete de napi-rs se distribuye como un pequeño paquete raíz más un paquete opcional por plataforma, y el gestor de paquetes instala únicamente el binario cuyos campos de package.json os, cpu y (cuando corresponde) libc coinciden con la máquina.

Esto es lo que ocurre durante la instalación:

  1. El usuario instala el paquete raíz.
  2. El gestor de paquetes omite los paquetes opcionales cuyos campos os, cpu o libc no coinciden.
  3. El paquete de la plataforma correspondiente instala un archivo .node precompilado.
  4. index.js localiza ese binario y lo carga.

napi.targets enumera todas las plataformas que distribuyes. Sin embargo, un napi build local compila un único target: tu host, salvo que pases --target. Los demás binarios los genera el workflow de GitHub Actions creado automáticamente. Su job de publicación ejecuta napi create-npm-dirs para crear un directorio de paquete npm por target y, a continuación, mueve cada artefacto compilado al directorio correspondiente antes de publicar.

Cada target necesita su propio nombre de paquete, así que usa un scope de 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"
  }
}

Conclusión

Ahora tienes un add-on de Rust que Node carga como cualquier otro módulo, con tipos generados y binarios precompilados por plataforma, de modo que tus usuarios nunca tienen que instalar una toolchain de Rust. Como siguiente paso, traslada a src/lib.rs tu función limitada por CPU más lenta, compárala con la versión en JavaScript usando datos reales y publica un tag para que el CI generado compile todos los targets.

Para seguir leyendo sobre Rust, consulta Getting Started with Loco, Rust’s Answer to Rails.

Preguntas frecuentes

¿Cuál es la diferencia entre async fn y AsyncTask en napi-rs?

Una async fn se ejecuta en el runtime de Tokio que gestiona napi-rs y es adecuada para E/S asíncrona. AsyncTask ejecuta Task::compute en el thread pool de libuv de Node y es adecuada para trabajo bloqueante acotado o limitado por CPU. Ambas devuelven una Promise a JavaScript. El pool de libuv se comparte con las operaciones de sistema de archivos, DNS y criptografía de Node, y un AbortSignal solo puede cancelar una AsyncTask antes de que comience su paso compute.

¿Qué ocurre cuando el código de Rust entra en pánico dentro de una función de napi-rs?

Sin la opción catch_unwind, un panic de Rust que alcanza la frontera de Node-API aborta todo el proceso de Node.js en lugar de lanzar una excepción. Marca la función con #[napi(catch_unwind)] para convertir el panic en un Error de JavaScript construido a partir del payload del panic. Esto requiere la estrategia de panic predeterminada (unwind) y no puede capturar un panic que aborta. Para los fallos previstos, devuelve Result: un Err de una función síncrona se lanza como un Error de JavaScript.

¿Funcionan los add-ons de napi-rs en Bun y Deno?

El soporte para Bun es de tipo best effort. El repositorio de napi-rs ejecuta un job de CI con la última versión de Bun, pero los fallos en Bun no bloquean las versiones de napi-rs, así que prueba tu propio add-on en Bun. Los add-ons nativos de Deno no están en la matriz de CI del código fuente de napi-rs, y la documentación de napi-rs advierte que no se debe dar por hecho el soporte de Deno solo por la compatibilidad con Node-API. El fallback WASI opcional también presenta limitaciones conocidas en ambos runtimes.

¿A qué nivel de Node-API debería apuntar un add-on de napi-rs?

El nivel de Node-API determina el runtime más antiguo en el que puede cargarse tu add-on. Un binario compilado contra el nivel N de Node-API puede, por lo general, cargarse en versiones posteriores de Node.js que sigan ofreciendo el nivel N, sin necesidad de recompilar para cada versión mayor de Node. Un nivel más alto da acceso a funciones más recientes de Node-API, pero eleva ese mínimo. Las funciones añadidas después del nivel elegido no están 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.