transformers-js

Transformers.js - Machine Learning for JavaScript

Safety Notice

This listing is imported from skills.sh public index metadata. Review upstream SKILL.md and repository scripts before running.

Copy this and send it to your AI assistant to learn

Install skill "transformers-js" with this command: npx skills add huggingface/skills/huggingface-skills-transformers-js

Transformers.js - Machine Learning for JavaScript

Transformers.js enables running state-of-the-art machine learning models directly in JavaScript, both in browsers and Node.js environments, with no 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

Installation

NPM Installation

npm install @huggingface/transformers

Browser Usage (CDN)

<script type="module"> import { pipeline } from 'https://cdn.jsdelivr.net/npm/@huggingface/transformers'; </script>

Core Concepts

  1. Pipeline API

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 task const pipe = await pipeline('sentiment-analysis');

// Use the pipeline const result = await pipe('I love transformers!'); // Output: [{ label: 'POSITIVE', score: 0.999817686 }]

// IMPORTANT: Always dispose when done to free memory await classifier.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.

  1. Model Selection

You can specify a custom model as the second argument:

const pipe = await pipeline( 'sentiment-analysis', 'Xenova/bert-base-multilingual-uncased-sentiment' );

Finding Models:

Browse available Transformers.js models on Hugging Face Hub:

Tip: Filter by task type, sort by trending/downloads, and check model cards for performance metrics and usage examples.

  1. Device Selection

Choose where to run the model:

// Run on CPU (default for WASM) const pipe = await pipeline('sentiment-analysis', 'model-id');

// Run on GPU (WebGPU - experimental) const pipe = await pipeline('sentiment-analysis', 'model-id', { device: 'webgpu', });

  1. Quantization Options

Control model precision vs. performance:

// Use quantized model (faster, smaller) const pipe = await pipeline('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 = await pipeline('text-classification'); const result = await classifier('This movie was amazing!');

Named Entity Recognition (NER)

const ner = await pipeline('token-classification'); const entities = await ner('My name is John and I live in New York.');

Question Answering

const qa = await pipeline('question-answering'); const answer = await qa({ question: 'What is the capital of France?', context: 'Paris is the capital and largest city of France.' });

Text Generation

const generator = await pipeline('text-generation', 'onnx-community/gemma-3-270m-it-ONNX'); const text = await generator('Once upon a time', { max_new_tokens: 100, temperature: 0.7 });

For streaming and chat: See Text Generation Guide for:

  • Streaming token-by-token output with TextStreamer

  • Chat/conversation format with system/user/assistant roles

  • Generation parameters (temperature, top_k, top_p)

  • Browser and Node.js examples

  • React components and API endpoints

Translation

const translator = await pipeline('translation', 'Xenova/nllb-200-distilled-600M'); const output = await translator('Hello, how are you?', { src_lang: 'eng_Latn', tgt_lang: 'fra_Latn' });

Summarization

const summarizer = await pipeline('summarization'); const summary = await summarizer(longText, { max_length: 100, min_length: 30 });

Zero-Shot Classification

const classifier = await pipeline('zero-shot-classification'); const result = await classifier('This is a story about sports.', ['politics', 'sports', 'technology']);

Computer Vision

Image Classification

const classifier = await pipeline('image-classification'); const result = await classifier('https://example.com/image.jpg'); // Or with local file const result = await classifier(imageUrl);

Object Detection

const detector = await pipeline('object-detection'); const objects = await detector('https://example.com/image.jpg'); // Returns: [{ label: 'person', score: 0.95, box: { xmin, ymin, xmax, ymax } }, ...]

Image Segmentation

const segmenter = await pipeline('image-segmentation'); const segments = await segmenter('https://example.com/image.jpg');

Depth Estimation

const depthEstimator = await pipeline('depth-estimation'); const depth = await depthEstimator('https://example.com/image.jpg');

Zero-Shot Image Classification

const classifier = await pipeline('zero-shot-image-classification'); const result = await classifier('image.jpg', ['cat', 'dog', 'bird']);

Audio Processing

Automatic Speech Recognition

const transcriber = await pipeline('automatic-speech-recognition'); const result = await transcriber('audio.wav'); // Returns: { text: 'transcribed text here' }

Audio Classification

const classifier = await pipeline('audio-classification'); const result = await classifier('audio.wav');

Text-to-Speech

const synthesizer = await pipeline('text-to-speech', 'Xenova/speecht5_tts'); const audio = await synthesizer('Hello, this is a test.', { speaker_embeddings: speakerEmbeddings });

Multimodal

Image-to-Text (Image Captioning)

const captioner = await pipeline('image-to-text'); const caption = await captioner('image.jpg');

Document Question Answering

const docQA = await pipeline('document-question-answering'); const answer = await docQA('document-image.jpg', 'What is the total amount?');

Zero-Shot Object Detection

