Transformers JS

Transformers.js — Machine Learning for JavaScript

Runs state-of-the-art ML models directly in JavaScript, in browsers and server-side runtimes (Node.js, Bun, Deno), with no Python server required.

Installation

npm install @huggingface/transformers

// Browser (CDN)
import { pipeline } from 'https://cdn.jsdelivr.net/npm/@huggingface/transformers';

Core Concepts

Pipeline API — groups preprocessing, inference, and postprocessing. Always dispose() when done to free memory (see references/EXAMPLES.md for cleanup patterns):

import { pipeline } from '@huggingface/transformers';
const pipe = await pipeline('sentiment-analysis');
const result = await pipe('I love transformers!');
await pipe.dispose();

Model selection — pass a model ID as the second argument, e.g. pipeline('sentiment-analysis', 'Xenova/bert-base-multilingual-uncased-sentiment'). Browse compatible models at https://huggingface.co/models?library=transformers.js&sort=trending, filtered by pipeline_tag for a specific task.

Device: { device: 'webgpu' } for GPU acceleration (falls back to WASM/CPU when unsupported); omit for CPU/WASM default.

Quantization: { dtype: 'q4' } — options fp32 (largest/most accurate), fp16, q8, q4 (smallest, some accuracy loss).

Supported Tasks

One pipeline call per task, e.g. await pipeline('image-classification')('https://example.com/image.jpg'). Task IDs by category:

• NLP: text-classification/sentiment-analysis, token-classification/ner, question-answering, fill-mask, summarization, translation, text-generation, text2text-generation, zero-shot-classification
• Vision: image-classification, object-detection, image-segmentation, depth-estimation, zero-shot-image-classification, image-to-image
• Audio: automatic-speech-recognition, audio-classification, text-to-speech/text-to-audio
• Multimodal: image-to-text, document-question-answering, zero-shot-object-detection
• Embeddings: feature-extraction (add { pooling: 'mean', normalize: true } for sentence embeddings), sentence-similarity

For streaming/chat text generation (system/user/assistant roles, TextStreamer, generation params), see references/TEXT_GENERATION.md.

Finding and Choosing Models

Filter the Hub by library=transformers.js and pipeline_tag=<task>, sort by trending/downloads/likes/modified. Consider: size (<100MB fast/browser-friendly, 100-500MB balanced, >500MB high-accuracy/Node.js), quantization (fp32/fp16/q8/q4 trade accuracy for size/speed), task compatibility (check the model card for supported tasks, I/O format, language, license), and performance metrics on the model card. Start with a smaller model, verify it has ONNX files, and pin a specific revision in production for stability.

Advanced Configuration

Environment (env) controls caching and model loading globally:

import { env, LogLevel } from '@huggingface/transformers';
env.allowRemoteModels = true;   // load from Hugging Face Hub
env.allowLocalModels = false;   // load from file system
env.localModelPath = '/models/';
env.useFSCache = true;          // Node.js disk cache
env.useBrowserCache = true;
env.cacheDir = './.cache';
env.logLevel = LogLevel.INFO;   // default WARNING
env.fetch = (url, options) => fetch(url, { ...options, headers: { ...options?.headers, Authorization: `Bearer ${HF_TOKEN}` } });

Typical patterns: development uses remote models + FS cache; production uses local-only models from a fixed path; testing disables both caches. Full option/caching reference: references/CONFIGURATION.md.

ModelRegistry (v4) inspects model assets before loading — required files, cache status, available dtypes:

import { ModelRegistry } from '@huggingface/transformers';
const files = await ModelRegistry.get_pipeline_files(task, modelId, modelOptions);
const cached = await ModelRegistry.is_pipeline_cached(task, modelId, modelOptions);
const dtypes = await ModelRegistry.get_available_dtypes(modelId);

See references/MODEL_REGISTRY.md for full API coverage.

Standalone tokenization: npm install @huggingface/tokenizers for fast tokenization without loading a full inference pipeline.

Manual tokenizer + model for finer control:

import { AutoTokenizer, AutoModel } from '@huggingface/transformers';
const tokenizer = await AutoTokenizer.from_pretrained('bert-base-uncased');
const model = await AutoModel.from_pretrained('bert-base-uncased');
const outputs = await model(await tokenizer('Hello world!'));

Batch processing: pass an array of inputs to any pipeline, e.g. classifier(['I love this!', 'This is terrible.']).