Principle:Microsoft Onnxruntime Nodejs Runtime Setup
| Field | Value |
|---|---|
| Principle Name | Nodejs_Runtime_Setup |
| Overview | Installation and configuration of the ONNX Runtime JavaScript package for Node.js inference applications. |
| Category | External Tool Doc |
| Domains | ML_Inference, JavaScript_Integration |
| Source Repository | microsoft/onnxruntime |
| Last Updated | 2026-02-10 |
Overview
Installation and configuration of the ONNX Runtime JavaScript package for Node.js inference applications. The onnxruntime-node npm package provides Node.js bindings to the native ONNX Runtime C++ library, enabling high-performance machine learning inference within JavaScript server applications.
Description
The onnxruntime-node npm package provides Node.js bindings to the native ONNX Runtime C++ library. Installation via npm automatically downloads platform-specific native binaries for the current operating system and architecture (Windows, Linux, macOS on x64 and ARM64). The package depends on onnxruntime-common which provides the shared TypeScript API surface used across all ONNX Runtime JavaScript targets (Node.js, Web, React Native).
The package is designed to be consumed via the standard Node.js module system. Once installed, the native shared library (.so, .dll, or .dylib) is placed in the node_modules directory alongside the JavaScript bindings. This enables seamless integration without manual native library management.
Key aspects of the runtime setup include:
- Platform-specific binaries: The npm install process automatically downloads the correct native ONNX Runtime shared library for the host platform.
- onnxruntime-common dependency: Provides the shared TypeScript type definitions and API surface (InferenceSession, Tensor, etc.) that are common across all ONNX Runtime JavaScript packages.
- Node.js v20+ requirement: The package requires Node.js version 20 or higher for compatibility with the N-API native addon layer.
- Package location: The JavaScript source lives under <ORT_ROOT>/js/node in the repository, and the common API under <ORT_ROOT>/js/common.
Theoretical Basis
Node.js native addons (N-API) bridge JavaScript and the C++ ONNX Runtime core, providing near-native performance while maintaining JavaScript's developer experience. N-API is an ABI-stable interface that allows native C/C++ code to be called from JavaScript without recompilation across Node.js versions. This architecture means that the computationally intensive ONNX model loading and inference execution happens in native code, while the developer interacts with a familiar JavaScript/TypeScript API.
The binding pattern follows the common approach for performance-critical Node.js libraries: a thin JavaScript/TypeScript wrapper around a native C++ addon. The onnxruntime-common package defines the TypeScript interfaces, while onnxruntime-node provides the N-API implementation that delegates to the ONNX Runtime C++ shared library.
Usage
To set up the ONNX Runtime Node.js environment:
- Ensure Node.js v20 or higher is installed.
- In your Node.js project directory, run npm install onnxruntime-node.
- Import the package using require('onnxruntime-node') or ES module import syntax.
- The package is ready to create inference sessions and run models.
The setup is a prerequisite for all subsequent Node.js inference operations including session creation, tensor construction, and model execution.