General

Codebase

Environment Variables

Learn how environment variables are managed in the project.

The starter kit uses @t3-oss/env-nextjs to manage environment variables with type safety and validation. All environment variables are defined in lib/env.ts with Zod schemas.

Environment Variable Files

Create a .env file in the root directory (you can copy from .env.example):

Terminal

cp .env.example .env

Security Note Never commit .env to version control. It's already included in .gitignore.

Required Variables

The following environment variables are required for the application to run:

Database

.env

DATABASE_URL=postgresql://user:password@localhost:5432/dbname

Note The POSTGRES_* variables (POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, POSTGRES_HOST, POSTGRES_PORT) are optional and have defaults. Only DATABASE_URL is required.

Authentication

.env

BETTER_AUTH_SECRET=your-secret-key-here

Note The authentication secret is named BETTER_AUTH_SECRET, not AUTH_SECRET. Generate a secure random string for this value.

Optional Variables

Authentication (OAuth)

.env

GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

Billing (Stripe)

.env

STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
NEXT_PUBLIC_STRIPE_PRICE_PRO_MONTHLY=price_...
NEXT_PUBLIC_STRIPE_PRICE_PRO_YEARLY=price_...
NEXT_PUBLIC_STRIPE_PRICE_LIFETIME=price_...
NEXT_PUBLIC_STRIPE_PRICE_CREDITS_STARTER=price_...
NEXT_PUBLIC_STRIPE_PRICE_CREDITS_BASIC=price_...
NEXT_PUBLIC_STRIPE_PRICE_CREDITS_PRO=price_...

Email (Resend)

.env

EMAIL_FROM=noreply@example.com
RESEND_API_KEY=re_...

Storage (S3)

.env

S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key
S3_ENDPOINT=https://s3.amazonaws.com
S3_REGION=us-east-1
NEXT_PUBLIC_IMAGES_BUCKET_NAME=your-bucket-name

Monitoring (Sentry)

.env

SENTRY_ORG=your-org
SENTRY_PROJECT=your-project
SENTRY_AUTH_TOKEN=your-auth-token
NEXT_PUBLIC_SENTRY_DSN=https://...@sentry.io/...

Captcha (Cloudflare Turnstile)

.env

TURNSTILE_SECRET_KEY=your-secret-key
NEXT_PUBLIC_TURNSTILE_SITE_KEY=your-site-key

Site Configuration

.env

NEXT_PUBLIC_SITE_URL=https://your-domain.com
NEXT_PUBLIC_LOG_LEVEL=info

Type Safety

The project uses TypeScript and Zod to ensure type safety for environment variables. All variables are defined in lib/env.ts with validation schemas.

Type Safety Environment variables are validated at build time and runtime. If a required variable is missing or has an invalid type, the application will fail to start with a clear error message.

Adding New Variables

Add the variable to lib/env.ts in the appropriate schema (server or client)
Add the variable to .env.example (without sensitive values)
Add the variable to your .env file with the actual value
Add the variable to runtimeEnv in lib/env.ts
Restart your development server

Example: Adding a Server Variable

lib/env.ts

server: {
  // ... existing variables
  MY_NEW_VAR: z.string().min(1),
},

lib/env.ts

runtimeEnv: {
  // ... existing variables
  MY_NEW_VAR: process.env.MY_NEW_VAR,
},

Example: Adding a Client Variable

Client variables must be prefixed with NEXT_PUBLIC_:

lib/env.ts

client: {
  // ... existing variables
  NEXT_PUBLIC_MY_VAR: z.string().optional(),
},

lib/env.ts

runtimeEnv: {
  // ... existing variables
  NEXT_PUBLIC_MY_VAR: process.env.NEXT_PUBLIC_MY_VAR,
},

Production

For production deployments, set environment variables in your hosting platform's dashboard (Vercel, Railway, etc.). Never commit production secrets to your repository.

Skipping Validation

For Docker builds or CI/CD pipelines, you can skip environment variable validation:

Terminal

SKIP_ENV_VALIDATION=true npm run build

This is useful when environment variables are provided at runtime rather than build time.