Pluggable inference providers

.github/workflows/publish.yml

@@ -11,17 +11,21 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Install pnpm
-        uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1  # v4
+        uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
       # Setup .npmrc file to publish to npm
-      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f  # v6
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6
         with:
           node-version: "24.10.0"
           registry-url: "https://registry.npmjs.org"
           cache: "pnpm"
       - run: pnpm install --frozen-lockfile
       - run: pnpm build
+      - name: Publish ONNX provider to npm
+        run: pnpm --filter @huggingface/transformers-onnx publish --access public --no-git-checks
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
       - name: Publish to npm
         run: pnpm --filter @huggingface/transformers publish --access public --no-git-checks
         env:

.gitignore

@@ -14,3 +14,5 @@ packages/*/types
 
 # Do not track coverage reports
 packages/*/coverage
+
+*.local.*

CONTRIBUTING.md

@@ -27,10 +27,10 @@ helped you, or simply ⭐️ the repository to say thank you.
 
 There are several ways you can contribute to 🤗 Transformers.js:
 
-* Fix outstanding issues with the existing code.
-* Submit issues related to bugs or desired new features.
-* Implement new models.
-* Contribute to the examples or to the documentation.
+- Fix outstanding issues with the existing code.
+- Submit issues related to bugs or desired new features.
+- Implement new models.
+- Contribute to the examples or to the documentation.
 
 ## Fixing outstanding issues
 
