Implementation:Langfuse Langfuse Web Env Config

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

Overview

This module defines and validates all environment variables for the Langfuse Next.js web application using the T3 Env library with Zod schemas, providing type-safe access to server-side and client-side configuration.

Description

The env.mjs file uses @t3-oss/env-nextjs with Zod validation schemas to create a single, type-safe env object that is the canonical source of all environment variable access in the web application. The file is structured into three sections:

Server-side variables (not exposed to the browser) include:

• Core infrastructure: DATABASE_URL, CLICKHOUSE_URL/USER/PASSWORD/DB, NODE_ENV, SALT, ENCRYPTION_KEY.
• Authentication (NextAuth.js): NEXTAUTH_SECRET, NEXTAUTH_URL, NEXTAUTH_COOKIE_DOMAIN, AUTH_SESSION_MAX_AGE (default 30 days), AUTH_DISABLE_USERNAME_PASSWORD, AUTH_DISABLE_SIGNUP.
• OAuth/SSO providers: Comprehensive configuration for Google, GitHub, GitHub Enterprise, GitLab, Azure AD, Okta, Authentik, OneLogin, Auth0, Cognito, Keycloak, JumpCloud, WorkOS, WordPress, and a custom OIDC provider. Each provider has CLIENT_ID, CLIENT_SECRET, ALLOW_ACCOUNT_LINKING, CLIENT_AUTH_METHOD (defaulting to client_secret_basic), and CHECKS (supporting nonce, none, pkce, state).
• S3/MinIO media storage: LANGFUSE_S3_MEDIA_UPLOAD_BUCKET, region, endpoint, credentials, SSE configuration, content length limits, and download URL expiry.
• OpenTelemetry: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, OTEL_TRACE_SAMPLING_RATIO.
• Email: EMAIL_FROM_ADDRESS, SMTP_CONNECTION_URL.
• EE (Enterprise Edition): LANGFUSE_EE_LICENSE_KEY, ADMIN_API_KEY, UI customization variables (logo, documentation/support/feedback URLs, default model adapter).
• Feature flags and performance: LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES, LANGFUSE_SKIP_FINAL_FOR_OTEL_PROJECTS, LANGFUSE_API_CLICKHOUSE_PROPAGATE_OBSERVATIONS_TIME_BOUNDS, events table migration flags, query optimization shadow testing.
• Integrations: Stripe, Sentry, Slack, Plain (support), PostHog, and Langfuse AI features (natural language filters).
• Provisioning: LANGFUSE_INIT_* variables for bootstrapping orgs, projects, and users.
• Default org/project assignment: LANGFUSE_DEFAULT_ORG_ID (supports comma-separated IDs), LANGFUSE_DEFAULT_ORG_ROLE, LANGFUSE_DEFAULT_PROJECT_ID, LANGFUSE_DEFAULT_PROJECT_ROLE.

Client-side variables (prefixed with NEXT_PUBLIC_) include:

• NEXT_PUBLIC_LANGFUSE_CLOUD_REGION (US, EU, STAGING, DEV, HIPAA).
• NEXT_PUBLIC_DEMO_PROJECT_ID, NEXT_PUBLIC_DEMO_ORG_ID.
• NEXT_PUBLIC_SIGN_UP_DISABLED, NEXT_PUBLIC_BASE_PATH.
• PostHog analytics keys, Plain app ID, playground streaming default.

Runtime env mapping: The runtimeEnv section destructures process.env for each variable, with fallback handling for renamed variables (e.g., AUTH_AZURE_AD_* falls back to legacy AUTH_AZURE_*).

Validation is skipped during Docker builds (DOCKER_BUILD === "1") and empty strings are treated as undefined.

Usage

Use the exported env object whenever you need to access an environment variable in the web application. Always import from this module rather than reading process.env directly to ensure type safety and validation.

Code Reference

Source Location

• Repository: Langfuse
• File: web/src/env.mjs
• Lines: 1-740

Signature

import { createEnv } from "@t3-oss/env-nextjs";

export const env = createEnv({
  server: {
    DATABASE_URL: z.string().url(),
    NODE_ENV: z.enum(["development", "test", "production"]),
    NEXTAUTH_SECRET: z.string().min(1),
    NEXTAUTH_URL: z.preprocess(...),
    SALT: z.string(),
    CLICKHOUSE_URL: z.string().url(),
    CLICKHOUSE_USER: z.string(),
    CLICKHOUSE_PASSWORD: z.string(),
    // ... 100+ additional server variables
  },
  client: {
    NEXT_PUBLIC_LANGFUSE_CLOUD_REGION: z.enum(["US", "EU", "STAGING", "DEV", "HIPAA"]).optional(),
    NEXT_PUBLIC_BASE_PATH: z.string().optional(),
    // ... additional client variables
  },
  runtimeEnv: { /* maps process.env to schema keys */ },
  skipValidation: process.env.DOCKER_BUILD === "1",
  emptyStringAsUndefined: true,
});

Import

import { env } from "@/src/env.mjs";

I/O Contract

Inputs

Name	Type	Required	Description
DATABASE_URL	string (URL)	Yes	PostgreSQL connection string
NODE_ENV	"test" | "production"	Yes	Node.js environment
NEXTAUTH_SECRET	string	Yes (production)	Secret for NextAuth.js JWT signing
NEXTAUTH_URL	string (URL)	Yes	Base URL for NextAuth.js callbacks
SALT	string	Yes	Encryption salt for API key hashing
CLICKHOUSE_URL	string (URL)	Yes	ClickHouse server URL
CLICKHOUSE_USER	string	Yes	ClickHouse authentication user
CLICKHOUSE_PASSWORD	string	Yes	ClickHouse authentication password
AUTH_*_CLIENT_ID	string	No	OAuth provider client ID (per provider)
AUTH_*_CLIENT_SECRET	string	No	OAuth provider client secret (per provider)
LANGFUSE_EE_LICENSE_KEY	string	No	Enterprise Edition license key
ENCRYPTION_KEY	string (64 hex chars)	No	256-bit encryption key for sensitive data
LANGFUSE_S3_MEDIA_UPLOAD_BUCKET	string	No	S3 bucket for media uploads
NEXT_PUBLIC_LANGFUSE_CLOUD_REGION	"EU" | "STAGING" | "DEV" | "HIPAA"	No	Cloud region identifier (client-side)
NEXT_PUBLIC_BASE_PATH	string	No	Custom base path for the web application

Outputs

Name	Type	Description
env	object	Type-safe object with all validated environment variables accessible as properties (e.g. env.DATABASE_URL, env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION)

Usage Examples

import { env } from "@/src/env.mjs";

// Access server-side variables
const dbUrl = env.DATABASE_URL;
const isProduction = env.NODE_ENV === "production";

// Access ClickHouse configuration
const chConfig = {
  url: env.CLICKHOUSE_URL,
  user: env.CLICKHOUSE_USER,
  password: env.CLICKHOUSE_PASSWORD,
  database: env.CLICKHOUSE_DB,
};

// Check for optional features
if (env.LANGFUSE_EE_LICENSE_KEY) {
  // Enable enterprise features
}

// Check authentication provider availability
if (env.AUTH_GOOGLE_CLIENT_ID && env.AUTH_GOOGLE_CLIENT_SECRET) {
  // Configure Google OAuth provider
}

// Access client-side variables (available in browser)
const cloudRegion = env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION;
const basePath = env.NEXT_PUBLIC_BASE_PATH ?? "";

Related Pages

• Environment:Langfuse_Langfuse_Node_24_Runtime