const detector = await pipeline('zero-shot-object-detection'); const objects = await detector('image.jpg', ['person', 'car', 'tree']);

Feature Extraction (Embeddings)

const extractor = await pipeline('feature-extraction'); const embeddings = await extractor('This is a sentence to embed.'); // Returns: tensor of shape [1, sequence_length, hidden_size]

// For sentence embeddings (mean pooling) const extractor = await pipeline('feature-extraction', 'onnx-community/all-MiniLM-L6-v2-ONNX'); const embeddings = await extractor('Text to embed', { pooling: 'mean', normalize: true });

Finding and Choosing Models

Browsing the Hugging Face Hub

Discover compatible Transformers.js models on Hugging Face Hub:

Base URL (all models):

https://huggingface.co/models?library=transformers.js&#x26;sort=trending

Filter by task using the pipeline_tag parameter:

Task URL

Text Generation https://huggingface.co/models?pipeline_tag=text-generation&#x26;library=transformers.js&#x26;sort=trending

Text Classification https://huggingface.co/models?pipeline_tag=text-classification&#x26;library=transformers.js&#x26;sort=trending

Translation https://huggingface.co/models?pipeline_tag=translation&#x26;library=transformers.js&#x26;sort=trending

Summarization https://huggingface.co/models?pipeline_tag=summarization&#x26;library=transformers.js&#x26;sort=trending

Question Answering https://huggingface.co/models?pipeline_tag=question-answering&#x26;library=transformers.js&#x26;sort=trending

Image Classification https://huggingface.co/models?pipeline_tag=image-classification&#x26;library=transformers.js&#x26;sort=trending

Object Detection https://huggingface.co/models?pipeline_tag=object-detection&#x26;library=transformers.js&#x26;sort=trending

Image Segmentation https://huggingface.co/models?pipeline_tag=image-segmentation&#x26;library=transformers.js&#x26;sort=trending

Speech Recognition https://huggingface.co/models?pipeline_tag=automatic-speech-recognition&#x26;library=transformers.js&#x26;sort=trending

Audio Classification https://huggingface.co/models?pipeline_tag=audio-classification&#x26;library=transformers.js&#x26;sort=trending

Image-to-Text https://huggingface.co/models?pipeline_tag=image-to-text&#x26;library=transformers.js&#x26;sort=trending

Feature Extraction https://huggingface.co/models?pipeline_tag=feature-extraction&#x26;library=transformers.js&#x26;sort=trending

Zero-Shot Classification https://huggingface.co/models?pipeline_tag=zero-shot-classification&#x26;library=transformers.js&#x26;sort=trending

Sort options:

  • &sort=trending

  • Most popular recently

  • &sort=downloads

  • Most downloaded overall

  • &sort=likes

  • Most liked by community

  • &sort=modified

  • Recently updated

Choosing the Right Model

Consider these factors when selecting a model:

  1. Model Size

  • Small (< 100MB): Fast, suitable for browsers, limited accuracy

  • Medium (100MB - 500MB): Balanced performance, good for most use cases

  • Large (> 500MB): High accuracy, slower, better for Node.js or powerful devices

  1. Quantization Models are often available in different quantization levels:

  • fp32

  • Full precision (largest, most accurate)

  • fp16

  • Half precision (smaller, still accurate)

  • q8

  • 8-bit quantized (much smaller, slight accuracy loss)

  • q4

  • 4-bit quantized (smallest, noticeable accuracy loss)

  1. Task Compatibility Check the model card for:

  • Supported tasks (some models support multiple tasks)

  • Input/output formats

  • Language support (multilingual vs. English-only)

  • License restrictions

  1. Performance Metrics Model cards typically show:

  • Accuracy scores

  • Benchmark results

  • Inference speed

  • Memory requirements

Example: Finding a Text Generation Model

// 1. Visit: https://huggingface.co/models?pipeline_tag=text-generation&#x26;library=transformers.js&#x26;sort=trending

// 2. Browse and select a model (e.g., onnx-community/gemma-3-270m-it-ONNX)

// 3. Check model card for: // - Model size: ~270M parameters // - Quantization: q4 available // - Language: English // - Use case: Instruction-following chat

// 4. Use the model: import { pipeline } from '@huggingface/transformers';

