ollama-js

Ollama-js is the official JavaScript and TypeScript client for the Ollama API, giving Node.js and browser applications typed access to large language models running through the Ollama server. It wraps every core endpoint — chat, generate, create, pull, push, embed, and more — behind a single Ollama class, with matching streaming and non-streaming overloads for each method.

Beyond local inference, the library also talks to Ollama’s hosted cloud API at ollama.com, letting the same client code offload larger models to the cloud by swapping the host and adding an API key. A Node-specific subclass adds local file handling for image inputs and model creation, while a lightweight browser build keeps the footprint minimal for client-side use.

What You Get

• A single Ollama client class covering chat, generate, create, pull, push, copy, delete, list, show, embed, and ps endpoints
• Matching streaming and non-streaming TypeScript overloads for every request method, backed by an AbortableAsyncIterator
• A custom ResponseError class carrying the HTTP status code for structured error handling
• Separate Node and browser entry points, with the Node build adding local file-based image and model handling
• Direct access to Ollama’s hosted cloud API (ollama.com) for offloading larger models without changing client code

Common Use Cases

• Building a local chatbot or coding assistant against models running on a developer’s own machine
• Streaming token-by-token chat or generate responses into a CLI or web UI
• Generating text embeddings for retrieval-augmented generation (RAG) pipelines
• Offloading larger models to Ollama’s cloud API when local hardware isn’t enough
• Managing the local model library programmatically — pulling, listing, copying, and deleting models from scripts

Under The Hood

Architecture The library is built around a single Ollama class defined in src/browser.ts, which every request method (chat, generate, embed, pull, push, etc.) funnels through a shared processStreamableRequest helper — this one method decides whether to return a plain JSON response or wrap the response body in an AbortableAsyncIterator (from src/utils.ts) depending on the request’s stream flag, so every endpoint gets streaming support for free. A Node-specific Ollama subclass in src/index.ts extends the browser class to add filesystem-aware behavior — resolving local image paths to base64 and rejecting local-path model creation — while the browser entry point stays dependency-light. Configuration (host, custom fetch implementation, headers) is injected through the constructor rather than read from globals, so a single fetch swap is enough to redirect the client at a proxy, mock server, or Ollama’s own cloud endpoint.

Tech Stack Written in strict TypeScript and built with unbuild into dual ESM/CommonJS bundles (dist/index.mjs / dist/index.cjs) plus generated .d.ts type declarations, so it works from both import and require call sites. The only runtime dependency is whatwg-fetch, a fetch polyfill for browser environments; everything else (typed request/response interfaces, the streaming NDJSON parser, header normalization) is hand-written rather than pulled from a third-party HTTP client. Tests run on Vitest, linting on ESLint with the TypeScript plugin, and formatting on Prettier.

Code Quality A test/ directory covers the browser client, Node client, and utility functions with Vitest, using vi.spyOn to assert that request options (model, streaming flags, logprobs, tool calls) are forwarded correctly to the underlying transport rather than hitting a live server — a reasonable unit-level substitute for integration tests. Errors surface as a dedicated ResponseError class carrying both a message and the original HTTP status code, rather than being swallowed or re-thrown as generic Errors. tsconfig.json enables strict mode with strictNullChecks, and CI (.github/workflows/test.yaml) runs the test suite on every change, with a separate publish.yaml workflow handling npm releases.

API Design The public surface mirrors the Ollama HTTP API almost one-to-one — chat(), generate(), pull(), embed(), and friends each take a single typed request object and return either the full response or a stream, selected purely by a stream boolean, so callers don’t need two different client shapes for the two modes. Getting started requires only new Ollama() and one call; more advanced features (tool calling via a tools array, JSON-constrained output via format, reasoning depth via think, and per-token logprobs) are opt-in fields on the same request objects rather than separate methods, keeping the API surface small while still exposing the full range of the underlying server’s capabilities.