Typesafe Env Variables

Environment variables are validated at startup using a Zod schema. If a required variable is missing, the server fails fast with a clear error message instead of crashing later with a cryptic undefined.

Env file locations

create copies every .env.example to .env for you, and generates the secrets packs mark as generated.

After installing packs, run onboard to walk through the variables those packs need.

The env schema

Defined in apps/backend/src/config/env/env.config.ts. Packs merge extra schemas into this file (for example workos.env.ts, betterauth.env.ts, stripe.env.ts).

import { z } from "zod";

export const envSchema = z.object({
  FRONTEND_URL: z.string(),
  SERVER_URL: z.string().optional(),
  DATABASE_URL: z.string(),
  VALKEY_URL: z.string(),
  // Pack-gated keys are added when you install those packs
});

export type Env = z.infer<typeof envSchema>;

How validation works

The validateEnv() function runs at server startup, before routes accept traffic:

export const validateEnv = () => {
  try {
    envSchema.parse(process.env);
  } catch (err) {
    if (err instanceof z.ZodError) {
      const errorMessage = z.prettifyError(err);
      throw new Error(`Missing environment variables:\n  ${errorMessage}`, { cause: err });
    }
  }
};

If any variable is missing or has the wrong type, you get a list of exactly what is wrong before the server tries to use them.

Base template variables

These ship with the free starter (before packs):

Every origin variable needs its scheme (https://app.example.com, not app.example.com). A bare host breaks CORS and OAuth callbacks in ways that look unrelated; see Troubleshooting.

Frontend variables

Frontend (and admin) variables are prefixed with VITE_ and accessed via globalThis._importMeta_.env. They are baked into the bundle at build time. Do not put secrets here.

The mobile app reads the same ideas as EXPO_PUBLIC_API_BASE_URL, EXPO_PUBLIC_ENVIRONMENT, and EXPO_PUBLIC_SENTRY_DNS; see Mobile.

const apiUrl = globalThis._importMeta_.env.VITE_API_BASE_URL;

Pack-gated variables

Only required after you install the matching pack. Full setup lives on each pack page.

WorkOS starter

See SaaS Starter (WorkOS).

Better Auth starters (free and SaaS)

See Auth Starter (Better Auth) and SaaS Starter (Better Auth).

Admin (every starter)

See Admin app.

Billing

One provider per project. Each has a secret, a webhook signing secret, and one id per plan.

Newsletter

See Newsletter.

AI chat

See AI Chat.

Email (Resend)

Used by auth (password reset, verification), invitations, optional billing receipts, and notifications. See Mailing.

Observability (optional)

See Observability.

Adding a new env variable

1. Add it to the Zod schema in apps/backend/src/config/env/env.config.ts (or a pack-specific *.env.ts merge)
2. Add it to .env.example so other developers know about it, and to .env.test if tests need it
3. Add it to your local .env
4. Use z.string().optional() if the variable is not required in all environments

If you are writing a pack, declare the variable in the manifest's env field instead and the CLI patches all three files, marks it required, generated, or optional for onboard, and groups it under a section. See the manifest reference.