onnxruntime/js

ONNX Runtime JavaScript API

This directory contains multiple NPM projects:

• onnxruntime-common
• onnxruntime-node
• onnxruntime-web
• onnxruntime-react-native

Development

This folder contains a .vscode folder for Visual Studio Code workspace configs. Using VSCode to open this folder will allow code-formatting and linting features on typescript and C/C++ source code inside this folder. Following files are used for code-formatting and linting features for developers:

• .vscode/**
• package.json
• packages-lock.json
• .eslintrc.js
• .clang-format

Using VSCode:

1. in <ORT_ROOT>/js, run:

   npm ci

2. use VSCode to open folder <ORT_ROOT>/js
3. install VSCode extension if not installed yet:
   • Clang-Format
   • ESLint

To populate typescript type declarations, in each projects, run npm ci.

Run code formatter and linter manually

in <ORT_ROOT>/js, use npm run lint to run ESLint , and use npm run format to run clang-format.

onnxruntime-common

language: typescript

dependency:

folder: <ORT_ROOT>/js/common

This project is designed to include all "common" code, which are pure javascript that can run in both Node.js and browsers.

Requirements

Node.js v12+ (recommended v14+)

Build

Use following command in folder <ORT_ROOT>/js/common to install NPM packages, build typescript files and generate bundles:

npm ci

Distribution

It should be able to consumed by both from projects that uses NPM packages (through a Node.js folder structure of node_modules folder that generated by npm install onnxruntime-common) and from a CDN service that serves a .min.js bundle file.

Features

Following features are included in onnxruntime-common:

• InferenceSession interfaces
• Tensor/OnnxValue interfaces, implementation and a set of utility functions
• Backend interfaces and a set of functions for backend registration

onnxruntime-node

language: typescript/C++

dependency: onnxruntime-common, ONNXRuntime.dll

folder: <ORT_ROOT>/js/node

This project is designed to be used as a NPM package to enable Node.js users to consume ONNX Runtime via Node.js binding, in Node.js or any Node.js compatible environment.

Requirements

Node.js v12+ (recommended v14+)

Build

Build ONNX Runtime and Node.js binding

Follow instructions for building ONNX Runtime Node.js binding

Build Node.js binding only

Use following command in folder <ORT_ROOT>/js/node to install NPM packages and build typescript files:

npm ci

This will download the latest pre-built ONNX Runtime binaries for the current platform.

Distribution

It should be able to consumed by from projects that uses NPM packages (through a Node.js folder structure of node_modules folder that generated by npm install onnxruntime-node).

onnxruntime-web

language: typescript

dependency: onnxruntime-common, ONNXRuntime WebAssembly

folder: <ORT_ROOT>/js/web

This project is a library for running ONNX models on browsers. It is the successor of ONNX.js.

Requirements

Node.js v12+ (recommended v14+)

Build

1. Install NPM packages

   1. in <ORT_ROOT>/js/, run npm ci.
   2. in <ORT_ROOT>/js/common/, run npm ci.
   3. in <ORT_ROOT>/js/web/, run npm ci.

2. Follow instructions for building ONNX Runtime WebAssembly. (TODO: document is not ready. we are working on it.)

   in <ORT_ROOT>/, run either of the following commands to build WebAssembly:

   # In windows, use 'build' to replace './build.sh'
   
   # The following command build debug.
   ./build.sh --build_wasm
   
   # The following command build release.
   ./build.sh --config Release --build_wasm --skip_tests --disable_wasm_exception_catching --disable_rtti
   

   To build with multi-thread support, append flag --enable_wasm_threads to the command.

3. Copy following files from build output folder to <ORT_ROOT>/js/web/dist/:

   • ort-wasm.wasm
   • ort-wasm-threaded.wasm (if appliable)
   • ort-wasm-threaded.worker.js (if appliable)

4. Copy following files from build output folder to <ORT_ROOT>/js/web/lib/wasm/binding/:

   • ort-wasm.js
   • ort-wasm-threaded.js (if appliable)

5. Use following command in folder <ORT_ROOT>/js/web to build:

   npm run build
   

Distribution

It should be able to consumed by both from projects that uses NPM packages (through a Node.js folder structure of node_modules folder that generated by npm install onnxruntime-web) and from a CDN service that serves a .min.js file and one or multiple .wasm file(s).

onnxruntime-react-native

TBD