Index of every page on this site: llms.txt
All skills
huggingface avatar

/transformers-js

@205e9c2
Run it yourself

Run state-of-the-art machine learning models directly in JavaScript. `@huggingface/transformers` supports text, vision, audio, and multimodal tasks in browsers and Node.js / Bun / Deno, with WebGPU or WASM execution.

  • 4 files
  • 77.1 KB
  • Apache-2
  • Updated 2 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/huggingface/transformers.js/transformers-js

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesCONFIGURATION.md

≈2.4k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Configuration

All global configuration lives on the env object exported from the package. Mutating fields on env changes library-wide behavior at runtime.

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

Quick examples

<!-- @generated:start id=examples:env -->

Example: Load models from your own server and disable remote downloads.

import { env } from '@huggingface/transformers';
env.allowRemoteModels = false;
env.localModelPath = '/path/to/local/models/';

Example: Point the filesystem cache at a custom directory (Node.js).

import { env } from '@huggingface/transformers';
env.cacheDir = '/path/to/cache/directory/';
<!-- @generated:end id=examples:env -->

All options

<!-- @generated:start id=typedef:TransformersEnvironment -->
Option Type Description
version string This version of Transformers.js.
backends object Exposes backend environment settings that users can override.
logLevel number The logging level. Use LogLevel enum values. Defaults to LogLevel.WARNING.
allowRemoteModels boolean Whether to allow loading of remote files, defaults to true. If set to false, it will have the same effect as setting local_files_only=true when loading pipelines, models, tokenizers, processors, etc.
remoteHost string Host URL to load models from. Defaults to the Hugging Face Hub.
remotePathTemplate string Path template to fill in and append to remoteHost when loading models.
allowLocalModels boolean Whether to allow loading of local files, defaults to false if running in-browser, and true otherwise. If set to false, it will skip the local file check and try to load the model from the remote host.
localModelPath string Path to load local models from. By default, it is /models/ relative to the library's installed location when a file system is available (e.g., Node.js), and the /models/ URL path otherwise (e.g., browsers).
useFS boolean Whether to use the file system to load files. By default, it is true if available.
useBrowserCache boolean Whether to use Cache API to cache models. By default, it is true if available.
useFSCache boolean Whether to use the file system to cache files. By default, it is true if available.
cacheDir string|null The directory to use for caching files with the file system. By default, it is .cache relative to the library's installed location when a file system is available (e.g., Node.js), and null otherwise (e.g., browsers).
useCustomCache boolean Whether to use a custom cache system (defined by customCache), defaults to false.
customCache CacheInterface|null The custom cache to use. Defaults to null. This must be an object that implements the match and put functions of the Web Cache API. For more information, see https://developer.mozilla.org/en-US/docs/Web/API/Cache.
useWasmCache boolean Whether to pre-load and cache WASM binaries and the WASM factory (.mjs) for ONNX Runtime. Defaults to true when cache is available. This can improve performance and enables offline usage by avoiding repeated downloads.
cacheKey string The cache key to use for storing models and WASM binaries. Defaults to transformers-cache.
experimental_useCrossOriginStorage boolean Whether to use the Cross-Origin Storage API to cache model files across origins, allowing different sites to share the same cached model weights. Defaults to false. Requires the Cross-Origin Storage Chrome extension: https://chromewebstore.google.com/detail/cross-origin-storage/denpnpcgjgikjpoglpjefakmdcbmlgih. The experimental_ prefix indicates that the underlying browser API is not yet standardized and may change or be removed without a major version bump. For more information, see https://github.com/WICG/cross-origin-storage.
fetch (input: string | URL, init?: any) => Promise<any> The fetch function to use. Defaults to fetch.
<!-- @generated:end id=typedef:TransformersEnvironment -->

Log levels

Pass one of these values to env.logLevel:

Value Numeric
LogLevel.DEBUG 10
LogLevel.INFO 20
LogLevel.WARNING 30 (default)
LogLevel.ERROR 40
LogLevel.NONE 50

Higher numbers suppress more output. Setting env.logLevel also propagates to ONNX Runtime, so you get matching verbosity from the inference backend.

Common patterns

Development (fast iteration with remote models):

env.allowRemoteModels = true;
env.useFSCache = true;
env.logLevel = LogLevel.INFO;

Production Node.js server (air-gapped, local only):

env.allowRemoteModels = false;
env.allowLocalModels = true;
env.localModelPath = "/opt/models";

Browser app with a CDN mirror:

env.remoteHost = "https://cdn.example.com";
env.useBrowserCache = true;

