feat: export supportedDevices and deviceToExecutionProviders from public API

[Amarnath10i]

Summary

Resolves #1645.

The supportedDevices list and the deviceToExecutionProviders() helper were only available from the internal ./backends/onnx.js module. Users who want to inspect supported devices or map a device to its ONNX execution providers had to reach into a private path. This PR surfaces both from the package entry point so they become part of the public API:

• �ackends/onnx.js: change const supportedDevices = [] to export const supportedDevices = [].
• ransformers.js: re-export supportedDevices and deviceToExecutionProviders from ./backends/onnx.js.

Both already carry JSDoc, so pnpm typegen will expose their types automatically.

Example

\\js
import { supportedDevices, deviceToExecutionProviders } from '@huggingface/transformers';

console.log(supportedDevices); // e.g. ['webgpu', 'cpu', ...]
console.log(deviceToExecutionProviders('auto')); // current device's execution providers
\\

Test plan

ode --check on the two edited files passes.

• Types are regenerated via pnpm typegen in CI.

[promiseeuler]

While testing the new public export, I found that supportedDevices exposes the library's internal mutable array. A consumer can mutate it and corrupt later provider selection globally. On this branch I imported both exports, saved the first device ('coreml' here), ran supportedDevices.length = 0, and then deviceToExecutionProviders('coreml') threw: Unsupported device: "coreml". Should be one of: . Could the public API return an immutable snapshot (or freeze a separate exported copy) while keeping the internal array private, and add a regression proving consumer mutation cannot affect deviceToExecutionProviders? The focused import/reproduction is deterministic. Prettier passed for both changed files and tsc --build packages/transformers/tsconfig.json passed.

[Amarnath10i]

@promiseeuler Thanks for the thorough review and reproduction — you're right, the previous export leaked the library's internal mutable array.

Fixed in the latest push:

• The internal array is now private (renamed to \supportedDevicesInternal) and is no longer exported.
• The public \supportedDevices\ is now a frozen snapshot: \Object.freeze([...supportedDevicesInternal]). Consumers can no longer mutate it, and even if they try (\length = 0, \push, index assignment) the internal state — and therefore \deviceToExecutionProviders\ — is unaffected.
• Added regression tests in \exports.test.js\ that assert the export is frozen and that mutating it does not change \deviceToExecutionProviders('auto')\ or a specific device lookup.

I couldn't run the full \pnpm\ suite locally (no network for install here), so it'd be great if you could re-run \prettier\ and \ sc --build packages/transformers/tsconfig.json\ on your side. The change is otherwise minimal and confined to the two source files plus the new test.

[promiseeuler]

Rechecked exact head 25f51a2. Prettier passes on all three changed files; tsc --build packages/transformers/tsconfig.json passes; and the focused exports.test.js suite passes 3/3, including both supportedDevices immutability regressions. The private internal array plus frozen public snapshot addresses the reported mutation path without changing provider selection. Thanks for the focused fix.

[promiseeuler]

Thanks for addressing the original supportedDevices export path. I tested exact head 25f51a2; the new focused test suite passes (3 tests), but the internal array is still exposed through deviceToExecutionProviders("auto").

const device = supportedDevices[0];
const auto = deviceToExecutionProviders("auto");
auto.length = 0;
deviceToExecutionProviders(device);

On macOS, auto was not frozen, clearing it changed the next deviceToExecutionProviders("auto") result to [], and the final call threw Unsupported device: "coreml". Should be one of: .

Could the "auto" branch return a copy or immutable snapshot instead of supportedDevicesInternal, with a regression that mutates the value returned by deviceToExecutionProviders("auto")? The public export is now protected, but this second public path can still mutate the same internal state.

[nico-martin]

Hi @Amarnath10i, thank you so much for looking into this! The latest version looks good. The public device list is immutable, provider results are defensive copies, and the mutation regressions are covered. No changes are requested; a small custom-runtime test would just be a non-blocking follow-up.

[HuggingFaceDocBuilderDev]

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

[promiseeuler]

Rechecked exact head 7dd9a53. The focused exports suite passes 9/9, Prettier passes on all three changed files, and tsc --build packages/transformers/tsconfig.json passes. The immutable public snapshot and defensive copies cover both mutation paths, while the custom-runtime guard preserves the existing undefined default. The requested changes are resolved.

[Amarnath10i]

Addressed your feedback! The array is now private and the public export is a frozen snapshot.

[xenova]

Hi @Amarnath10i 👋 Thanks for the PR! One concern I do have with the shape of the PR in its current state is that this changes the top-level exports / API in a way that isn't consistent with the python transformers library.

I think it would be better to attach it to the backends property in the env variable we export.

For example, you can access (and update) the ONNX env via env.backends.onnx

// e.g., set location of .wasm files. Defaults to use a CDN.
env.backends.onnx.wasm.wasmPaths = '/path/to/files/';

and since these properties/functions you mention are very specific to ONNX Runtime ("ExecutionProviders" and "devices"), it could be useful to expose this there.

In fact, we have some precedence here with setLogLevel, and we could maybe do something like getSupportedDevices()

transformers.js/packages/transformers/src/backends/onnx.js

Lines 386 to 390 in bf27627

	// Expose ONNX environment variables to `env.backends.onnx`
	env.backends.onnx = {
	...ONNX_ENV,
	setLogLevel,
	};

Secondly, what use-case do you have for exposing the internal mapping for deviceToExecutionProviders? I think that is somewhat internal (transformers.js uses a "device" abstraction, and we choose the "execution provider" based on this).