# huggingface.js: the JavaScript SDK for the Hugging Face Hub and Inference Providers

> huggingface.js is a monorepo of TypeScript packages for creating repos, uploading files and calling hosted models from Node, Bun, Deno or the browser. It is convenient and typed, but it is a thin client over a hosted service you still have to pay for and operate.

**huggingface/huggingface.js** — Use Hugging Face with JavaScript

- Repository: https://github.com/huggingface/huggingface.js
- Website: https://hf.co/docs/huggingface.js
- Stars: 2,536 · Forks: 926
- Language: TypeScript
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/huggingface-huggingface-js

## What huggingface.js actually covers

The README describes the repository as "a collection of JS libraries to interact with the Hugging Face API, with TS types included". It is not one package. It is a pnpm workspace with separate packages for separate jobs: @huggingface/hub for repository operations, @huggingface/inference for model calls, @huggingface/mcp-client for a Model Context Protocol client and a small agent library, @huggingface/gguf for parsing GGUF files hosted remotely, @huggingface/dduf for the Diffusers Unified Format, @huggingface/tasks for the Hub's task and library definitions, @huggingface/jinja for chat templates, @huggingface/space-header, @huggingface/ollama-utils and @huggingface/tiny-agents.

That split matters more than the README's opening example suggests. If you only need to push a file to a repository, you install @huggingface/hub and nothing else. If you only need chat completions, you install @huggingface/inference. The packages are versioned independently, which the release list confirms: hub-v2.17.1, hub-v2.17.0 and jinja-v0.5.10 were published on separate dates. You can bump the Hub client without touching the templating package.

The intended audience is JavaScript and TypeScript developers who want Hub and inference operations inside an existing web or Node application rather than in a Python script. The README is explicit that the libraries "will only work on modern browsers / Node.js >= 18 / Bun / Deno", because the project uses modern language features instead of polyfills. That is a deliberate trade: fewer dependencies, no compatibility shims, and a hard floor on runtime versions.

## How the packages are layered

The dependency direction is visible in the package descriptions. @huggingface/inference exposes an InferenceClient. @huggingface/mcp-client is described as "a Model Context Protocol client, and a tiny Agent library, built on top of InferenceClient". So the agent layer does not talk to the network on its own; it sits on the inference client, which sits on HTTP calls to the Hub's routing endpoints or to a dedicated Inference Endpoint URL you supply.

The Hub package is a different axis. Its exports in the README are createRepo, commit, deleteRepo, listFiles, uploadFile, deleteFiles, plus the RepoId type. These are thin wrappers over Hub HTTP endpoints, which is why the same functions work in a browser tab and in a Node process without a server in between. The README notes that uploadFile can take "native File in browsers", so the content you upload can come straight from a file input.

The inference client accepts a provider argument. The README lists sambanova, together, fal-ai, replicate and cohere as options, and shows a textToImage call routed to replicate and another to fal-ai. The client also has an endpoint method that returns a client bound to a specific base URL, which is how you point at your own dedicated Inference Endpoint instead of the shared routing layer. The example shows both a raw endpoint URL and a router URL of the form https://router.huggingface.co/hf-inference/models/meta-llama/Llama-3.1-8B-Instruct. Those are the two shapes the documentation presents.

## Installing huggingface.js and making a first call

Install only the packages you need. The README shows three npm installs, and the root package.json declares pnpm as the package manager for the repository itself, which is a separate concern from how you consume the published packages.

```bash
npm install @huggingface/hub
npm install @huggingface/inference
npm install @huggingface/mcp-client
```

Then import from the installed packages. The README's import block is the shortest useful starting point, and it also shows that types ship with the packages rather than through a separate @types entry.

```ts
import { createRepo, commit, deleteRepo, listFiles } from "@huggingface/hub";
import { InferenceClient } from "@huggingface/inference";
import { McpClient } from "@huggingface/mcp-client";
import type { RepoId } from "@huggingface/hub";
```

For a first real call, construct the client with a token and call chatCompletion. The README directs you to the account settings page at https://huggingface.co/settings/tokens to get that token, and its examples use the placeholder string "hf_...".

```ts
import { InferenceClient } from "@huggingface/inference";

const client = new InferenceClient(HF_TOKEN);

const out = await client.chatCompletion({
  model: "meta-llama/Llama-3.1-8B-Instruct",
  messages: [{ role: "user", content: "Hello, nice to meet you!" }],
  max_tokens: 512
});
console.log(out.choices[0].message);
```

What you should see is the assistant message printed to the console. If you want tokens as they arrive instead of one final object, the README shows chatCompletionStream as an async iterable, where each chunk exposes chunk.choices[0].delta.content. If you want a specific backend, add provider: "sambanova" (or together, fal-ai, replicate, cohere) to the same call. The README also shows that model can be omitted for some tasks, using the recommended model for that task, as in its translation example.

If you would rather not bundle anything, the README gives a CDN path using jsDelivr with the +esm suffix, pinned to inference@4.13.28 and hub@2.17.1. Deno users get two options in the README: esm.sh URLs or npm: specifiers.

## Where huggingface.js is the wrong tool

The libraries are clients. Every inference call leaves your process and hits a hosted provider. If your requirement is to run a model on the machine, in-process, with no network round trip and no per-call billing, huggingface.js does not do that, and the README does not present it as doing that. The @huggingface/gguf package parses GGUF files that are hosted remotely; parsing is not execution.

