Implementation:Langfuse Langfuse Shared Env Config

Knowledge Sources	Langfuse
Domains	Configuration, Environment
Last Updated	2026-02-14 00:00 GMT

Overview

Centralized environment variable configuration module that validates and exports all shared environment variables used across the Langfuse web and worker applications.

Description

This module defines a comprehensive Zod v4 schema (EnvSchema) that declares, validates, and provides defaults for every shared environment variable in the Langfuse platform. The schema covers configuration for Redis (including cluster and sentinel modes), ClickHouse (connection, performance tuning, deletion modes), S3/blob storage (event uploads, media uploads, exports), ingestion pipeline settings, logging, encryption, cache TTLs, webhook whitelisting, Slack integration, SSO claim mapping, AI features, dataset service feature flags, enterprise licensing, and ingestion masking.

On module load, the schema is parsed against process.env (with empty strings stripped via removeEmptyEnvVariables). During Docker builds (DOCKER_BUILD === "1"), validation is bypassed and process.env is used directly. The resulting validated object is exported as the singleton env, which is imported throughout the codebase for type-safe access to configuration values.

Usage

Import env from this module whenever you need to read a shared configuration value. The object is fully typed via SharedEnv, so IDE autocompletion and compile-time checks are available for every environment variable. Add new environment variables by extending the EnvSchema object with the appropriate Zod validator and default.

Code Reference

Source Location

Repository: Langfuse
File: packages/shared/src/env.ts
Lines: 1-316

Signature

const EnvSchema = z.object({
  NEXT_PUBLIC_LANGFUSE_CLOUD_REGION: z.string().optional(),
  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
  REDIS_HOST: z.string().nullish(),
  REDIS_PORT: z.coerce.number().positive().max(65536).default(6379).nullable(),
  CLICKHOUSE_URL: z.string().url(),
  CLICKHOUSE_USER: z.string(),
  CLICKHOUSE_PASSWORD: z.string(),
  ENCRYPTION_KEY: z.string().length(64).optional(),
  LANGFUSE_S3_EVENT_UPLOAD_BUCKET: z.string(),
  LANGFUSE_LOG_LEVEL: z.enum(["trace", "debug", "info", "warn", "error", "fatal"]).optional(),
  // ... 80+ additional environment variables
});

export type SharedEnv = z.infer<typeof EnvSchema>;

export const env: SharedEnv =
  process.env.DOCKER_BUILD === "1"
    ? (process.env as any)
    : EnvSchema.parse(removeEmptyEnvVariables(process.env));

Import

import { env } from "@langfuse/shared";
// or within the shared package:
import { env } from "../../env";

I/O Contract

Inputs

Name	Type	Required	Description
process.env	NodeJS.ProcessEnv	Yes	The raw environment variables from the runtime. Empty strings are stripped before validation.

Outputs

Name	Type	Description
env	SharedEnv	A fully validated and typed object containing all shared environment configuration values with defaults applied.

Usage Examples

import { env } from "@langfuse/shared";

// Access Redis configuration
const redisHost = env.REDIS_HOST;
const redisPort = env.REDIS_PORT; // number | null, defaults to 6379

// Check ClickHouse settings
const chUrl = env.CLICKHOUSE_URL;
const chCluster = env.CLICKHOUSE_CLUSTER_NAME; // defaults to "default"

// Check feature flags
if (env.LANGFUSE_S3_CORE_DATA_EXPORT_IS_ENABLED === "true") {
  // enable S3 export
}

// Access ingestion pipeline tuning
const queueDelay = env.LANGFUSE_INGESTION_QUEUE_DELAY_MS; // defaults to 15000
const shardCount = env.LANGFUSE_INGESTION_QUEUE_SHARD_COUNT; // defaults to 1

// Access log level
if (env.LANGFUSE_LOG_LEVEL === "debug") {
  // verbose logging
}

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment