transformers-js

transformers.js

ML inference for JavaScript, without a Python server. Supports text, vision, audio, and multimodal tasks through a single pipeline() entry point.

Install

npm install @huggingface/transformers

Quick start

import { pipeline } from "@huggingface/transformers";

const classifier = await pipeline("sentiment-analysis"); const output = await classifier("I love transformers!"); // [{ label: "POSITIVE", score: 0.9998 }]


`pipeline(task, model?, options?)` is the one function you need 90% of the time.
Passing no `model` uses the default for that task.

## Supported tasks

<!-- @generated:start id=task-list -->
- [`text-classification`](references/TASKS.md#text-classification) _(alias: `sentiment-analysis`)_ — default model: `Xenova/distilbert-base-uncased-finetuned-sst-2-english`
- [`token-classification`](references/TASKS.md#token-classification) _(alias: `ner`)_ — default model: `Xenova/bert-base-multilingual-cased-ner-hrl`
- [`question-answering`](references/TASKS.md#question-answering) — default model: `Xenova/distilbert-base-cased-distilled-squad`
- [`fill-mask`](references/TASKS.md#fill-mask) — default model: `onnx-community/ettin-encoder-32m-ONNX`
- [`summarization`](references/TASKS.md#summarization) — default model: `Xenova/distilbart-cnn-6-6`
- [`translation`](references/TASKS.md#translation) — default model: `Xenova/t5-small`
- [`text2text-generation`](references/TASKS.md#text2text-generation) — default model: `Xenova/flan-t5-small`
- [`text-generation`](references/TASKS.md#text-generation) — default model: `onnx-community/Qwen3-0.6B-ONNX`
- [`zero-shot-classification`](references/TASKS.md#zero-shot-classification) — default model: `Xenova/distilbert-base-uncased-mnli`
- [`audio-classification`](references/TASKS.md#audio-classification) — default model: `Xenova/wav2vec2-base-superb-ks`
- [`zero-shot-audio-classification`](references/TASKS.md#zero-shot-audio-classification) — default model: `Xenova/clap-htsat-unfused`
- [`automatic-speech-recognition`](references/TASKS.md#automatic-speech-recognition) _(alias: `asr`)_ — default model: `Xenova/whisper-tiny.en`
- [`text-to-audio`](references/TASKS.md#text-to-audio) _(alias: `text-to-speech`)_ — default model: `onnx-community/Supertonic-TTS-ONNX`
- [`image-to-text`](references/TASKS.md#image-to-text) — default model: `Xenova/vit-gpt2-image-captioning`
- [`image-classification`](references/TASKS.md#image-classification) — default model: `Xenova/vit-base-patch16-224`
- [`image-segmentation`](references/TASKS.md#image-segmentation) — default model: `Xenova/detr-resnet-50-panoptic`
- [`background-removal`](references/TASKS.md#background-removal) — default model: `Xenova/modnet`
- [`zero-shot-image-classification`](references/TASKS.md#zero-shot-image-classification) — default model: `Xenova/clip-vit-base-patch32`
- [`object-detection`](references/TASKS.md#object-detection) — default model: `Xenova/detr-resnet-50`
- [`zero-shot-object-detection`](references/TASKS.md#zero-shot-object-detection) — default model: `Xenova/owlvit-base-patch32`
- [`document-question-answering`](references/TASKS.md#document-question-answering) — default model: `Xenova/donut-base-finetuned-docvqa`
- [`image-to-image`](references/TASKS.md#image-to-image) — default model: `Xenova/swin2SR-classical-sr-x2-64`
- [`depth-estimation`](references/TASKS.md#depth-estimation) — default model: `onnx-community/depth-anything-v2-small`
- [`feature-extraction`](references/TASKS.md#feature-extraction) _(alias: `embeddings`)_ — default model: `onnx-community/all-MiniLM-L6-v2-ONNX`
- [`image-feature-extraction`](references/TASKS.md#image-feature-extraction) — default model: `onnx-community/dinov3-vits16-pretrain-lvd1689m-ONNX`
<!-- @generated:end id=task-list -->

For full recipes — every task, grouped by modality, with runnable code —
see [`references/TASKS.md`](references/TASKS.md).

## Choosing a model

Browse models compatible with transformers.js on the Hub:
<https://huggingface.co/models?library=transformers.js>

Filter by task with the `pipeline_tag` parameter, e.g.
<https://huggingface.co/models?library=transformers.js&pipeline_tag=text-generation>.

**Before recommending a model**, confirm it actually has ONNX weights — the
library cannot load a model without them. Two ways to check:

1. Open the model page on the Hub and look for an `onnx/` directory in the
   "Files and versions" tab.
2. Programmatically, with `ModelRegistry.get_available_dtypes(modelId)` —
   returns the list of dtypes shipped. An empty array means the model exists
   but ships no ONNX files. It throws a `ModelFileNotFoundError` if the model
   does not exist or is not accessible (private/gated — the Hub cannot tell
   these apart), and a regular error on network failures, so an unreachable
   model is never mistaken for one without ONNX files.

```javascript
import { ModelRegistry, ModelFileNotFoundError } from "@huggingface/transformers";

// "Xenova/some-model" is a placeholder — substitute the ID you want to check.
try {
  const dtypes = await ModelRegistry.get_available_dtypes("Xenova/some-model");
  if (dtypes.length === 0) {
    // Model exists but has no ONNX files — not usable with transformers.js.
  }
} catch (e) {
  if (e instanceof ModelFileNotFoundError) {
    // Model does not exist, or is private/gated without a token.
  } else {
    throw e; // network failure — retry rather than blacklisting the model
  }
}

Don't suggest a model without verifying this; the failure mode at runtime is a download error that's harder to diagnose than a pre-flight check. For a fuller pre-flight pattern (cache checks, dtype fallback), see references/CONFIGURATION.md.

Quantization

Most pipelines accept a dtype option. Smaller dtypes download and run faster at the cost of some accuracy:

`dtype`	Size	Use when
`fp32`	Largest	Maximum accuracy, Node.js with lots of RAM
`fp16`	~50% of fp32	GPU / WebGPU inference
`q8`	~25% of fp32	Good default for browsers
`q4`	~12% of fp32	Tight memory budgets, large language models
`q4f16`	~12% of fp32	Like `q4` but with fp16 activations — pairs well with WebGPU LLMs

const pipe = await pipeline("text-generation", "onnx-community/Qwen3-0.6B-ONNX", {
  dtype: "q4",
});

Device

Default is CPU/WASM. Pass device: "webgpu" to run on the GPU when available:

const pipe = await pipeline("sentiment-analysis", null, { device: "webgpu" });

Memory management

Pipelines hold onto model weights and backend sessions. Always call pipe.dispose() when you're done with one — especially in long-running servers, before loading a replacement, or on component unmount.

const pipe = await pipeline("sentiment-analysis");
try {
  const result = await pipe("Great!");
} finally {
  await pipe.dispose();
}

Configuration

The env export lets you control model sources, caching, logging, and the fetch function.

import { env, LogLevel } from "@huggingface/transformers";

env.allowRemoteModels = true;
env.useFSCache = true;           // Node.js: cache downloaded models on disk
env.useBrowserCache = true;      // Browser: cache via the Cache API
env.logLevel = LogLevel.WARNING;

See references/CONFIGURATION.md for the full set of environment options, cache management, and private / gated models.

Pipeline options

Every pipeline accepts a progress_callback for download progress plus options controlling device, dtype, and caching. The per-task recipes in references/TASKS.md show common call options (e.g. top_k, max_new_tokens) in use; shared loading options, generation parameters, streaming, and KV-cache reuse are documented in references/PIPELINE_OPTIONS.md. For the exhaustive per-task option types, see the API reference.

Things to never do

Don't reuse a disposed pipeline. Create a new one with pipeline(...) after dispose().
Don't recreate pipelines inside hot loops. Create once, call many times.
Don't block startup on model downloads. Show progress via progress_callback.
Don't fabricate model IDs. Confirm a model exists on the Hub and has ONNX files (look for an onnx/ directory in the repo) before suggesting it to a user.

Reference documentation

Official site: https://huggingface.co/docs/transformers.js
API reference: https://huggingface.co/docs/transformers.js/api/pipelines
Examples repo: https://github.com/huggingface/transformers.js-examples

This skill's local references:

TASKS.md — recipes for every task, grouped by modality (generated)
CONFIGURATION.md — env options, caching, model inspection
PIPELINE_OPTIONS.md — common pipeline options, dtype, device, generation parameters