Как вызывать Rust из Node.js с помощью napi-rs
Создавайте нативные модули Node.js на Rust с napi-rs. Экспортируйте функции, объекты и асинхронные задачи, а затем публикуйте готовые бинарные файлы в npm.
Чтобы вызывать Rust из Node.js с помощью napi-rs v3, создайте проект командой npx @napi-rs/cli new и пометьте Rust-функции атрибутом #[napi]. Затем выполните сборку и подключайте сгенерированный index.js через require, как любой другой модуль.
Возможно, цикл хеширования тормозит ваш event loop или вам нужна нативная библиотека, а возвращаться к борьбе с binding.gyp не хочется. Путь C++-аддонов через node-gyp работает, но в итоге на машине каждого пользователя должны быть Python и компилятор. В этом руководстве мы соберём работающий аддон на Rust, добавим функцию, возвращающую объект, и асинхронную функцию, а также разберём, как предсобранные бинарники доставляются пользователям через npm.
Ключевые выводы
- napi-rs компилирует Rust-код с аннотацией
#[napi]в бинарник.node, а также генерирует JavaScript-загрузчик (index.js) и объявления TypeScript (index.d.ts). - Для проекта на napi-rs v3 нужен Rust 1.88+, а для CLI — Node.js ^20.17.0, ^22.13.0 или 23.5.0+. Это требование CLI не связано с тем, какие версии Node поддерживает готовый аддон.
- Экспортируемой функции
async fnнужна фичаasyncилиtokio_rtв крейтеnapi. В сгенерированных типах такая функция возвращаетPromise. - Пакет napi-rs публикуется как корневой пакет плюс по одному опциональному пакету на каждую платформу, поэтому тем, кто его устанавливает, Rust не нужен.
Что такое napi-rs?
napi-rs — это фреймворк для создания нативных аддонов Node.js на Rust. Вы помечаете Rust-функции атрибутом #[napi], а сборка создаёт бинарник .node, JavaScript-загрузчик и объявления TypeScript, сгенерированные из сигнатур Rust.
napi-rs работает поверх Node-API — ABI-стабильного C-интерфейса Node для аддонов. Поскольку интерфейс ABI-стабилен, бинарник, скомпилированный под определённый уровень Node-API, как правило, загружается без пересборки и в более поздних релизах Node.js, которые по-прежнему предоставляют этот уровень. Вызывающий код импортирует аддон как обычный модуль и получает автодополнение с типами.
napi-rs или WebAssembly: что выбрать?
Выбирайте napi-rs, если код выполняется на сервере и ему нужны файловая система, нативные потоки или существующая нативная библиотека. Выбирайте Wasm, если тот же код должен работать и в браузере. napi-rs и Wasm не исключают друг друга: napi-rs умеет создавать опциональную WASI-сборку, и сгенерированный загрузчик может переключаться на неё как на запасной вариант.
| napi-rs | WebAssembly | C++ через node-gyp | |
|---|---|---|---|
| Файловая система и нативные потоки | Да | Ограниченно, зависит от хоста | Да |
| Линковка существующих нативных/C-библиотек | Да | Только если они скомпилированы в Wasm | Да |
| Нужны сборки под каждую платформу | Да, собираются в CI | Нет | Да, либо компиляция при установке |
| Опциональная WASI-сборка с фолбэком в загрузчике | Да | Неприменимо | Нет |
| Инструменты, нужные пользователю при установке | Никакие | Никакие | Часто Python и компилятор C++ |
| Генерация типов TS | Да | Зависит от инструментов | Нет |
Какой вариант быстрее, зависит от нагрузки, поэтому проводите бенчмарки на собственном горячем пути. Чтобы глубже разобраться с Wasm, почитайте о запуске высокопроизводительного кода с помощью Wasm и публикации пакетов WebAssembly в npm.
Создание проекта napi-rs
Чтобы создать проект napi-rs, запустите napi new через пакет @napi-rs/cli. В документации по началу работы перечислены требования: Rust 1.88 или новее, Node.js ^20.17.0, ^22.13.0 или 23.5.0+ для CLI, Git и компоновщик C. Версии Node, на которых будет работать готовый аддон, — отдельный вопрос: они определяются уровнем Node-API, под который он компилируется.
С шаблоном для Yarn:
yarn dlx @napi-rs/cli new hash-rs
cd hash-rs
yarn install
yarn build
С шаблоном для pnpm:
pnpm dlx @napi-rs/cli new hash-rs --package-manager pnpm
cd hash-rs
pnpm install
pnpm build
Поддерживаются только шаблоны для Yarn и pnpm. Интерактивные вопросы napi new касаются пути, имени пакета, уровня Node-API, целевых платформ, лицензии и того, нужно ли генерировать CI-воркфлоу. Сгенерированный проект содержит следующие файлы:
src/lib.rs: ваши экспортируемые Rust-функции.Cargo.toml: объявляетcrate-type = ["cdylib"]и крейты napi-rs v3. Оставьте версии, которые он прописал, и проверьте, что в нём указан выбранный вами уровень фич Node-API.build.rs: сгенерированный обязательный файл. Он вызываетnapi_build::setup()и должен оставаться в корне крейта, поэтому не редактируйте его.package.json: скриптbuildзапускаетnapi build --platform --release. Блокnapiсодержит вашу конфигурацию:
{
"napi": {
"binaryName": "hash-rs",
"targets": ["x86_64-apple-darwin", "aarch64-apple-darwin", "x86_64-unknown-linux-gnu", "x86_64-pc-windows-msvc"]
}
}
Значения полей берите из своего сгенерированного файла. Каждая сборка создаёт hash-rs.<platform>.node (например, hash-rs.darwin-arm64.node), а также index.js и index.d.ts.
Код, написанный для napi-rs v2, без изменений работать не будет. Если вы копировали его из старого туториала, сверьтесь с руководством по миграции с v2 на v3:
| v2 | v3 |
|---|---|
napi.name | napi.binaryName |
napi.triples | плоский массив napi.targets |
napi.package.name | napi.packageName |
napi create-npm-dir | napi create-npm-dirs |
JsObject, JsFunction | типизированные API v3; старые типы доступны через небезопасную фичу compat-mode |
Пишем ресурсоёмкую функцию на napi-rs
Чтобы экспортировать Rust-функцию, добавьте #[napi] к pub fn. Сначала подключите крейт для хеширования:
cargo add sha2
Затем замените содержимое src/lib.rs следующим кодом для 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()
}
Функция повторно хеширует собственный результат rounds раз. Именно такой плотный цикл блокирует поток JavaScript. Тип Rust String отображается в строку JS, а u32 — в число JS. Hex-кодирование реализовано вручную в цикле, поэтому не зависит от особенностей форматирования в конкретной версии sha2. Пересоберите проект командой yarn build. Функция появится в index.d.ts под именем в camelCase — sha256Rounds.
Вызовите её из CommonJS-файла, например try.cjs:
const { sha256Rounds } = require('./index.js')
console.log(sha256Rounds('hello', 1))
// 2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824
В пошаговом руководстве по простому пакету используется тот же цикл «собрать — подключить через require».
Возврат объектов и Promise
В napi-rs используйте #[napi(object)], чтобы возвращать обычные JS-объекты, и async fn, чтобы возвращать Promise. Согласно странице о концепции Object, все поля структуры с #[napi(object)] должны быть pub. Такую структуру можно использовать и как аргумент, и как возвращаемый тип, а её значение копируется при пересечении границы между Rust и JS.
Для асинхронных функций включите фичу async (или tokio_rt) в крейте napi и добавьте Tokio для файлового ввода-вывода:
[dependencies]
# keep the features the scaffold wrote, and append "async"
napi = { version = "3", features = ["async"] }
cargo add tokio --features fs
Добавьте следующий код в конец существующего src/lib.rs, где уже импортированы макрос napi и Sha256. Оператор ? после fs::read работает, потому что napi преобразует std::io::Error в собственный тип 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 })
}
Экспортируемая в napi-rs async fn выполняется в среде Tokio, которой управляет napi-rs. В сгенерированных типах hashFile возвращает Promise, который разрешается объектом FileHash, а Err из Rust превращается в отклонённый Promise. async fn хорошо подходит для подобных задач ввода-вывода. Для длительных чисто вычислительных задач в napi-rs есть AsyncTask, который выполняет работу вне основного потока.
Как опубликовать пакет napi-rs в npm?
Тем, кто устанавливает пакет napi-rs, Rust не нужен. Пакет napi-rs публикуется как небольшой корневой пакет плюс по одному опциональному пакету на каждую платформу. Пакетный менеджер устанавливает только тот бинарник, у которого поля package.json os, cpu и (где это актуально) libc соответствуют машине.
Вот что происходит при установке:
- Пользователь устанавливает корневой пакет.
- Пакетный менеджер пропускает опциональные пакеты, у которых поля
os,cpuилиlibcне совпадают с машиной. - Подходящий платформенный пакет устанавливает предсобранный файл
.node. index.jsнаходит этот бинарник и загружает его.
В napi.targets перечислены все платформы, для которых вы публикуете сборки. Однако локальный napi build компилирует только одну цель — вашу хост-платформу, если не передан --target. Остальные бинарники собирает сгенерированный воркфлоу GitHub Actions. Его задача публикации запускает napi create-npm-dirs, чтобы создать по одной директории npm-пакета на каждую цель, а затем перед публикацией перемещает каждый собранный артефакт в соответствующую директорию.
Каждой цели нужно собственное имя пакета, поэтому используйте скоуп 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"
}
}
Заключение
Теперь у вас есть аддон на Rust, который Node загружает как любой другой модуль, — со сгенерированными типами и предсобранными бинарниками под каждую платформу, так что пользователям никогда не придётся устанавливать тулчейн Rust. Следующий шаг — перенести самую медленную CPU-bound функцию в src/lib.rs, сравнить её с JavaScript-версией на реальных входных данных и запушить тег, чтобы сгенерированный CI собрал все целевые платформы.
Больше материалов о Rust — в статье Getting Started with Loco, Rust’s Answer to Rails.
Часто задаваемые вопросы
Чем async fn отличается от AsyncTask в napi-rs?
async fn выполняется в среде Tokio, которой управляет napi-rs, и подходит для асинхронного ввода-вывода. AsyncTask выполняет Task::compute в пуле потоков libuv и подходит для ограниченной по времени блокирующей или CPU-bound работы. Оба варианта возвращают в JavaScript Promise. Пул libuv используется совместно с операциями Node над файловой системой, DNS и криптографией, а AbortSignal может отменить AsyncTask только до начала шага compute.
Что происходит, если код на Rust паникует внутри функции napi-rs?
Без опции catch_unwind паника Rust, дошедшая до границы Node-API, аварийно завершает весь процесс Node.js вместо того, чтобы выбросить исключение. Пометьте функцию атрибутом #[napi(catch_unwind)], чтобы превратить панику в JavaScript Error, сформированный из payload паники. Для этого нужна стратегия паники по умолчанию — unwind; панику в режиме abort перехватить нельзя. Для ожидаемых ошибок лучше возвращайте Result: Err из синхронной функции выбрасывается как JavaScript Error.
Работают ли аддоны napi-rs в Bun и Deno?
Поддержка Bun предоставляется по принципу best effort. В репозитории napi-rs есть CI-задача для последней версии Bun, но сбои в Bun не блокируют релизы napi-rs, поэтому тестируйте свой аддон в Bun самостоятельно. Нативные аддоны Deno не входят в CI-матрицу исходного кода napi-rs, а документация napi-rs предостерегает от предположения, что Deno поддерживается только благодаря совместимости с Node-API. У опционального WASI-фолбэка также есть известные пробелы в обеих средах выполнения.
На какой уровень Node-API ориентировать аддон napi-rs?
Уровень Node-API определяет самую старую среду выполнения, в которой может загрузиться ваш аддон. Бинарник, собранный под уровень Node-API N, как правило, загружается в более поздних релизах Node.js, которые по-прежнему предоставляют уровень N, без пересборки под каждую мажорную версию Node. Более высокий уровень открывает доступ к новым функциям Node-API, но поднимает эту нижнюю границу. Функции, добавленные после выбранного вами уровня, недоступны.
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