@@ -55,9 +55,9 @@ To create a new issue, please [use one of the templates](https://github.com/hugg
 
 If there is a new feature you'd like to see in 🤗 Transformers.js, please open an issue and describe:
 
-1. What is the *motivation* behind this feature? Is it related to a problem or frustration with the library? Is it a feature related to something you need for a project? Is it something you worked on and think it could benefit the community? Whatever it is, we'd love to hear about it!
+1. What is the _motivation_ behind this feature? Is it related to a problem or frustration with the library? Is it a feature related to something you need for a project? Is it something you worked on and think it could benefit the community? Whatever it is, we'd love to hear about it!
 2. Describe your requested feature in as much detail as possible. The more you can tell us about it, the better we'll be able to help you.
-3. Provide a *code snippet* that demonstrates the feature's usage.
+3. Provide a _code snippet_ that demonstrates the feature's usage.
 4. If the feature is related to a paper, please include a link.
 
 If your issue is well written we're already 80% of the way there by the time you create it.
@@ -98,7 +98,7 @@ Every model file exports a base class and one or more task heads. For the vast m
 **Decoder-only LLM:**
 
 ```js
-import { PreTrainedModel } from '../modeling_utils.js';
+import { PreTrainedModel } from "../modeling_utils.js";
 
 export class MyModelPreTrainedModel extends PreTrainedModel {}
 export class MyModelModel extends MyModelPreTrainedModel {}
@@ -108,22 +108,25 @@ export class MyModelForCausalLM extends MyModelPreTrainedModel {}
 **Encoder-only model:**
 
 ```js
-import { PreTrainedModel } from '../modeling_utils.js';
-import { MaskedLMOutput, SequenceClassifierOutput } from '../modeling_outputs.js';
+import { PreTrainedModel } from "../modeling_utils.js";
+import {
+  MaskedLMOutput,
+  SequenceClassifierOutput,
+} from "../modeling_outputs.js";
 
 export class MyModelPreTrainedModel extends PreTrainedModel {}
 export class MyModelModel extends MyModelPreTrainedModel {}
 
 export class MyModelForMaskedLM extends MyModelPreTrainedModel {
-    async _call(model_inputs) {
-        return new MaskedLMOutput(await super._call(model_inputs));
-    }
+  async _call(model_inputs) {
+    return new MaskedLMOutput(await super._call(model_inputs));
+  }
 }
 
 export class MyModelForSequenceClassification extends MyModelPreTrainedModel {
-    async _call(model_inputs) {
-        return new SequenceClassifierOutput(await super._call(model_inputs));
-    }
+  async _call(model_inputs) {
+    return new SequenceClassifierOutput(await super._call(model_inputs));
+  }
 }
 ```
 
@@ -133,11 +136,11 @@ Only add the task heads the model actually supports. The available output classe
 
 Most models reuse an existing tokenizer (e.g. all Llama-family models use `LlamaTokenizer`). Only create a new one if the model genuinely needs custom tokenization or preprocessing logic.
 
-| What | File | Barrel to update |
-| --- | --- | --- |
-| Custom tokenizer | `src/models/<name>/tokenization_<name>.js` | `src/models/tokenizers.js` |
-| Custom image processor | `src/models/<name>/image_processing_<name>.js` | `src/models/image_processors.js` |
-| Custom multimodal processor | `src/models/<name>/processing_<name>.js` | `src/models/processors.js` |
+| What                           | File                                             | Barrel to update                   |
+| ------------------------------ | ------------------------------------------------ | ---------------------------------- |
+| Custom tokenizer               | `src/models/<name>/tokenization_<name>.js`       | `src/models/tokenizers.js`         |
+| Custom image processor         | `src/models/<name>/image_processing_<name>.js`   | `src/models/image_processors.js`   |
+| Custom multimodal processor    | `src/models/<name>/processing_<name>.js`         | `src/models/processors.js`         |
 | Custom audio/feature extractor | `src/models/<name>/feature_extraction_<name>.js` | `src/models/feature_extractors.js` |
 
 The class name must match the `tokenizer_class` or `processor_class` field in the model's `tokenizer_config.json` / `preprocessor_config.json` on the Hub.
@@ -210,7 +213,6 @@ pnpm test
 pnpm --filter @huggingface/transformers test -t "MyModelForCausalLM"
 ```
 
-
 ## Create a Pull Request
 
 Before writing any code, we strongly advise you to search through the existing PRs or
@@ -230,6 +232,7 @@ You'll need the following tools installed to contribute to 🤗 Transformers.js:
 - **[pnpm](https://pnpm.io/)** - Fast, disk space efficient package manager
 
 To install pnpm:
+
 ```bash
 npm install -g pnpm
 ```
@@ -267,6 +270,7 @@ Follow the steps below to start contributing:
    the pull request.
 
 ### Pull request checklist
+
 ☐ The pull request title should summarize your contribution.  
 ☐ If your pull request addresses an issue, please mention the issue number in the pull
 request description to make sure they are linked (and people viewing the issue know you
@@ -280,19 +284,23 @@ useful to avoid duplicated work, and to differentiate it from PRs ready to be me
 ☐ If your changes affect user-facing functionality, update the relevant documentation.
 
 ### Tests
+
 We are using [Jest](https://jestjs.io/) to execute unit-tests. All tests can be found in `packages/transformers/tests` and have to end with `.test.js`
 
 Execute all tests
+
 ```bash
 pnpm test
 ```
 
 Execute tests for a specific package
+
 ```bash
 pnpm --filter @huggingface/transformers test
 ```
 
 Execute a specific test file
+
 ```bash
 cd packages/transformers
 pnpm test -- ./tests/models.test.js
@@ -301,14 +309,17 @@ pnpm test -- ./tests/models.test.js
 ### Style guide
 
 #### Code formatting
+
 We use [Prettier](https://prettier.io/) to maintain consistent code formatting across the project. Please ensure your code is formatted before submitting a pull request.
 
 **Format all files:**
+
 ```bash
 pnpm format
 ```
 
 **Check formatting without making changes:**
+
 ```bash
 pnpm format:check
 ```
@@ -318,13 +329,15 @@ pnpm format:check
 We recommend setting up Prettier in your IDE to format on save:
 
 **Visual Studio Code:**
+
 1. Install the [Prettier extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
 2. Open Settings (Ctrl+, or Cmd+,)
 3. Search for "format on save"
 4. Enable "Editor: Format On Save"
 5. Set Prettier as your default formatter: search for "default formatter" and select "Prettier - Code formatter"
 
 **IntelliJ IDEA / WebStorm:**
+
 1. Go to `Settings` → `Languages & Frameworks` → `JavaScript` → `Prettier`
 2. Set the Prettier package path (usually `node_modules/prettier`)
 3. Check "On save" under "Run for files"
@@ -333,9 +346,10 @@ We recommend setting up Prettier in your IDE to format on save:
 
 ## Project Structure
 
-This project uses **pnpm workspaces** to manage multiple packages in a monorepo. Currently, there is one workspace:
+This project uses **pnpm workspaces** to manage multiple packages in a monorepo:
 
 - `packages/transformers` - The main Transformers.js library
+- `packages/transformers-onnx` - The TypeScript ONNX Runtime inference provider
 
 This structure allows for better organization and makes it easier to add framework-specific integrations in the future.
 
@@ -346,22 +360,26 @@ This structure allows for better organization and makes it easier to add framewo
 The recommended way to develop and test changes is to use the watch mode build and install from the local package:
 
 1. Start the build in watch mode:
+
    ```bash
    pnpm dev
    ```
+
    This will automatically rebuild the library whenever you make changes to the source code.
 
 2. Create a separate test project and install transformers.js from your local development directory:
+
    ```bash
    mkdir my-test-project
    cd my-test-project
    npm init -y
    npm install file:/path/to/transformers.js/packages/transformers
    ```
+
    Replace `/path/to/transformers.js` with the actual path to your cloned repository.
 
 3. Make your changes to the transformers.js source code in the main repository. The watch mode will automatically rebuild the library.
 
 4. Test your changes in your test project. The changes will be automatically reflected since the package is linked via the `file:` protocol.
 
-This workflow allows for rapid iteration and testing during development.
+This workflow allows for rapid iteration and testing during development.

packages/transformers-onnx/README.md

@@ -0,0 +1,21 @@
+# @huggingface/transformers-onnx
+
+ONNX Runtime inference provider for Transformers.js.
+
+```js
+import { OnnxInferenceProvider } from '@huggingface/transformers-onnx';
+
+const provider = OnnxInferenceProvider.from_modelId('onnx-community/model-ONNX');
+```
+
+## Runtime dependencies
+
+Node applications using the ONNX provider must install `onnxruntime-node` alongside Transformers.js:
+
+```sh
+npm install @huggingface/transformers onnxruntime-node
+```
+
+The Node runtime is an optional peer so browser-only and custom-backend-only installations do not download native ONNX binaries.
+
+Browser ESM builds load this package lazily through the bare `@huggingface/transformers-onnx` specifier. Direct CDN usage therefore requires an import map for this package and its `onnxruntime-web` dependencies. Keep the provider's copied `.mjs` and `.wasm` files beside `transformers-onnx.web.js`; default relative `wasmPaths` are resolved from that module URL. Alternatively, set `env.backends.onnx.wasm.wasmPaths` before loading a model.

packages/transformers-onnx/jest.config.mjs

@@ -0,0 +1,5 @@
+export default {
+  testEnvironment: "node",
+  roots: ["./tests/"],
+  transform: {},
+};

packages/transformers-onnx/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@huggingface/transformers-onnx",
+  "version": "0.1.0",
+  "description": "ONNX Runtime inference provider for Transformers.js",
+  "type": "module",
+  "main": "./dist/transformers-onnx.node.cjs",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "node": {
+        "import": {
+          "types": "./types/index.d.ts",
+          "default": "./dist/transformers-onnx.node.mjs"
+        },
+        "require": {
+          "types": "./types/index.d.ts",
+          "default": "./dist/transformers-onnx.node.cjs"
+        }
+      },
+      "default": {
+        "types": "./types/index.d.ts",
+        "default": "./dist/transformers-onnx.web.js"
+      }
+    },
+    "./testing": {
+      "types": "./types/testing.d.ts",
+      "import": "./dist/testing.mjs",
+      "require": "./dist/testing.cjs"
+    }
+  },
+  "scripts": {
+    "format": "prettier --write . --ignore-path ../../.prettierignore",
+    "format:check": "prettier --check . --ignore-path ../../.prettierignore",
+    "typegen": "tsc --build",
+    "build": "node scripts/build.mjs && pnpm typegen",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js --runInBand"
+  },
+  "dependencies": {
+    "onnxruntime-common": "1.24.3",
+    "onnxruntime-web": "1.26.0-dev.20260416-b7804b056c"
+  },
+  "peerDependencies": {
+    "onnxruntime-node": "1.24.3"
+  },
+  "peerDependenciesMeta": {
+    "onnxruntime-node": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.1.0",
+    "@webgpu/types": "^0.1.69",
+    "esbuild": "^0.27.2",
+    "jest": "^30.2.0",
+    "onnxruntime-node": "1.24.3",
+    "typescript": "5.9.3"
+  },
+  "files": [
+    "src",
+    "dist",
+    "types",
+    "README.md",
+    "!**/*.tsbuildinfo"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "Apache-2.0"
+}