Environments

Overview

Environment variables are validated at startup using t3-oss/env with Zod schemas. If a required variable is missing or malformed, the app fails immediately with a clear error.

Shared env concerns live in their packages as prefix-agnostic factories — createAuthEnvConfig and createPaymentEnvConfig(runtimeEnv, { prefix }) — called by each host with its own env source and public-var prefix.

Prefix conventions

Only prefixed variables are exposed to the browser. Server-side variables without a prefix stay on the server.

Build-time vs runtime

Variables behave differently depending on how the app is built:

• Build-time (inlined): VITE_* and NEXT_PUBLIC_* variables are replaced with their values during the build step. They are baked into the JavaScript bundle and cannot be changed after build. This applies to the static apps (App, Editor, Web). For the API, PORT, BASE_PATH, and MIGRATIONS_PATH are also inlined at build time via esbuild define.
• Runtime (server): Variables without a prefix are read from process.env when the server process starts. They can be changed by editing the .env file and restarting the container. This applies to Docker-based apps (API, Docs).
• Runtime (injected): The Player's public config keeps the VITE_ prefix but is not inlined: the SSR host reads it from process.env at startup and forwards it to the browser via an injected bt-runtime-env JSON element (apps/player/src/lib/runtime-env.ts). See the Player section.

---

API (apps/api)

The API uses a split environment configuration:

• Build-time (build-env.ts): Infrastructure config inlined into the bundle via esbuild define in tsup.config.ts. Validated with Zod at build time.
• Runtime (env.ts): Secrets and per-environment config validated with t3-env at startup.

The migration entrypoint (migrate.ts) only depends on build-time config and DATABASE_URL, keeping it isolated from other service secrets.

Build-time (inlined)

Runtime (secrets)

Template: apps/api/.env.local

---

App (apps/app)

All variables are build-time (VITE_ prefixed) — inlined into the bundle during pnpm build:app. Auth and payment configs come from the shared factories (createAuthEnvConfig / createPaymentEnvConfig with import.meta.env and the VITE_ prefix — payment is provided to the tree via <PaymentProvider>); the app-specific variables are validated by a local Zod schema with defaults and parsing in-schema.

Core

App-specific

Stripe donation links

Build modes

Template: apps/app/.env.example

---

Learn (apps/learn)

The learner space. All variables are build-time (VITE_ prefixed), validated by src/lib/env.ts. The publishable key is the same Clerk instance as the App's: the session is shared across the parent domain.

Production values go in apps/learn/.env.production.local (gitignored). The API must list the app's origin in CORS_ORIGINS: checkout and portal return URLs are validated against the same list.

Template: apps/learn/.env.example

---

Web (apps/web)

All variables are build-time (NEXT_PUBLIC_ prefixed) — inlined during next build. The Stripe vars are read server-side by @workspace/payment/service-nextjs during prerender and passed to client components as props, so they must be present at build time.

Template: apps/web/.env.example

---

Player (apps/player)

Two distinct halves — see apps/player/.env.example for the full annotated list:

Build-time (inlined)

Runtime (SSR host)

Read from process.env when the SSR host starts. In production these live in the remote deploy dir's .env (compose env_file), not in the image — changing them is a container restart, not a rebuild. Public VITE_* values are forwarded to the browser via the injected bt-runtime-env JSON element; the plain Vite dev server has no SSR host, so the client falls back to import.meta.env in dev.

Static build (legacy host)

The legacy host has no runtime .env: pnpm release:player-legacy builds in Vite's legacy mode, which reads apps/player/.env.legacy (committed defaults: base path, API base, ads on, demo and debug off) then apps/player/.env.legacy.local (gitignored: deal API key, Ezoic site, Axiom, telemetry, Clerk key…) and bakes every value into the bundle, so changing one is a re-release. The runtime keys above are set the same way for that host — VITE_CLERK_PUBLISHABLE_KEY among them; left empty, every player of the static bundle reads anonymously.

Which file for which build

.env.deploy only knows hosts, remote dirs, ports and image names.

Template: apps/player/.env.example

---

Database (packages/database)

Used by Drizzle Kit and Supabase CLI for migrations and local development.

Template: packages/database/.env (committed, local Supabase). Its .env.production (template .env.production.example) serves drizzle-kit against production only; the operations on production data read apps/cli/.env.production.local (CLI).

---

Translations (apps/admin)

The translations tool lives in the Admin app (apps/admin), which mixes build-time (NEXT_PUBLIC_ prefixed) and runtime server variables. Validated with @t3-oss/env-nextjs. Uses a GitHub App for branch/PR management.

Auth

GitHub App

Translations

Template: apps/admin/.env.example

---

CLI (apps/cli)

Operations CLI (pnpm cli <command>). The global --env local|prod picks the files it loads from apps/cli: .env.local for local (the default), .env.production.local then .env.production for prod. A variable set in the shell wins over the files. Each command validates only the variables of the adapters it uses.

Templates: apps/cli/.env.example (local), apps/cli/.env.production.example (prod)

The production credentials of the operations live in apps/cli/.env.production.local, gitignored like every .env* of apps/cli but the templates; the former packages/database ops scripts are commands here now (#1774), so their :prod env no longer serves them. The commands whose services take a ServiceContext get it from the global --actor <accountId>, never from the env.

---

Deploy (/.env.deploy)

Used by release scripts only. See Deployment for details.

Override locally with .env.deploy.local (gitignored).

---

Validation schemas

Schemas are colocated with the packages that own the concern: