Environment:Microsoft Onnxruntime Nodejs Runtime Environment

Field	Value
sources	js/README.md, js/common/package.json, js/node/package.json, js/web/package.json
domains	javascript, nodejs, inference, webassembly
last_updated	2026-02-10

Overview

Node.js runtime environment for executing ONNX model inference using the onnxruntime-node and onnxruntime-web NPM packages with N-API and WebAssembly backends.

Description

The Node.js Runtime Environment enables ONNX model inference within JavaScript and TypeScript applications through three complementary NPM packages. The onnxruntime-common package provides the shared API surface (pure JavaScript, works in both Node.js and browser contexts). The onnxruntime-node package delivers native performance through a C++ addon compiled with N-API, giving Node.js applications direct access to the full ONNX Runtime C++ engine. The onnxruntime-web package targets browser and edge environments via a WebAssembly build of the runtime. All three packages require Node.js v20 or later. For development and building from source, Python 3.9+ is also needed as a build dependency. The TypeScript-based API mirrors the Python InferenceSession pattern: create a session from a model, construct input tensors, run inference, and extract output tensors.

Usage

Use this environment whenever you need to:

Run ONNX model inference in a Node.js server application or microservice.
Embed ONNX inference in an Electron desktop application.
Deploy ONNX models to browser-based applications via WebAssembly.
Build full-stack JavaScript/TypeScript applications with ML inference capabilities.

System Requirements

Requirement	Minimum	Recommended
Node.js	v20	v20 LTS
NPM	8+	10+
Python	3.9+ (dev only)	3.12 (dev only)
Operating System	Linux, Windows, macOS	Linux x86_64 or macOS arm64
RAM	1 GB	4 GB+ (model dependent)
Disk	100 MB	300 MB+

Dependencies

System Packages

For onnxruntime-node (native addon):

A C++ compiler toolchain is required only when building from source (GCC 9+, Clang 12+, or MSVC 2019+).
Pre-built binaries are included in the NPM package for supported platforms, so no compiler is needed for typical usage.

For onnxruntime-web (WebAssembly):

No additional system packages are required. The WASM binary is bundled.

NPM Packages

Package	Purpose	Backend
onnxruntime-common	Shared API types and interfaces	Pure JavaScript
onnxruntime-node	Native Node.js inference via N-API C++ binding	C++ (N-API)
onnxruntime-web	Browser and Node.js inference via WebAssembly	WebAssembly

Development Dependencies

Package	Purpose
typescript	TypeScript compilation
python (3.9+)	Build scripts and native addon compilation
node-gyp	Native addon build tool (for onnxruntime-node development)

Credentials

No credentials, API keys, or environment variables are required for basic usage of the Node.js ONNX Runtime packages.

Quick Install

For Node.js native inference:

npm install onnxruntime-node

For browser/WebAssembly inference:

npm install onnxruntime-web

For the shared common API only:

npm install onnxruntime-common

Verify installation:

node -e "const ort = require('onnxruntime-node'); console.log('onnxruntime-node loaded successfully');"

Code Evidence

Node.js version requirement (js/README.md:27)

# js/README.md:27
## Prerequisites
- Node.js v20+

The README specifies Node.js v20 as the minimum supported version for all JavaScript packages.

Python requirement for development (js/README.md:29)

# js/README.md:29
- Python 3.9+ (for building native addons)

Python is required as a build-time dependency when compiling the native N-API addon from source.

Package architecture (js/README.md:75, 119)

# js/README.md:75
# onnxruntime-node: Node.js binding using N-API (C++ addon)
# Provides native performance by directly calling the ONNX Runtime C++ library.

# js/README.md:119
# onnxruntime-web: WebAssembly-based runtime
# Compiles the ONNX Runtime C++ engine to WASM for browser deployment.

Common Errors

Error	Cause	Solution
`Error: Cannot find module 'onnxruntime-node'`	Package not installed	Run `npm install onnxruntime-node`
`Error: The module was compiled against a different Node.js version`	Native addon built for a different Node.js major version	Run `npm rebuild onnxruntime-node` or reinstall with current Node.js
`TypeError: ort.InferenceSession.create is not a function`	Using wrong import or outdated package version	Update to latest version: `npm install onnxruntime-node@latest`
`Error: ONNX model file not found`	Incorrect model file path	Verify the model path is correct and the file exists; use absolute paths in production
`RangeError: Invalid typed array length`	Input tensor dimensions do not match model expectations	Check model input shapes and ensure tensor data has the correct length
`node: --experimental-wasm-threads is not allowed`	Node.js version too old for WASM threading features	Upgrade to Node.js v20 or later

Compatibility Notes

Node.js v20: This is the minimum required version. Older LTS versions (v16, v18) are not supported due to N-API version requirements and WASM feature dependencies.
onnxruntime-node: Ships pre-built binaries for Linux x86_64, Linux arm64, Windows x86_64, macOS x86_64, and macOS arm64. Other platforms require building from source.
onnxruntime-web: Works in any modern browser supporting WebAssembly. For Node.js usage, it provides an alternative backend that does not require native compilation.
onnxruntime-common: Pure JavaScript with no native dependencies. Safe to use in any JavaScript runtime that supports ES2017+.
TypeScript: All packages include TypeScript type definitions. No additional @types packages are needed.
Electron: The onnxruntime-node package works in Electron applications but may require electron-rebuild to recompile the native addon.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment