Como chamar Rust a partir do Node.js com napi-rs
Crie complementos nativos para Node.js com Rust e napi-rs. Exporte funções, objetos e tarefas assíncronas e publique binários pré-compilados no npm.
Para chamar Rust a partir do Node.js com o napi-rs v3, crie a estrutura do projeto com npx @napi-rs/cli new, marque as funções Rust com #[napi], execute o build e faça o require do index.js gerado como faria com qualquer outro módulo.
Talvez um loop de hashing esteja deixando seu event loop lento, ou você precise de uma biblioteca nativa e não queira voltar a brigar com o binding.gyp. O caminho dos add-ons em C++ via node-gyp funciona, mas acaba exigindo Python e um compilador na máquina de cada usuário. Este guia constrói um add-on em Rust funcional, adiciona um tipo de retorno em objeto e uma função assíncrona, e mostra como os binários pré-compilados chegam aos usuários pelo npm.
Principais conclusões
- O napi-rs compila código Rust anotado com
#[napi]em um binário.nodee também gera um loader JavaScript (index.js) e declarações TypeScript (index.d.ts). - Um projeto napi-rs v3 precisa do Rust 1.88+, além do Node.js ^20.17.0, ^22.13.0 ou 23.5.0+ para a CLI. Esse requisito da CLI é independente das versões do Node suportadas pelo add-on final.
- Um
async fnexportado precisa da featureasyncoutokio_rtno cratenapie é tipado como retornando umaPromise. - Um pacote napi-rs é distribuído como um pacote raiz mais um pacote opcional por plataforma, então quem o instala nunca precisa do Rust.
O que é o napi-rs?
O napi-rs é um framework para criar add-ons nativos para Node.js em Rust. Você marca as funções Rust com #[napi], e o build gera um binário .node, um loader JavaScript e declarações TypeScript geradas a partir das assinaturas em Rust.
O napi-rs funciona sobre o Node-API, a interface C com ABI estável do Node para add-ons. Como a interface tem ABI estável, um binário compilado para um determinado nível do Node-API geralmente pode ser carregado, sem recompilação, em versões posteriores do Node.js que ainda ofereçam esse nível. Quem usa o add-on o importa como um módulo comum e conta com autocomplete tipado.
napi-rs vs. WebAssembly: qual usar?
Escolha o napi-rs quando seu código roda no servidor e precisa do sistema de arquivos, de threads nativas ou de uma biblioteca nativa já existente. Escolha Wasm quando o mesmo código também precisar rodar no navegador. napi-rs e Wasm não são mutuamente exclusivos: o napi-rs pode gerar um build WASI opcional, e o loader gerado pode recorrer a ele como fallback.
| napi-rs | WebAssembly | C++ com node-gyp | |
|---|---|---|---|
| Sistema de arquivos e threads nativas | Sim | Limitado, depende do host | Sim |
| Vincula bibliotecas nativas/C existentes | Sim | Somente se compiladas para Wasm | Sim |
| Exige builds por plataforma | Sim, gerados no CI | Não | Sim, ou compilados na instalação |
| Build WASI opcional com fallback no loader | Sim | N/A | Não |
| Toolchain necessária ao usuário na instalação | Nenhuma | Nenhuma | Frequentemente Python e um compilador C++ |
| Tipos TS gerados | Sim | Depende do ferramental | Não |
Qual opção é mais rápida depende da carga de trabalho, então faça benchmarks do seu próprio hot path. Para se aprofundar em Wasm, leia sobre como executar código de alto desempenho com Wasm e como publicar pacotes WebAssembly no npm.
Crie um projeto napi-rs
Para criar um projeto napi-rs, execute o napi new por meio do pacote @napi-rs/cli. A documentação de primeiros passos lista os pré-requisitos: Rust 1.88 ou mais recente, Node.js ^20.17.0, ^22.13.0 ou 23.5.0+ para a CLI, Git e um linker C. As versões do Node em que o add-on final roda são outra questão, determinada pelo nível do Node-API para o qual ele é compilado.
Com o template do Yarn:
yarn dlx @napi-rs/cli new hash-rs
cd hash-rs
yarn install
yarn build
Com o template do pnpm:
pnpm dlx @napi-rs/cli new hash-rs --package-manager pnpm
cd hash-rs
pnpm install
pnpm build
Apenas os templates do Yarn e do pnpm são suportados. Os prompts do napi new pedem o caminho, o nome do pacote, o nível do Node-API, os targets, a licença e se deve ser gerado um workflow de CI. A estrutura gerada contém estes arquivos:
src/lib.rs: suas funções Rust exportadas.Cargo.toml: declaracrate-type = ["cdylib"]e os crates do napi-rs v3. Mantenha as versões que ele define e verifique nele o nível de features do Node-API que você escolheu.build.rs: gerado e obrigatório. Ele chamanapi_build::setup()e deve permanecer na raiz do crate, então não o edite.package.json: o scriptbuildexecutanapi build --platform --release. O bloconapicontém sua configuração:
{
"napi": {
"binaryName": "hash-rs",
"targets": ["x86_64-apple-darwin", "aarch64-apple-darwin", "x86_64-unknown-linux-gnu", "x86_64-pc-windows-msvc"]
}
}
Copie os valores dos campos do arquivo gerado no seu projeto. Cada build gera hash-rs.<platform>.node (por exemplo, hash-rs.darwin-arm64.node), junto com index.js e index.d.ts.
Código escrito para o napi-rs v2 não funciona sem alterações. Se você copiou de um tutorial antigo, confira-o com o guia de migração da v2 para a v3:
| v2 | v3 |
|---|---|
napi.name | napi.binaryName |
napi.triples | array simples napi.targets |
napi.package.name | napi.packageName |
napi create-npm-dir | napi create-npm-dirs |
JsObject, JsFunction | APIs tipadas da v3; os tipos antigos ficam atrás da feature insegura compat-mode |
Escreva uma função napi-rs com uso intensivo de CPU
Exporte uma função Rust adicionando #[napi] a uma pub fn. Primeiro, adicione um crate de hashing:
cargo add sha2
Em seguida, substitua o src/lib.rs por este código do 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()
}
A função aplica o hash novamente sobre a própria saída rounds vezes, o tipo de loop intenso que bloqueia uma thread JavaScript. O String do Rust é mapeado para uma string JS, e o u32, para um number JS. A codificação hexadecimal é feita com um loop manual, então não depende de formatação específica de versão do sha2. Recompile com yarn build. A função aparece no index.d.ts com o nome em camelCase sha256Rounds.
Chame-a a partir de um arquivo CommonJS, como try.cjs:
const { sha256Rounds } = require('./index.js')
console.log(sha256Rounds('hello', 1))
// 2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824
O passo a passo de pacote simples usa o mesmo ciclo de build seguido de require.
Retorne objetos e Promises
No napi-rs, use #[napi(object)] para retornar objetos JS simples e async fn para retornar Promises. De acordo com a página de conceito de Object, todos os campos de uma struct #[napi(object)] devem ser pub. A struct pode então ser usada como argumento ou tipo de retorno, e seu valor é copiado ao atravessar a fronteira entre Rust e JavaScript.
Para funções assíncronas, ative a feature async (ou tokio_rt) no napi e adicione o Tokio para I/O de arquivos:
[dependencies]
# keep the features the scaffold wrote, and append "async"
napi = { version = "3", features = ["async"] }
cargo add tokio --features fs
Acrescente o código a seguir ao src/lib.rs existente, que já importa a macro napi e o Sha256. O ? depois de fs::read funciona porque o napi converte std::io::Error no seu próprio 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 })
}
Um async fn exportado pelo napi-rs roda em um runtime Tokio gerenciado pelo próprio napi-rs. Nos tipos gerados, hashFile retorna uma Promise que resolve para um objeto FileHash, e um Err do Rust se torna uma Promise rejeitada. O async fn é adequado para trabalho de I/O como este. Para tarefas longas puramente de CPU, o napi-rs oferece o AsyncTask, que executa o trabalho fora da thread principal.
Como publicar um pacote napi-rs no npm?
Quem instala um pacote napi-rs não precisa do Rust. Um pacote napi-rs é distribuído como um pequeno pacote raiz mais um pacote opcional por plataforma, e o gerenciador de pacotes instala apenas o binário cujos campos do package.json os, cpu e (quando aplicável) libc correspondem à máquina.
Veja o que acontece no momento da instalação:
- O usuário instala o pacote raiz.
- O gerenciador de pacotes ignora os pacotes opcionais cujos campos
os,cpuoulibcnão correspondem. - O pacote da plataforma correspondente instala um arquivo
.nodepré-compilado. - O
index.jsencontra esse binário e o carrega.
O napi.targets lista todas as plataformas que você distribui. No entanto, um napi build local compila apenas um target: o do seu host, a menos que você passe --target. Os demais binários vêm do workflow do GitHub Actions gerado. O job de publicação dele executa napi create-npm-dirs para criar um diretório de pacote npm por target e, em seguida, move cada artefato compilado para o diretório correspondente antes de publicar.
Cada target precisa do próprio nome de pacote, então use um escopo do 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"
}
}
Conclusão
Agora você tem um add-on em Rust que o Node carrega como qualquer outro módulo, com tipos gerados e binários pré-compilados por plataforma, de modo que seus usuários nunca precisam instalar uma toolchain Rust. Como próximo passo, mova sua função limitada por CPU mais lenta para o src/lib.rs, compare-a com a versão em JavaScript usando entradas reais e envie uma tag para que o CI gerado compile todos os targets.
Para mais leituras sobre Rust, confira Getting Started with Loco, Rust’s Answer to Rails.
Perguntas frequentes
Qual é a diferença entre async fn e AsyncTask no napi-rs?
Um async fn roda no runtime Tokio gerenciado pelo napi-rs e é adequado para I/O assíncrono. O AsyncTask executa Task::compute no pool de threads da libuv do Node e é adequado para trabalho bloqueante limitado ou com uso intensivo de CPU. Ambos retornam uma Promise para o JavaScript. O pool da libuv é compartilhado com as operações de sistema de arquivos, DNS e criptografia do Node, e um AbortSignal só consegue cancelar um AsyncTask antes do início da etapa compute.
O que acontece quando o código Rust entra em panic dentro de uma função napi-rs?
Sem a opção catch_unwind, um panic do Rust que alcança a fronteira do Node-API aborta todo o processo do Node.js em vez de lançar uma exceção. Marque a função com #[napi(catch_unwind)] para transformar o panic em um Error do JavaScript construído a partir do payload do panic. Isso requer a estratégia de panic padrão, unwind, e não consegue capturar um panic do tipo abort. Para falhas esperadas, retorne Result: um Err de uma função síncrona é lançado como um Error do JavaScript.
Os add-ons napi-rs funcionam no Bun e no Deno?
O suporte ao Bun é feito com base no melhor esforço. O repositório do napi-rs executa um job de CI com a versão mais recente do Bun, mas falhas no Bun não bloqueiam os releases do napi-rs, então teste seu próprio add-on no Bun. Add-ons nativos para Deno não fazem parte da matriz de CI do código-fonte do napi-rs, e a documentação do napi-rs alerta para não presumir suporte ao Deno apenas com base na compatibilidade com o Node-API. O fallback WASI opcional também tem lacunas conhecidas nos dois runtimes.
Qual nível do Node-API um add-on napi-rs deve ter como alvo?
O nível do Node-API define o runtime mais antigo em que seu add-on pode ser carregado. Um binário compilado para o nível N do Node-API geralmente pode ser carregado em versões posteriores do Node.js que ainda ofereçam o nível N, sem recompilação a cada versão major do Node. Um nível mais alto dá acesso a funções mais recentes do Node-API, mas eleva esse piso. Funções adicionadas depois do nível escolhido não ficam disponíveis.
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