const generator = await pipeline( 'text-generation', 'onnx-community/gemma-3-270m-it-ONNX', { dtype: 'q4' } // Use quantized version for faster inference );

const output = await generator('Explain quantum computing in simple terms.', { max_new_tokens: 100 });

await generator.dispose();

Tips for Model Selection

  • Start Small: Test with a smaller model first, then upgrade if needed

  • Check ONNX Support: Ensure the model has ONNX files (look for onnx folder in model repo)

  • Read Model Cards: Model cards contain usage examples, limitations, and benchmarks

  • Test Locally: Benchmark inference speed and memory usage in your environment

  • Community Models: Look for models by Xenova (Transformers.js maintainer) or onnx-community

  • Version Pin: Use specific git commits in production for stability: const pipe = await pipeline('task', 'model-id', { revision: 'abc123' });

Advanced Configuration

Environment Configuration (env )

The env object provides comprehensive control over Transformers.js execution, caching, and model loading.

Quick Overview:

import { env } from '@huggingface/transformers';

// View version console.log(env.version); // e.g., '3.8.1'

// Common settings env.allowRemoteModels = true; // Load from Hugging Face Hub env.allowLocalModels = false; // Load from file system env.localModelPath = '/models/'; // Local model directory env.useFSCache = true; // Cache models on disk (Node.js) env.useBrowserCache = true; // Cache models in browser env.cacheDir = './.cache'; // Cache directory location

Configuration Patterns:

// Development: Fast iteration with remote models env.allowRemoteModels = true; env.useFSCache = true;

// Production: Local models only env.allowRemoteModels = false; env.allowLocalModels = true; env.localModelPath = '/app/models/';

// Custom CDN env.remoteHost = 'https://cdn.example.com/models';

// Disable caching (testing) env.useFSCache = false; env.useBrowserCache = false;

For complete documentation on all configuration options, caching strategies, cache management, pre-downloading models, and more, see:

→ Configuration Reference

Working with Tensors

import { AutoTokenizer, AutoModel } from '@huggingface/transformers';

// Load tokenizer and model separately for more control const tokenizer = await AutoTokenizer.from_pretrained('bert-base-uncased'); const model = await AutoModel.from_pretrained('bert-base-uncased');

// Tokenize input const inputs = await tokenizer('Hello world!');

// Run model const outputs = await model(inputs);

Batch Processing

const classifier = await pipeline('sentiment-analysis');

// Process multiple texts const results = await classifier([ 'I love this!', 'This is terrible.', 'It was okay.' ]);

Browser-Specific Considerations

WebGPU Usage

WebGPU provides GPU acceleration in browsers:

const pipe = await pipeline('text-generation', 'onnx-community/gemma-3-270m-it-ONNX', { device: 'webgpu', dtype: 'fp32' });

Note: WebGPU is experimental. Check browser compatibility and file issues if problems occur.

WASM Performance

Default browser execution uses WASM:

// Optimized for browsers with quantization const pipe = await pipeline('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:

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

// Track progress for each file const fileProgress = {};

function onProgress(info) { console.log(${info.status}: ${info.file});

if (info.status === 'progress') { fileProgress[info.file] = info.progress; console.log(${info.file}: ${info.progress.toFixed(1)}%); }

if (info.status === 'done') { console.log(✓ ${info.file} complete); } }

// Pass callback to pipeline const classifier = await pipeline('sentiment-analysis', null, { progress_callback: onProgress });

Progress Info Properties:

interface ProgressInfo { status: 'initiate' | 'download' | 'progress' | 'done' | 'ready'; name: string; // Model id or path file: string; // File being processed progress?: number; // Percentage (0-100, only for 'progress' status) loaded?: number; // Bytes downloaded (only for 'progress' status) total?: number; // Total bytes (only for 'progress' status) }

For complete examples including browser UIs, React components, CLI progress bars, and retry logic, see:

→ Pipeline Options - Progress Callback

Error Handling

try { const pipe = await pipeline('sentiment-analysis', 'model-id'); const result = await pipe('text to analyze'); } catch (error) { if (error.message.includes('fetch')) { console.error('Model download failed. Check internet connection.'); } else if (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 = await pipeline('sentiment-analysis'); const result = await pipe('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' )

  • Reduce batch size

  • Limit sequence length with max_length

WebGPU Errors

  • Check browser compatibility (Chrome 113+, Edge 113+)

  • Try dtype: 'fp16' if fp32 fails

  • Fall back to WASM if WebGPU unavailable

Reference Documentation

This Skill

  • Pipeline Options - Configure pipeline() with progress_callback , device , dtype , etc.

  • Configuration Reference - Global env configuration for caching and model loading

  • Caching Reference - Browser Cache API, Node.js filesystem cache, and custom cache implementations

  • Text Generation Guide - Streaming, chat format, and generation parameters

  • Model Architectures - Supported models and selection tips

  • Code Examples - Real-world implementations for different runtimes

Official Transformers.js

Best Practices

  • 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.

Source Transparency

This detail page is rendered from real SKILL.md content. Trust labels are metadata-based hints, not a safety guarantee.

Open in GitHubOpen in ClawHub

Related Skills

Related by shared tags or category signals.

General

hugging-face-model-trainer

No summary provided by upstream source.

Repository SourceNeeds Review
-328
huggingface
General

hugging-face-datasets

No summary provided by upstream source.

Repository SourceNeeds Review
-292
huggingface
General

hugging-face-evaluation

No summary provided by upstream source.

Repository SourceNeeds Review
-206
huggingface