napi-rs で Node.js から Rust を呼び出す方法
Rustとnapi-rsでNode.jsネイティブアドオンを作成。関数やオブジェクト、非同期タスクを公開し、各環境向けのビルド済みバイナリをnpmで配布します。
napi-rs v3 で Node.js から Rust を呼び出す手順は次のとおりです。npx @napi-rs/cli new でプロジェクトのひな形を作成し、Rust の関数に #[napi] を付けてビルドします。あとは生成された index.js を、通常のモジュールと同じように require するだけです。
ハッシュ計算のループがイベントループを詰まらせている、あるいはネイティブライブラリを使いたいが binding.gyp との格闘には戻りたくない、という状況もあるでしょう。node-gyp を使った C++ アドオンでも実現はできます。ただしその場合、利用者全員のマシンに Python とコンパイラが必要になります。本ガイドでは、動作する Rust アドオンを構築し、オブジェクトを返す関数と非同期関数を追加します。さらに、ビルド済みバイナリが npm を通じて利用者に届く仕組みも解説します。
重要なポイント
- napi-rs は、
#[napi]アノテーションを付けた Rust コードを.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をエクスポートするには、napiクレートでasyncまたはtokio_rtフィーチャーを有効にする必要があります。この関数はPromiseを返す型として定義されます。- napi-rs パッケージは、ルートパッケージとプラットフォームごとのオプショナルパッケージで構成されます。そのため、インストールする側で Rust を用意する必要はありません。
napi-rs とは
napi-rs は、Rust で Node.js のネイティブアドオンを開発するためのフレームワークです。Rust の関数に #[napi] を付けてビルドすると、.node バイナリ、JavaScript ローダー、そして Rust のシグネチャから生成された TypeScript の型宣言が出力されます。
napi-rs は、Node のアドオン向け C インターフェースである Node-API の上に構築されています。Node-API は ABI 安定です。そのため、ある Node-API レベル向けにコンパイルしたバイナリは、そのレベルを引き続き提供している新しい Node.js リリースでも、一般に再ビルドなしで読み込めます。呼び出し側は通常のモジュールと同じようにアドオンをインポートでき、型付きの補完も利用できます。
napi-rs と WebAssembly、どちらを使うべきか
コードがサーバー上で動作し、ファイルシステム、ネイティブスレッド、既存のネイティブライブラリのいずれかを必要とする場合は napi-rs を選びます。同じコードをブラウザでも動かす必要がある場合は Wasm を選びます。なお、両者は二者択一ではありません。napi-rs はオプションで WASI ビルドを生成でき、生成されるローダーはそれをフォールバックとして使えます。
| napi-rs | WebAssembly | node-gyp C++ | |
|---|---|---|---|
| ファイルシステムとネイティブスレッド | 可 | 制限あり(ホスト環境に依存) | 可 |
| 既存のネイティブ/C ライブラリのリンク | 可 | Wasm にコンパイルした場合のみ | 可 |
| プラットフォームごとのビルド | 必要(CI でビルド) | 不要 | 必要(またはインストール時にコンパイル) |
| ローダーによるフォールバック付きのオプション WASI ビルド | 可 | 該当なし | 不可 |
| インストール時に利用者が必要とするツールチェーン | なし | なし | 多くの場合 Python と C++ コンパイラ |
| TypeScript の型の自動生成 | あり | ツールによる | なし |
どちらが高速かはワークロードによって異なります。自分のホットパスで実際にベンチマークを取ってください。Wasm についてさらに知りたい場合は、Wasm で高性能なコードを実行すると WebAssembly パッケージを npm に公開するを参照してください。
napi-rs プロジェクトを作成する
napi-rs プロジェクトを作成するには、@napi-rs/cli パッケージ経由で napi new を実行します。Getting Started のドキュメントには、前提条件として次のものが挙げられています。
- Rust 1.88 以上
- CLI 用の Node.js ^20.17.0、^22.13.0、または 23.5.0 以上
- 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 | 型付きの v3 API(旧型は unsafe な compat-mode フィーチャーでのみ利用可能) |
CPU 負荷の高い napi-rs 関数を書く
Rust の関数をエクスポートするには、pub fn に #[napi] を付けます。まずハッシュ用のクレートを追加します。
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 の数値にマッピングされます。 - 16 進エンコード: 手書きのループで実装しているため、
sha2のバージョン固有のフォーマット機能に依存しません。
yarn build で再ビルドすると、index.d.ts にキャメルケースの名前 sha256Rounds で関数が現れます。
try.cjs などの CommonJS ファイルから呼び出してみます。
const { sha256Rounds } = require('./index.js')
console.log(sha256Rounds('hello', 1))
// 2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824
シンプルなパッケージのチュートリアルでも、同じ「ビルドしてから require する」という流れを採用しています。
オブジェクトと Promise を返す
napi-rs でプレーンな JS オブジェクトを返すには #[napi(object)] を、Promise を返すには async fn を使います。Object のコンセプトページによると、#[napi(object)] 構造体のフィールドはすべて pub でなければなりません。この条件を満たせば、構造体を引数としても戻り値としても使えます。その値は境界をまたぐ際にコピーされます。
非同期関数を使うには、napi で async フィーチャー(または tokio_rt)を有効にします。また、ファイル I/O 用に 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 は、napi-rs が管理する Tokio ランタイム上で実行されます。生成される型では、hashFile は FileHash オブジェクトで解決される Promise を返します。Rust の Err は、reject された Promise になります。
async fn は、このような I/O 処理に適しています。長時間かかる純粋な CPU 処理には、napi-rs が提供する AsyncTask を使うと、処理をメインスレッドの外で実行できます。
napi-rs パッケージを npm に公開するには
napi-rs パッケージをインストールする利用者は、Rust を必要としません。napi-rs パッケージは、小さなルートパッケージと、プラットフォームごとのオプショナルパッケージで構成されます。パッケージマネージャーは、os、cpu、および(該当する場合は)libc の package.json フィールドがマシンと一致するバイナリだけをインストールします。
インストール時の流れは次のとおりです。
- 利用者がルートパッケージをインストールします。
- パッケージマネージャーは、
os、cpu、libcのいずれかのフィールドが一致しないオプショナルパッケージをスキップします。 - 一致したプラットフォーム用パッケージが、ビルド済みの
.nodeファイルをインストールします。 index.jsがそのバイナリを見つけて読み込みます。
napi.targets には、配布するすべてのプラットフォームを列挙します。ただし、ローカルでの napi build がコンパイルするターゲットは 1 つだけです。--target を指定しない限り、ホスト環境向けのみがビルドされます。他のバイナリは、自動生成される GitHub Actions ワークフローで作成します。このワークフローの publish ジョブは、まず 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"
}
}
まとめ
これで、Node が通常のモジュールと同じように読み込める Rust アドオンが完成しました。型は自動生成され、ビルド済みのバイナリがプラットフォームごとに用意されるため、利用者が Rust ツールチェーンをインストールする必要はありません。
次のステップは以下のとおりです。
- 最も遅い CPU バウンドな関数を
src/lib.rsに移します。 - 実際の入力データを使って、JavaScript 版と性能を比較します。
- タグをプッシュし、自動生成された CI にすべてのターゲットをビルドさせます。
Rust についてさらに読みたい方は、Loco 入門:Rails に対する Rust からの回答をご覧ください。
よくある質問
napi-rs における async fn と AsyncTask の違いは何ですか?
async fn は napi-rs が管理する Tokio ランタイム上で実行され、非同期 I/O に適しています。AsyncTask は Task::compute を Node の libuv スレッドプール上で実行し、実行時間が限られたブロッキング処理や CPU バウンドな処理に適しています。どちらも JavaScript には Promise を返します。なお、libuv のスレッドプールは Node のファイルシステム、DNS、暗号処理と共有されています。また、AbortSignal で AsyncTask をキャンセルできるのは、compute ステップが開始される前に限られます。
napi-rs の関数内で Rust コードがパニックするとどうなりますか?
catch_unwind オプションを指定していない場合、Node-API の境界まで到達した Rust のパニックは、例外をスローするのではなく Node.js プロセス全体を異常終了させます。関数に #[napi(catch_unwind)] を付けると、パニックはそのペイロードから生成された JavaScript の Error に変換されます。これにはデフォルトの unwind パニック戦略が必要で、abort するパニックは捕捉できません。想定内の失敗には、代わりに Result を返してください。同期関数から返された Err は、JavaScript の Error としてスローされます。
napi-rs アドオンは Bun や Deno で動作しますか?
Bun のサポートはベストエフォートです。napi-rs リポジトリでは最新の Bun を使った CI ジョブが実行されていますが、Bun での失敗は napi-rs のリリースを妨げません。そのため、自分のアドオンが Bun で動くかは自分でテストしてください。Deno のネイティブアドオンは napi-rs ソースの CI マトリクスに含まれていません。napi-rs のドキュメントでも、Node-API 互換性だけを根拠に Deno での動作を前提にしないよう注意喚起されています。また、オプションの WASI フォールバックにも、両ランタイムで既知の制約があります。
napi-rs アドオンはどの Node-API レベルを対象にすべきですか?
Node-API レベルによって、アドオンを読み込める最も古いランタイムが決まります。Node-API レベル N 向けにビルドしたバイナリは、一般にレベル N を引き続き提供している新しい Node.js リリースで読み込めます。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