Where to Find Environment Variable Definitions for Logto: A Complete Guide

Logto environment variable definitions are centralized in packages/shared/src/node/env/GlobalValues.ts for server-side configuration and mapped through Vite configurations in packages/console/vite.config.ts and packages/experience/vite.config.ts for client-side build-time variables, with a root .env.example file serving as the authoritative template.

Logto does not store all environment variables in a single configuration file. Instead, the open-source identity platform scatters definitions across typed TypeScript classes and build configuration files. Understanding exactly where Logto environment variable definitions live is essential for customizing deployments, extending functionality, or troubleshooting configuration issues.

Server-Side Environment Variable Definitions

Server-side variables are type-safe and centralized in the shared package.

The GlobalValues Class in packages/shared/src/node/env/GlobalValues.ts

The GlobalValues class serves as the single source of truth for core server configuration. This TypeScript file defines a class whose public read-only properties map directly to expected environment variables via process.env lookups.

// packages/shared/src/node/env/GlobalValues.ts
export class GlobalValues {
  public readonly httpsCert = process.env.HTTPS_CERT_PATH;
  public readonly httpsKey = process.env.HTTPS_KEY_PATH;
  public readonly posthogPublicKey = process.env.POSTHOG_PUBLIC_KEY;
  public readonly posthogPublicHost = process.env.POSTHOG_PUBLIC_HOST;
  // Additional core configuration properties...
}

Instantiating this class creates a typed configuration object that the Logto core server uses to access environment variables throughout the application lifecycle.

Accessing Server Variables in Code

To use these definitions in your implementation, import the class from the shared package and instantiate it:

import { GlobalValues } from '@logto/shared/node/env';

const env = new GlobalValues();

if (env.httpsCert && env.httpsKey) {
  // Configure HTTPS server with the provided certificate and key
}

Client-Side Environment Variable Definitions

Front-end applications in Logto receive environment variables at build time through Vite's define configuration.

Console Application Configuration (packages/console/vite.config.ts)

The Console application (the administrative web interface) receives its environment variables through the Vite configuration file located at packages/console/vite.config.ts. This file explicitly maps process.env entries to import.meta.env constants using the define option:

// packages/console/vite.config.ts
export default defineConfig({
  define: {
    'import.meta.env.IS_CLOUD': JSON.stringify(process.env.IS_CLOUD),
    'import.meta.env.ADMIN_ENDPOINT': JSON.stringify(process.env.ADMIN_ENDPOINT),
    'import.meta.env.DEV_FEATURES_ENABLED': JSON.stringify(process.env.DEV_FEATURES_ENABLED),
    'import.meta.env.CONSOLE_PUBLIC_URL': JSON.stringify(process.env.CONSOLE_PUBLIC_URL),
    'import.meta.env.POSTHOG_PUBLIC_KEY': JSON.stringify(process.env.POSTHOG_PUBLIC_KEY),
    'import.meta.env.LOGTO_OSS_SURVEY_ENDPOINT': JSON.stringify(process.env.LOGTO_OSS_SURVEY_ENDPOINT),
  },
});

Experience Application Configuration (packages/experience/vite.config.ts)

The Experience application (the end-user authentication flows) follows an identical pattern in packages/experience/vite.config.ts. This ensures the sign-in experience receives its own subset of environment variables at build time, maintaining separation between the admin console and user-facing components.

Accessing Client Variables in Code

Within the frontend applications, access these variables through the globally available import.meta.env object:

// In any Vite-built component
const apiBase = import.meta.env.ADMIN_ENDPOINT; // e.g., "http://localhost:3002"
const isCloud = import.meta.env.IS_CLOUD === 'true';

Specialized Environment Variable Locations

Beyond the central definitions, Logto defines specific environment variables near their consumption points.

Translation and Proxy Utilities

In packages/translate/src/utils.ts, the application directly accesses proxy configuration:

// Direct process.env access for proxy settings
const httpsProxy = process.env.HTTPS_PROXY;
const httpProxy = process.env.HTTP_PROXY;

OpenAI Integration Keys

The translation service in packages/translate/src/openai.ts retrieves API credentials directly from the environment:

// packages/translate/src/openai.ts
const apiKey = process.env.OPENAI_API_KEY;
const modelName = process.env.OPENAI_MODEL_NAME;

Integration Testing Flags

Located in packages/toolkit/core-kit/src/utils/integration-test.ts, this file defines flags used specifically during automated testing scenarios, separating test configuration from production variables.

The .env.example Configuration Template

While not a definition file per se, the root .env.example serves as the documentation source and template for all supported variables. Developers copy this file to .env and populate values according to their deployment needs. This file contains placeholder entries for all variables referenced in GlobalValues.ts, the Vite configurations, and specialized utility files.

Summary

• Server-side definitions: Located in packages/shared/src/node/env/GlobalValues.ts within the GlobalValues class that maps process.env to typed properties
• Client-side definitions: Configured in packages/console/vite.config.ts and packages/experience/vite.config.ts using Vite's define option to inject process.env values into import.meta.env
• Specialized variables: Scattered in utility files like packages/translate/src/utils.ts (proxy settings), packages/translate/src/openai.ts (AI credentials), and packages/toolkit/core-kit/src/utils/integration-test.ts (test flags)
• Configuration template: The root .env.example file lists all available variables with documentation for local development setup

Frequently Asked Questions

Where is the main file that defines Logto environment variables for the core server?

The primary definition file is packages/shared/src/node/env/GlobalValues.ts. This TypeScript file contains the GlobalValues class that explicitly declares all core server environment variables as public read-only properties, creating a type-safe interface to process.env.

How do client-side applications in Logto access environment variables?

Client-side applications access variables through import.meta.env after the build process injects them. The Vite configuration files (packages/console/vite.config.ts and packages/experience/vite.config.ts) map process.env entries to import.meta.env using the define configuration option, making them available to the frontend code at runtime.

What is the difference between how server-side and client-side variables are defined in Logto?

Server-side variables are defined in the GlobalValues class which actively reads from process.env at runtime, while client-side variables are statically injected at build time by Vite's configuration. Server-side definitions support dynamic configuration changes on server restart, whereas client-side variables are baked into the JavaScript bundle during the build process.

Where should I look to understand what environment variables are available for configuration?

Consult the root .env.example file for a complete list of supported variables with placeholder values and comments. For implementation details on how specific variables are used, examine packages/shared/src/node/env/GlobalValues.ts for server configuration and the respective vite.config.ts files for frontend applications.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}