The README also flags its own maturity: "The libraries are still very young, please help us by opening issues!". Treat that as a signal about API stability across minor versions rather than as modesty. The independent versioning of packages means a breaking change in the inference client does not force a Hub client upgrade, but it also means you should read release notes per package instead of assuming the monorepo moves as one unit.

There is a second, sharper limitation that the README does not address at all: token handling. The examples put HF_TOKEN directly into client construction, and the CDN example runs in a browser script tag. The documentation does not describe a browser-safe token exchange, a proxy pattern, or scoped short-lived credentials. If you ship an inference call from a client-side bundle with a real token in it, that token is exposed. Nothing in the README says otherwise, so plan to route inference through your own server if the token is not meant to be public.

Finally, the runtime floor is real. Node.js >= 18, Bun, Deno or a modern browser. If you maintain a build for an older runtime, this is not the library for that build.

## A real alternative and how the approach differs

The most direct alternative for the same job is calling the Hub's HTTP API directly with fetch, or using a general-purpose HTTP client. huggingface.js is a typed convenience layer over exactly that surface. The difference is not capability, since the underlying requests are the same, but where the maintenance burden sits. With raw fetch you own the request shapes, the response types and the endpoint URLs, and you get no compile-time checking of arguments like provider or repo type. With huggingface.js you get the RepoId type and typed method signatures, at the cost of tracking the library's release cadence.

A second comparison worth naming is the Python client, huggingface_hub. The README does not compare them, but the package split makes the intended parity clear: @huggingface/hub covers repository operations, and @huggingface/inference covers model calls, mirroring what a Python developer would reach for. The practical difference is ecosystem, not design. Python has the training and data tooling; JavaScript has the browser. If your code runs in a browser tab or in a Node service that already speaks TypeScript, the JS packages remove a language boundary. If your pipeline is already Python, adding a Node service to make the same calls is extra infrastructure for no gain.

One more distinction matters for anyone evaluating hosted inference: huggingface.js does not pick a provider for you in any documented way beyond the provider argument and the recommended-model behavior for some tasks. Provider selection, quotas and pricing live outside this repository, and the README does not document them.

## Maintenance, releases and the MIT licence

The repository is not archived, and its last push was on 2026-09-10. The most recent releases listed are hub-v2.17.1 on 2026-09-10, hub-v2.17.0 on 2026-09-07 and jinja-v0.5.10 on 2026-09-04. That release pattern tells you two things about upgrade cost. First, the Hub package moves in minor increments frequently, so pinning an exact version and reading the changelog before bumping is cheaper than tracking a floating range. Second, because packages release independently, an upgrade is scoped: a jinja bump does not imply a hub bump.

The repository is a pnpm workspace, declared as pnpm@10.10.0 in the root package.json, with a scripts section covering lint, format and a check-deps script run through tsx. That matters if you intend to fork or contribute rather than consume: you will be working inside a workspace with its own tooling, not a single-package repository. The root package.json is marked private, so the workspace root is not itself published.

The licence is MIT, stated in the repository's LICENSE file and in the root package.json. MIT is permissive: it allows use, modification and redistribution with the licence and copyright notice retained. That covers the library code. It does not cover the models you call through it. Model weights and spaces on the Hub carry their own licences, which the README does not discuss, and neither does it discuss the terms attached to third-party Inference Providers. Check those separately. Nothing here is legal advice.

## Conclusion

Adopt huggingface.js if your application already lives in JavaScript or TypeScript and you want typed access to the Hub and to hosted Inference Providers without writing your own HTTP layer. Skip it if you need to run models locally in-process, if you cannot accept a token in client-side code, or if your stack is Python and already served by huggingface_hub. Before committing, verify the Hub API is where you think it is, confirm the exact package version you will pin, and check the licence of every model you call through a provider.

## FAQ

### What is Hugging Face used for?

The README describes huggingface.js as a way to interact with the Hugging Face API: creating and deleting repositories, committing and downloading files, and calling supported serverless Inference Providers or dedicated Inference Endpoints. The repository itself is the JavaScript and TypeScript client for that platform.

### Is Hugging Face safe to use?

The README does not assess safety. What it does show is that the examples pass an HF_TOKEN directly into the client and that a CDN example runs inside a browser script tag, and it documents no browser-safe token exchange. Keep tokens out of client-side bundles.

### Why is it called Hugging Face?

The repository does not explain the origin of the name. It only gives the project name and the description "Use Hugging Face with JavaScript".

### Is Hugging Face a framework?

Not according to this repository. huggingface.js is described as a collection of JS libraries that interact with the Hugging Face API, with TypeScript types included, and it is split into separate packages such as @huggingface/hub and @huggingface/inference.

## Sources

- [huggingface/huggingface.js on GitHub](https://github.com/huggingface/huggingface.js)
- [License: MIT](https://github.com/huggingface/huggingface.js/blob/main/LICENSE)
- [Project website](https://hf.co/docs/huggingface.js)
- [README](https://github.com/huggingface/huggingface.js/blob/main/README.md)
- [Releases](https://github.com/huggingface/huggingface.js/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/huggingface-huggingface-js