# ONNX Runtime JavaScript API

This directory contains multiple NPM projects:

- [onnxruntime-common](#onnxruntime-common)
- [onnxruntime-node](#onnxruntime-node)
- [onnxruntime-web](#onnxruntime-web)
- [onnxruntime-react-native](#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`.

## 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](https://www.onnxruntime.ai/docs/how-to/build.html#apis-and-language-bindings) 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](https://github.com/Microsoft/onnxjs).

### 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](https://www.onnxruntime.ai/docs/how-to/build.html#apis-and-language-bindings) 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:
   ```sh
   # 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

<!-- TODO: update this section for onnxruntime react-native -->