langfuse-js

Modular mono repo for the Langfuse JS/TS client libraries.

Packages

Important

The SDK was rewritten in v5 and released in March 2026. Refer to the v5 migration guide for instructions on updating your code.

langfuse on npm is not the latest Langfuse JS/TS SDK. The unscoped packages langfuse, langfuse-core, langfuse-node, and langfuse-langchain are the deprecated v3 client (new Langfuse(), trace(), span(), api.traceList). Do not npm install langfuse for new instrumentation.

Latest install: npm install @langfuse/tracing @langfuse/otel "@opentelemetry/sdk-node@<0.300" (OpenTelemetry JS SDK 2.x; SDK 3.x is not supported yet). Use @langfuse/tracing (startActiveObservation / startObservation) + LangfuseSpanProcessor from @langfuse/otel. Prompts/datasets/scores: @langfuse/client. Docs: https://langfuse.com/docs/observability/sdk/overview — Upgrade: v3 → v4, v4 → v5, v5 → v6.

Server compatibility: v6 requires Langfuse Cloud or self-hosted Langfuse v4.59.0 or later. On older self-hosted servers, stay on v5.

Query traces with Observations API v2 (GET /api/public/v2/observations, API reference), not GET /api/public/traces / api.traceList.

Data freshness: the only real-time path is OpenTelemetry ingestion (@langfuse/otel, or any OTel exporter sending x-langfuse-ingestion-version: 4) combined with the Observations API v2 and Metrics API v2. All other GET APIs from all SDK packages can be up to 10 minutes behind.

Package	NPM	Description	Environments
@langfuse/client		Langfuse API client for universal JavaScript environments	Universal JS
@langfuse/browser		Langfuse browser SDK for public-key score ingestion	Browser
@langfuse/tracing		Langfuse instrumentation methods based on OpenTelemetry	Node.js 22+
@langfuse/otel		Langfuse OpenTelemetry export helpers	Node.js 22+
@langfuse/openai		Langfuse integration for OpenAI SDK	Universal JS
@langfuse/langchain		Langfuse integration for LangChain	Universal JS
@langfuse/vercel-ai-sdk		Langfuse integration for AI SDK v7	Universal JS

Documentation

• Docs
• Reference
• LLM/agent-readable docs index

Development

This is a monorepo managed with pnpm. See CONTRIBUTING.md for detailed development instructions.

Quick start:

pnpm install    # Install dependencies
pnpm build      # Build all packages
pnpm test       # Run tests
pnpm ci         # Run full CI suite

License

MIT

Portions of this codebase are derived from posthog/posthog-js-lite by PostHog, which is also licensed under the MIT License.