Langfuse JS/TS SDK (@langfuse/client)

@langfuse/client is the primary data-plane SDK for Langfuse, the open-source LLM engineering platform. It ships a single LangfuseClient class that wraps the full generated Langfuse REST API behind typed managers for prompt management, dataset and experiment operations, evaluation scores, and media uploads — everything except tracing, which lives in the separate @langfuse/tracing and @langfuse/otel packages by design.

Under langfuse.prompt, teams fetch, cache, compile, and version prompts with variable substitution and chat placeholders. langfuse.dataset and langfuse.experiment combine to run tasks and evaluators over versioned test sets, including built-in support for AutoEvals evaluators and automatic tracing of experiment runs. langfuse.score records evaluation and user-feedback scores against traces and observations, and langfuse.media handles upload and reference resolution for images, audio, and other attachments referenced from traces. Released as part of the v5 SDK rewrite (March 2026), it targets universal JavaScript environments (Node, edge, browser) and supersedes the legacy unscoped langfuse v3 package.

What You Get

• A typed LangfuseClient wrapping the complete generated Langfuse REST API
• Prompt management with caching, compilation, and chat/text prompt versioning
• Dataset and experiment runners with built-in AutoEvals evaluator support
• Score creation for evaluation and user-feedback pipelines with explicit flush control
• Media upload and reference resolution for trace attachments

Common Use Cases

• Fetching and compiling versioned prompts at request time in a Node.js API
• Running offline experiments over a Langfuse dataset with custom evaluators before deploying a prompt change
• Recording user-feedback or LLM-judge scores back onto production traces
• Uploading and linking media (images, audio, PDFs) referenced from LLM traces

Under The Hood

Architecture The package follows a manager-composition pattern: LangfuseClient (packages/client/src/LangfuseClient.ts) is a thin facade that instantiates five focused managers — PromptManager, DatasetManager, ExperimentManager, ScoreManager, MediaManager — each wrapping a shared LangfuseAPIClient imported from the sibling @langfuse/core package, which itself holds the generated REST client, logger, and env-var resolution shared across the whole langfuse-js monorepo. Cross-cutting concerns are pushed out into @langfuse/core and the separate @langfuse/tracing/@langfuse/otel packages, so consumers can adopt tracing independently of the data-plane client; @langfuse/client itself carries no HTTP or OpenTelemetry logic of its own — it only composes and re-exports typed operations (promptManager.ts wraps prompt CRUD plus a TTL-based LangfusePromptCache, ExperimentManager.ts composes RunnerContext and adapters.ts to bridge into AutoEvals evaluators). This gives a clean separation of concerns, enforced by the turborepo build graph across the monorepo’s eight sibling packages; the one abstraction with the widest blast radius if changed is the generated API client in @langfuse/core, since every manager constructs its requests through it.

Tech Stack TypeScript throughout (over 99% of the repo by bytes), built with tsup into dual ESM/CJS bundles with generated .d.ts/.d.cts types, and tested with vitest across three tiers (tests/unit, tests/integration, tests/e2e). The monorepo is a pnpm workspace orchestrated by turbo.json for incremental, parallel builds across its packages (client, core, tracing, otel, openai, langchain, vercel-ai-sdk, browser). @langfuse/client depends on @langfuse/core and @langfuse/tracing as workspace packages, plus mustache for prompt template compilation, with @opentelemetry/api as a peer dependency bridging to the tracing packages. Docs are generated via typedoc from inline JSDoc, releases are automated with release-it, and linting/formatting run through ESLint and Prettier enforced via Husky pre-commit hooks. Node 20.19+/22.13+/24+ is required.

Code Quality The client package has no test files colocated with its source — tests live centrally under the repo-root tests/ directory, split into tests/unit (e.g. LangfuseClient.test.ts, ExperimentManager.test.ts, dataset.test.ts, mediaUpload.test.ts), tests/integration (real calls against a local Langfuse instance covering scores, tracing, and propagation), and tests/e2e (full workflows such as datasets.e2e.test.ts, prompts.e2e.test.ts, experiments.e2e.test.ts) — giving three-tier coverage rather than unit-only testing. CI runs all three tiers as separate jobs on every PR and push, alongside linting. The code carries extensive TSDoc/JSDoc annotations with @param, @example, and @see tags throughout the public API, strict TypeScript typing is used across the surface, and ESLint plus Prettier enforce style pre-commit.

API Design The public surface is deliberately narrow and discoverable: new LangfuseClient() reads credentials from environment variables with zero required constructor arguments, and every capability hangs off one of five named properties (.prompt, .dataset, .experiment, .score, .media) plus an escape hatch (.api) to the fully generated REST client for anything the high-level managers don’t cover. Every public class and method carries a TSDoc block with runnable @example snippets that double as the source for the published TypeDoc reference site. The deliberate split of tracing into companion packages keeps this package’s dependency footprint small for teams that only need prompts, datasets, and scores, at the cost of an extra install for teams that want both — and the linked v3→v4→v5 migration guides acknowledge the API has shifted across major versions, the main friction point for adopters coming from the legacy SDK.