environment-setup

Environment Setup

What Are .env Files? (Plain Language)

Your app needs secret information to work — database passwords, API keys, service credentials. You can't put these directly in your code because:

1. Security: If your code is on GitHub, anyone can see your secrets
2. Flexibility: Different environments (your laptop vs the live site) need different values
3. Team safety: Each developer has their own keys; you don't share secrets in code

A .env file is a simple text file that sits on your computer (and ONLY your computer) containing these secrets. It looks like this:

# Database connection
DATABASE_URL=postgresql://user:password@localhost:5432/mydb

# Stripe payment processing
STRIPE_SECRET_KEY=sk_test_abc123
STRIPE_PUBLISHABLE_KEY=pk_test_xyz789

Your app reads these values when it starts up. The .env file is listed in .gitignore so it never gets uploaded to GitHub.

---

The .env.example File

Every project MUST have a .env.example file. This is a template that shows what variables are needed WITHOUT revealing actual secret values.

Auto-Generate Template

When setting up a project or adding a new service, always create or update .env.example:

# =============================================================
# Environment Variables
# Copy this file to .env and fill in your values:
#   cp .env.example .env
# =============================================================

# ----- DATABASE -----
# Your Supabase database connection string
# Get it: Supabase Dashboard > Project Settings > Database > Connection string
DATABASE_URL=postgresql://postgres:[YOUR-PASSWORD]@db.[YOUR-PROJECT-REF].supabase.co:5432/postgres

# Supabase anonymous (public) key — safe to expose in the browser
# Get it: Supabase Dashboard > Project Settings > API > anon/public key
NEXT_PUBLIC_SUPABASE_URL=https://[YOUR-PROJECT-REF].supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here

# Supabase service role key — NEVER expose this in the browser
# Get it: Supabase Dashboard > Project Settings > API > service_role key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key-here

# ----- AUTHENTICATION -----
# NextAuth secret — random string for encrypting session tokens
# Generate one: openssl rand -base64 32
NEXTAUTH_SECRET=generate-a-random-string-here
NEXTAUTH_URL=http://localhost:3000

# Google OAuth (optional — for "Sign in with Google")
# Get it: https://console.cloud.google.com/apis/credentials
# Create OAuth 2.0 Client ID, set redirect URI to http://localhost:3000/api/auth/callback/google
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# ----- PAYMENTS -----
# Stripe API keys
# Get it: https://dashboard.stripe.com/test/apikeys
# Use TEST keys during development (start with sk_test_ and pk_test_)
STRIPE_SECRET_KEY=sk_test_your-key-here
STRIPE_PUBLISHABLE_KEY=pk_test_your-key-here

# Stripe webhook secret for verifying webhook signatures
# Get it: https://dashboard.stripe.com/test/webhooks — click your endpoint, reveal signing secret
STRIPE_WEBHOOK_SECRET=whsec_your-webhook-secret-here

# ----- EMAIL -----
# Resend API key for sending emails
# Get it: https://resend.com/api-keys — create a new key
RESEND_API_KEY=re_your-api-key-here

# ----- APP CONFIG -----
# Your app's public URL (no trailing slash)
NEXT_PUBLIC_APP_URL=http://localhost:3000