Coldstart generates a packages/env/ package with Zod-validated environment variables using @t3-oss/env. Every variable is validated at startup — if a required variable is missing or malformed, the app fails immediately with a clear error message.

Architecture

packages/env/
├── src/
│   ├── server.ts    # API env vars (@t3-oss/env-nextjs or @t3-oss/env-core)
│   ├── web.ts       # Web env vars (@t3-oss/env-nextjs)
│   └── native.ts    # Mobile env vars (plain Zod schema)
├── package.json
└── tsconfig.json

Each platform imports its own env module:

Usage in apps

// In apps/api
import { env } from "@scope/env/server";

// In apps/web
import { env } from "@scope/env/web";

// In apps/mobile
import { env } from "@scope/env/native";

Variables by platform

Core variables (always generated)

Variable	Zod Schema	Required	Description
`NODE_ENV`	`z.enum(["development", "production", "test"]).default("development")`	No	Runtime environment
`DATABASE_URL`	`z.string().url()`	Yes	PostgreSQL connection string (Neon)
`BETTER_AUTH_SECRET`	`z.string().min(32)`	Yes	Auth signing secret (32+ chars)
`BETTER_AUTH_URL`	`z.string().url()`	Yes	Auth base URL (API URL)

OAuth variables (per provider)

Generated for each OAuth provider selected:

Variable	Zod Schema	Required	Condition
`GOOGLE_CLIENT_ID`	`z.string().min(1)`	Yes	Google OAuth enabled
`GOOGLE_CLIENT_SECRET`	`z.string().min(1)`	Yes	Google OAuth enabled
`GITHUB_CLIENT_ID`	`z.string().min(1)`	Yes	GitHub OAuth enabled
`GITHUB_CLIENT_SECRET`	`z.string().min(1)`	Yes	GitHub OAuth enabled
`APPLE_CLIENT_ID`	`z.string().min(1)`	Yes	Apple OAuth enabled
`APPLE_CLIENT_SECRET`	`z.string().min(1)`	Yes	Apple OAuth enabled

Billing variables (Stripe)

Variable	Zod Schema	Required	Condition
`STRIPE_SECRET_KEY`	`z.string().startsWith("sk_")`	Yes	Stripe billing
`STRIPE_WEBHOOK_SECRET`	`z.string().startsWith("whsec_")`	Yes	Stripe billing

Billing variables (Polar)

Variable	Zod Schema	Required	Condition
`POLAR_ACCESS_TOKEN`	`z.string().min(1)`	Yes	Polar billing
`POLAR_WEBHOOK_SECRET`	`z.string().min(1)`	Yes	Polar billing

Mobile billing (RevenueCat webhook)

Variable	Zod Schema	Required	Condition
`REVENUECAT_WEBHOOK_AUTH_KEY`	`z.string().min(1)`	Yes	Billing + mobile platform

Full Zod schema

packages/env/src/server.ts (Stripe + Google OAuth example)

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

export const env = createEnv({
  server: {
    NODE_ENV: z.enum(["development", "production", "test"]).default("development"),
    DATABASE_URL: z.string().url(),
    BETTER_AUTH_SECRET: z.string().min(32),
    BETTER_AUTH_URL: z.string().url(),
    GOOGLE_CLIENT_ID: z.string().min(1),
    GOOGLE_CLIENT_SECRET: z.string().min(1),
    STRIPE_SECRET_KEY: z.string().startsWith("sk_"),
    STRIPE_WEBHOOK_SECRET: z.string().startsWith("whsec_"),
  },
  client: {},
  runtimeEnv: {
    NODE_ENV: process.env.NODE_ENV,
    DATABASE_URL: process.env.DATABASE_URL,
    BETTER_AUTH_SECRET: process.env.BETTER_AUTH_SECRET,
    BETTER_AUTH_URL: process.env.BETTER_AUTH_URL,
    GOOGLE_CLIENT_ID: process.env.GOOGLE_CLIENT_ID,
    GOOGLE_CLIENT_SECRET: process.env.GOOGLE_CLIENT_SECRET,
    STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY,
    STRIPE_WEBHOOK_SECRET: process.env.STRIPE_WEBHOOK_SECRET,
  },
});

Core variables

Variable	Zod Schema	Required	Description
`NODE_ENV`	`z.enum(["development", "production", "test"]).default("development")`	No	Runtime environment
`NEXT_PUBLIC_API_URL`	`z.string().url().optional()`	No	API base URL

Billing variables (Stripe)

Variable	Zod Schema	Required	Condition
`NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`	`z.string().startsWith("pk_").optional()`	No	Stripe billing

Analytics variables

Variable	Zod Schema	Required	Condition
`NEXT_PUBLIC_POSTHOG_KEY`	—	No	Analytics enabled
`NEXT_PUBLIC_POSTHOG_HOST`	—	No	Analytics enabled

PostHog variables are used directly via process.env in the PostHog init code, not through the @t3-oss/env schema. PostHog gracefully handles missing keys by not initializing.

Full Zod schema

packages/env/src/web.ts (Stripe example)

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

export const env = createEnv({
  server: {
    NODE_ENV: z.enum(["development", "production", "test"]).default("development"),
  },
  client: {
    NEXT_PUBLIC_API_URL: z.string().url().optional(),
    NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: z.string().startsWith("pk_").optional(),
  },
  runtimeEnv: {
    NODE_ENV: process.env.NODE_ENV,
    NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
    NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY,
  },
});