Browser app, no CDN, just persist downloads via the Cache API:

env.useBrowserCache = true; // default when Cache API is available
// First visit downloads from the Hub; subsequent visits hit the cache.

Private / gated models and custom fetch

In Node.js, no configuration is needed for private or gated models: the library automatically sends Authorization: Bearer $HF_TOKEN with requests to the Hugging Face Hub, so setting that environment variable is enough.

In browsers — or for retry logic and abort signals anywhere — override env.fetch:

// Obtain the token from your own backend at runtime; never hard-code one in
// shipped client code.
const token = await getHuggingFaceToken();

env.fetch = (url, init) =>
  fetch(url, {
    ...init,
    headers: { ...init?.headers, Authorization: `Bearer ${token}` },
  });

Custom cache backends

env.useCustomCache = true;
env.customCache = {
  async match(key) { /* return Response or undefined */ },
  async put(key, response) { /* persist */ },
};

The cache must implement the Web Cache API's match and put methods.

Inspecting models before loading

ModelRegistry reports which files a model needs, whether they're cached locally, which dtypes the model ships with, and can clear caches selectively. Useful for pre-flight UI and disk management.

Note that get_available_dtypes returns [] only when the model exists but ships no ONNX files; it throws a ModelFileNotFoundError for missing or inaccessible (private/gated) models, and a regular error on network failures.

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

const task = "feature-extraction";
const modelId = "onnx-community/all-MiniLM-L6-v2-ONNX";

const cached = await ModelRegistry.is_pipeline_cached(task, modelId);
if (!cached) {
  const files = await ModelRegistry.get_pipeline_files(task, modelId);
  // ask the user to confirm before `pipeline(...)` downloads these.
}

const dtypes = await ModelRegistry.get_available_dtypes(modelId);
const dtype = ["q4", "q8", "fp16", "fp32"].find((d) => dtypes.includes(d));
const pipe = await pipeline(task, modelId, { dtype });
<!-- @generated:start id=class:ModelRegistry -->

Static class for cache and file management operations.

Methods

  • get_files(modelId, [options]) → Promise<string[]> — Get all files (model, tokenizer, processor) needed for a model.
  • get_pipeline_files(task, modelId, [options]) → Promise<string[]> — Get all files needed for a specific pipeline task.
  • get_model_files(modelId, [options]) → Promise<string[]> — Get model files needed for a specific model.
  • get_tokenizer_files(modelId) → Promise<string[]> — Get tokenizer files needed for a specific model.
  • get_processor_files(modelId) → Promise<string[]> — Get processor files needed for a specific model.
  • get_available_dtypes(modelId, [options]) → Promise<string[]> — Detects which quantization levels (dtypes) are available for a model by checking which ONNX files exist on the hub or locally.
  • is_cached(modelId, [options]) → Promise<boolean> — Quickly checks if a model is fully cached by verifying config.json is present, then confirming all required files are cached.
  • is_cached_files(modelId, [options]) → Promise<CacheCheckResult> — Checks if all files for a given model are already cached, with per-file detail.
  • is_pipeline_cached(task, modelId, [options]) → Promise<boolean> — Quickly checks if all files for a specific pipeline task are cached by verifying config.json is present, then confirming all required files are cached.
  • is_pipeline_cached_files(task, modelId, [options]) → Promise<CacheCheckResult> — Checks if all files for a specific pipeline task are already cached, with per-file detail.
  • get_file_metadata(path_or_repo_id, filename, [options]) → Promise<{exists: boolean, size?: number, contentType?: string, fromCache?: boolean}> — Get metadata for a specific file without downloading it.
  • clear_cache(modelId, [options]) → Promise<CacheClearResult> — Clears all cached files for a given model.
  • clear_pipeline_cache(task, modelId, [options]) → Promise<CacheClearResult> — Clears all cached files for a specific pipeline task.
<!-- @generated:end id=class:ModelRegistry -->

To reclaim disk space for a specific model or task:

await ModelRegistry.clear_cache(modelId);
await ModelRegistry.clear_pipeline_cache(task, modelId);

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 205e9c2. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated 2 months ago
Other metadata
metadata
{
  "author": "huggingface",
  "repository": "https://github.com/huggingface/transformers.js"
}
compatibility
Node.js 20+ (or equivalent Bun / Deno), or a modern browser with ES modules. WebGPU requires runtime and hardware support; WASM is the fallback. Model downloads from the Hugging Face Hub require network access unless you ship models locally.

README badge

README badge for huggingface/transformers.js