Environment Variables

How it works

One Zod schema checks all your environment variables when the app starts. It lives in lib/validations/env.ts. Zod is a schema validation library. The app parses process.env against this schema once, then exports the result as a typed env object.

If a required variable is missing or has a bad value, the app stops right away with an error. This happens before any request is served, so a broken config fails at startup instead of crashing later.

The env object is fully typed. When you read env.DATABASE_URL or env.STRIPE_SECRET_KEY in your code, you get autocomplete and type checking for free.

A variable is required unless its rule ends in .optional() or .default(...). Each rule also checks the value:

• z.url(): must be a valid URL, including the scheme (https://)
• z.email(): must be a valid email address
• z.string().min(n): must have at least n characters
• z.string().startsWith("price_"): must start with price_ (Stripe price IDs)
• z.enum([...]): must be one of a fixed set of values

Reference

Core / App

Authentication

Generate a secret with pnpm dlx auth secret or openssl rand -base64 32.

Google OAuth

Database

Storage (Cloudflare R2)

Email (SMTP2Go)

Cloudflare Turnstile

Turnstile guards the contact form. Only that form uses it, so no sign-in, register, or password flow needs a token. Both keys are still required because env validation runs at startup regardless.

Create the widget in MANAGED mode and add localhost to its Hostnames for local dev. See the Turnstile guide.

Stripe

The four price IDs are wired to the subscription plans in lib/auth.ts. Get the webhook secret locally with stripe listen --forward-to localhost:3000/api/auth/stripe/webhook.

Misc

.env.example

Copy this as your starting point (matches the repo's .env.example):

# Core
NODE_ENV="development"
PUBLIC_URL="http://localhost:3000"
NEXT_PUBLIC_APP_NAME="next-starter"

# Authentication
BETTER_AUTH_URL="http://localhost:3000"
NEXT_PUBLIC_BETTER_AUTH_URL="http://localhost:3000"
BETTER_AUTH_SECRET=""                    # Generate: pnpm dlx auth secret

# Google OAuth
GOOGLE_CLIENT_ID=""
GOOGLE_CLIENT_SECRET=""

# Database
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/next_starter"
# DIRECT_DATABASE_URL=""                 # Direct connection for migrations

# Storage (Cloudflare R2)
STORAGE_S3_KEY=""
STORAGE_S3_SECRET=""
STORAGE_S3_REGION="auto"
STORAGE_S3_ENDPOINT=""                    # https://<account-id>.r2.cloudflarestorage.com
STORAGE_S3_BUCKET="next-starter"
NEXT_PUBLIC_STORAGE_S3_CDN_URL=""        # https://<bucket>.<account-id>.r2.dev

# Email (SMTP2Go)
SMTP2GO_API_KEY=""
SENDER_EMAIL="noreply@yourdomain.com"

# Cloudflare Turnstile
NEXT_PUBLIC_TURNSTILE_SITE_KEY=""
TURNSTILE_SECRET_KEY=""

# Stripe
STRIPE_SECRET_KEY=""                     # Use sk_test_ keys for development
STRIPE_WEBHOOK_SECRET=""
STRIPE_PRICE_PLUS_MONTHLY=""
STRIPE_PRICE_PLUS_ANNUAL=""
STRIPE_PRICE_PRO_MONTHLY=""
STRIPE_PRICE_PRO_ANNUAL=""

# Misc
NEXT_TELEMETRY_DISABLED=1

What you can change

All changes happen in one file: lib/validations/env.ts.

• Add a new variable. Add a rule to the envSchema object. Then add the value to your .env file and to each deployment (Vercel, etc.). Read it in server code with the typed env object: import { env } from "@/lib/validations/env".
• Make a variable optional. Change its rule to end in .optional().
• Give a variable a fallback. Add .default("some value") to its rule.
• NEXT_PUBLIC_ variables are public. Next.js bakes them into the browser bundle at build time, so never put secrets in them. Read them anywhere with process.env.NEXT_PUBLIC_*. Adding one to the schema still checks it exists at startup.