12k
All articles

napi-rs で Node.js から Rust を呼び出す方法

Rustとnapi-rsでNode.jsネイティブアドオンを作成。関数やオブジェクト、非同期タスクを公開し、各環境向けのビルド済みバイナリをnpmで配布します。

OpenReplay Team
OpenReplay Team
napi-rs で Node.js から Rust を呼び出す方法

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-rsWebAssemblynode-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 への移行ガイドと照らし合わせて確認してください。

v2v3
napi.namenapi.binaryName
napi.triplesフラットな napi.targets 配列
napi.package.namenapi.packageName
napi create-npm-dirnapi 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 フィールドがマシンと一致するバイナリだけをインストールします。

インストール時の流れは次のとおりです。

  1. 利用者がルートパッケージをインストールします。
  2. パッケージマネージャーは、os、cpu、libc のいずれかのフィールドが一致しないオプショナルパッケージをスキップします。
  3. 一致したプラットフォーム用パッケージが、ビルド済みの .node ファイルをインストールします。
  4. 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 ツールチェーンをインストールする必要はありません。

次のステップは以下のとおりです。

  1. 最も遅い CPU バウンドな関数を src/lib.rs に移します。
  2. 実際の入力データを使って、JavaScript 版と性能を比較します。
  3. タグをプッシュし、自動生成された 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 関数を利用できる一方で、対応可能な最低バージョンも引き上げられます。選択したレベルより後に追加された関数は利用できません。

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.