Core variables

Variable	Zod Schema	Required	Description
`EXPO_PUBLIC_API_URL`	`z.string().url().optional()`	No	API base URL

Billing variables (RevenueCat)

Variable	Zod Schema	Required	Condition
`EXPO_PUBLIC_REVENUECAT_IOS_KEY`	`z.string().optional()`	No	Billing enabled
`EXPO_PUBLIC_REVENUECAT_ANDROID_KEY`	`z.string().optional()`	No	Billing enabled

Analytics variables

Variable	Zod Schema	Required	Condition
`EXPO_PUBLIC_POSTHOG_KEY`	—	No	Analytics enabled
`EXPO_PUBLIC_POSTHOG_HOST`	—	No	Analytics enabled

Full Zod schema

Mobile uses a plain Zod schema (not @t3-oss/env) because Expo doesn't support the Next.js env pattern:

packages/env/src/native.ts (with billing)

import { z } from "zod";

const schema = z.object({
  EXPO_PUBLIC_API_URL: z.string().url().optional(),
  EXPO_PUBLIC_REVENUECAT_IOS_KEY: z.string().optional(),
  EXPO_PUBLIC_REVENUECAT_ANDROID_KEY: z.string().optional(),
});

export const env = schema.parse({
  EXPO_PUBLIC_API_URL: process.env.EXPO_PUBLIC_API_URL,
  EXPO_PUBLIC_REVENUECAT_IOS_KEY: process.env.EXPO_PUBLIC_REVENUECAT_IOS_KEY,
  EXPO_PUBLIC_REVENUECAT_ANDROID_KEY: process.env.EXPO_PUBLIC_REVENUECAT_ANDROID_KEY,
});

.env file locations

Each app has its own .env file. Coldstart generates .env.example files with placeholder values:

File	Used by	Git-tracked
`apps/api/.env`	API server	No (in `.gitignore`)
`apps/api/.env.example`	Reference	Yes
`apps/web/.env`	Next.js web app	No (in `.gitignore`)
`apps/web/.env.example`	Reference	Yes
`apps/mobile/.env`	Expo mobile app	No (in `.gitignore`)
`apps/mobile/.env.example`	Reference	Yes

How startup validation works

The env validation runs at import time. When your app starts and imports @scope/env/server, the Zod schema validates every variable immediately:

❌ Invalid environment variables:
  DATABASE_URL: Required
  BETTER_AUTH_SECRET: String must contain at least 32 character(s)
  STRIPE_SECRET_KEY: Invalid input: must start with "sk_"

This fail-fast approach catches configuration errors before any request is served.

If your API fails to start with env validation errors, check that all required variables are set in apps/api/.env. Copy from .env.example as a starting point.

Which variables depend on features

Not all variables are always generated. The env schema adapts to your project configuration:

Quick reference: all variables

Variable	Platform	Condition	Required
`NODE_ENV`	API, Web	Always	No (defaults to development)
`DATABASE_URL`	API	Always	Yes
`BETTER_AUTH_SECRET`	API	Always	Yes
`BETTER_AUTH_URL`	API	Always	Yes
`GOOGLE_CLIENT_ID`	API	Google OAuth	Yes
`GOOGLE_CLIENT_SECRET`	API	Google OAuth	Yes
`GITHUB_CLIENT_ID`	API	GitHub OAuth	Yes
`GITHUB_CLIENT_SECRET`	API	GitHub OAuth	Yes
`APPLE_CLIENT_ID`	API	Apple OAuth	Yes
`APPLE_CLIENT_SECRET`	API	Apple OAuth	Yes
`STRIPE_SECRET_KEY`	API	Stripe billing	Yes
`STRIPE_WEBHOOK_SECRET`	API	Stripe billing	Yes
`POLAR_ACCESS_TOKEN`	API	Polar billing	Yes
`POLAR_WEBHOOK_SECRET`	API	Polar billing	Yes
`REVENUECAT_WEBHOOK_AUTH_KEY`	API	Billing + mobile	Yes
`NEXT_PUBLIC_API_URL`	Web	Always	No
`NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`	Web	Stripe billing	No
`NEXT_PUBLIC_POSTHOG_KEY`	Web	Analytics	No
`NEXT_PUBLIC_POSTHOG_HOST`	Web	Analytics	No
`EXPO_PUBLIC_API_URL`	Mobile	Always	No
`EXPO_PUBLIC_REVENUECAT_IOS_KEY`	Mobile	Billing	No
`EXPO_PUBLIC_REVENUECAT_ANDROID_KEY`	Mobile	Billing	No
`EXPO_PUBLIC_POSTHOG_KEY`	Mobile	Analytics	No
`EXPO_PUBLIC_POSTHOG_HOST`	Mobile	Analytics	No

Environment Variables

Architecture

Variables by platform

Core variables (always generated)

OAuth variables (per provider)

Billing variables (Stripe)

Billing variables (Polar)

Mobile billing (RevenueCat webhook)

Full Zod schema

Core variables

Billing variables (Stripe)

Analytics variables

Full Zod schema

Core variables

Billing variables (RevenueCat)

Analytics variables

Full Zod schema

.env file locations

How startup validation works

Which variables depend on features

Quick reference: all variables

Authentication

Billing

Analytics

Configuration

On this page

Environment Variables

Billing disabled

Billing with Stripe

Billing with Polar

Mobile platform + billing

OAuth providers

No API platform

Authentication

Billing

Analytics

Configuration

On this page