Transformers.js enables running state-of-the-art machine learning models directly in JavaScript across browsers and server-side runtimes (Node.js, Bun, Deno), with no Python server required.
When to Use This Skill
Use this skill when you need to:
Run ML models for text analysis, generation, or translation in JavaScript
Perform image classification, object detection, or segmentation
Implement speech recognition or audio processing
Build multimodal AI applications (text-to-image, image-to-text, etc.)
Run models client-side in the browser without a backend
The pipeline API is the easiest way to use models. It groups together preprocessing, model inference, and postprocessing:
import { pipeline } from'@huggingface/transformers';
// Create a pipeline for a specific taskconst pipe = awaitpipeline('sentiment-analysis');
// Use the pipelineconst result = awaitpipe('I love transformers!');
// Output: [{ label: 'POSITIVE', score: 0.999817686 }]// IMPORTANT: Always dispose when done to free memoryawait pipe.dispose();
⚠️ Memory Management: All pipelines must be disposed with pipe.dispose() when finished to prevent memory leaks. See examples in Code Examples for cleanup patterns across different environments.
2. Model Selection
You can specify a custom model as the second argument:
Tip: Filter by task type, sort by trending/downloads, and check model cards for performance metrics and usage examples.
3. Device Selection
Choose where to run the model:
// Run on CPU (default for WASM)const pipe = awaitpipeline('sentiment-analysis', 'model-id');
// Run on GPU (WebGPU)const pipe = awaitpipeline('sentiment-analysis', 'model-id', {
device: 'webgpu',
});
4. Quantization Options
Control model precision vs. performance:
// Use quantized model (faster, smaller)const pipe = awaitpipeline('sentiment-analysis', 'model-id', {
dtype: 'q4', // Options: 'fp32', 'fp16', 'q8', 'q4'
});
Supported Tasks
Note: All examples below show basic usage.
Natural Language Processing
Text Classification
const classifier = awaitpipeline('text-classification');
const result = awaitclassifier('This movie was amazing!');
Named Entity Recognition (NER)
const ner = awaitpipeline('token-classification');
const entities = awaitner('My name is John and I live in New York.');
Question Answering
const qa = awaitpipeline('question-answering');
const answer = awaitqa({
question: 'What is the capital of France?',
context: 'Paris is the capital and largest city of France.'
});
Text Generation
const generator = awaitpipeline('text-generation', 'onnx-community/gemma-3-270m-it-ONNX');
const text = awaitgenerator('Once upon a time', {
max_new_tokens: 100,
temperature: 0.7
});
const classifier = awaitpipeline('zero-shot-classification');
const result = awaitclassifier('This is a story about sports.', ['politics', 'sports', 'technology']);
Computer Vision
Image Classification
const classifier = awaitpipeline('image-classification');
const result = awaitclassifier('https://example.com/image.jpg');
// Or with local fileconst result = awaitclassifier(imageUrl);
ModelRegistry gives you visibility and control over model assets before loading a pipeline. Use it to estimate download size, check cache status, inspect available dtypes, and clear cached artifacts for a specific task/model/options tuple.
import { ModelRegistry } from'@huggingface/transformers';
const task = 'feature-extraction';
const modelId = 'onnx-community/all-MiniLM-L6-v2-ONNX';
const modelOptions = { dtype: 'fp32' };
// List required files for this pipelineconst files = awaitModelRegistry.get_pipeline_files(task, modelId, modelOptions);
// Check if assets are already cachedconst cached = awaitModelRegistry.is_pipeline_cached(task, modelId, modelOptions);
// Inspect precision formats available for this modelconst dtypes = awaitModelRegistry.get_available_dtypes(modelId);
console.log({ files: files.length, cached, dtypes });
For tokenization-only workflows, use @huggingface/tokenizers. It is a separate lightweight package useful when you need fast tokenization/encoding without loading full model inference pipelines.
Note: Use webgpu when available and fall back to WASM/CPU when not supported in the current runtime.
WASM Performance
WASM is the most compatible execution backend across runtimes:
// Optimized for browsers with quantizationconst pipe = awaitpipeline('sentiment-analysis', 'model-id', {
dtype: 'q8'// or 'q4' for even smaller size
});
Progress Tracking & Loading Indicators
Models can be large (ranging from a few MB to several GB) and consist of multiple files. Track download progress by passing a callback to the pipeline() function:
try {
const pipe = awaitpipeline('sentiment-analysis', 'model-id');
const result = awaitpipe('text to analyze');
} catch (error) {
if (error.message.includes('fetch')) {
console.error('Model download failed. Check internet connection.');
} elseif (error.message.includes('ONNX')) {
console.error('Model execution failed. Check model compatibility.');
} else {
console.error('Unknown error:', error);
}
}
Performance Tips
Reuse Pipelines: Create pipeline once, reuse for multiple inferences
Use Quantization: Start with q8 or q4 for faster inference
Batch Processing: Process multiple inputs together when possible
Cache Models: Models are cached automatically (see Caching Reference for details on browser Cache API, Node.js filesystem cache, and custom implementations)
WebGPU for Large Models: Use WebGPU for models that benefit from GPU acceleration
Prune Context: For text generation, limit max_new_tokens to avoid memory issues
Clean Up Resources: Call pipe.dispose() when done to free memory
Memory Management
IMPORTANT: Always call pipe.dispose() when finished to prevent memory leaks.
const pipe = awaitpipeline('sentiment-analysis');
const result = awaitpipe('Great product!');
await pipe.dispose(); // ✓ Free memory (100MB - several GB per model)
When to dispose:
Application shutdown or component unmount
Before loading a different model
After batch processing in long-running apps
Models consume significant memory and hold GPU/CPU resources. Disposal is critical for browser memory limits and server stability.
For detailed patterns (React cleanup, servers, browser), see Code Examples
Troubleshooting
Model Not Found
Verify model exists on Hugging Face Hub
Check model name spelling
Ensure model has ONNX files (look for onnx folder in model repo)
Memory Issues
Use smaller models or quantized versions (dtype: 'q4')
Always Dispose Pipelines: Call pipe.dispose() when done - critical for preventing memory leaks
Start with Pipelines: Use the pipeline API unless you need fine-grained control
Test Locally First: Test models with small inputs before deploying
Monitor Model Sizes: Be aware of model download sizes for web applications
Handle Loading States: Show progress indicators for better UX
Version Pin: Pin specific model versions for production stability
Error Boundaries: Always wrap pipeline calls in try-catch blocks
Progressive Enhancement: Provide fallbacks for unsupported browsers
Reuse Models: Load once, use many times - don't recreate pipelines unnecessarily
Graceful Shutdown: Dispose models on SIGTERM/SIGINT in servers
Quick Reference: Task IDs
Task
Task ID
Text classification
text-classification or sentiment-analysis
Token classification
token-classification or ner
Question answering
question-answering
Fill mask
fill-mask
Summarization
summarization
Translation
translation
Text generation
text-generation
Text-to-text generation
text2text-generation
Zero-shot classification
zero-shot-classification
Image classification
image-classification
Image segmentation
image-segmentation
Object detection
object-detection
Depth estimation
depth-estimation
Image-to-image
image-to-image
Zero-shot image classification
zero-shot-image-classification
Zero-shot object detection
zero-shot-object-detection
Automatic speech recognition
automatic-speech-recognition
Audio classification
audio-classification
Text-to-speech
text-to-speech or text-to-audio
Image-to-text
image-to-text
Document question answering
document-question-answering
Feature extraction
feature-extraction
Sentence similarity
sentence-similarity
This skill enables you to integrate state-of-the-art machine learning capabilities directly into JavaScript applications without requiring separate ML servers or Python environments.
Limitations
Use this skill only when the task clearly matches its upstream product or API scope.
Verify commands, API behavior, pricing, quotas, credentials, and deployment effects against current official documentation before making changes.
Do not treat generated examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.
