Production Environment Variables for Next.js Supabase SaaS

Generate and configure environment variables for your MakerKit Next.js Supabase Turbo production deployment. MakerKit uses Zod schemas to validate all variables at build time, catching configuration errors before deployment.

Generate Environment Variables

MakerKit provides an interactive generator that walks you through each required variable:

pnpm turbo gen env

This command:

1. Prompts you for each variable value
2. Uses defaults from your existing .env files when available
3. Creates a file at turbo/generators/templates/env/.env.local

Copy the contents of this file to your hosting provider's environment variable settings.

Validate Environment Variables

After generating or manually setting variables, validate them:

turbo gen validate-env

This checks that all required variables are present and correctly formatted.

Required Variables Reference

Application Settings

Supabase Configuration

Authentication Settings

Feature Flags

Billing Configuration

Stripe

Lemon Squeezy

Email Configuration

Using Resend

Using Nodemailer (SMTP)

CMS Configuration

Captcha Protection (Optional)

Monitoring (Optional)

Environment Variable Groups

Minimum Required for Deployment

These are the absolute minimum variables needed for a working deployment:

# Application
NEXT_PUBLIC_SITE_URL=https://yourdomain.com
NEXT_PUBLIC_PRODUCT_NAME=MyApp
# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLIC_KEY=eyJ...
SUPABASE_SECRET_KEY=eyJ...
# Billing (Stripe example)
NEXT_PUBLIC_BILLING_PROVIDER=stripe
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
# Email
MAILER_PROVIDER=resend
EMAIL_SENDER=noreply@yourdomain.com
RESEND_API_KEY=re_...
# Webhooks
SUPABASE_DB_WEBHOOK_SECRET=your-secret

Full Production Configuration

Here's a complete example with all common variables:

# ============================================
# APPLICATION
# ============================================
NEXT_PUBLIC_SITE_URL=https://yourdomain.com
NEXT_PUBLIC_PRODUCT_NAME=MyApp
NEXT_PUBLIC_SITE_TITLE=MyApp - Build SaaS Faster
NEXT_PUBLIC_SITE_DESCRIPTION=The complete SaaS starter kit
NEXT_PUBLIC_DEFAULT_THEME_MODE=light
NEXT_PUBLIC_DEFAULT_LOCALE=en
# ============================================
# AUTHENTICATION
# ============================================
NEXT_PUBLIC_AUTH_PASSWORD=true
NEXT_PUBLIC_AUTH_MAGIC_LINK=false
# ============================================
# FEATURES
# ============================================
NEXT_PUBLIC_ENABLE_THEME_TOGGLE=true
NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_DELETION=true
NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_BILLING=true
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS=true
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_DELETION=true
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_BILLING=true
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_CREATION=true
NEXT_PUBLIC_ENABLE_NOTIFICATIONS=true
NEXT_PUBLIC_REALTIME_NOTIFICATIONS=false
# ============================================
# SUPABASE
# ============================================
NEXT_PUBLIC_SUPABASE_URL=https://yourproject.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLIC_KEY=eyJhbGciOiJI...
SUPABASE_SECRET_KEY=eyJhbGciOiJI...
SUPABASE_DB_WEBHOOK_SECRET=your-webhook-secret
# ============================================
# BILLING (Stripe)
# ============================================
NEXT_PUBLIC_BILLING_PROVIDER=stripe
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
# ============================================
# EMAIL
# ============================================
MAILER_PROVIDER=resend
EMAIL_SENDER=noreply@yourdomain.com
RESEND_API_KEY=re_...
# ============================================
# CMS
# ============================================
CMS_CLIENT=keystatic
# ============================================
# OPTIONAL
# ============================================
CONTACT_EMAIL=support@yourdomain.com
LOGGER=pino

Build-Time vs Runtime Variables

MakerKit uses Zod schemas to validate environment variables. Understanding when validation occurs helps debug issues:

Build-Time Validation

Variables prefixed with NEXT_PUBLIC_ are embedded at build time. If missing:

• Build fails with a clear error message
• You must add the variable and rebuild

Runtime Validation

Server-only variables (without NEXT_PUBLIC_ prefix) are validated when the server starts. If missing:

• The application may start but fail when accessing certain features
• Check server logs for validation errors

Secrets Management

What Counts as a Secret

These variables contain sensitive data and must be protected:

• SUPABASE_SECRET_KEY
• STRIPE_SECRET_KEY
• STRIPE_WEBHOOK_SECRET
• LEMON_SQUEEZY_SECRET_KEY
• LEMON_SQUEEZY_SIGNING_SECRET
• SUPABASE_DB_WEBHOOK_SECRET
• RESEND_API_KEY
• EMAIL_PASSWORD
• CAPTCHA_SECRET_TOKEN

Best Practices

1. Never commit secrets: Use .gitignore to exclude .env*.local files
2. Use hosting provider secrets: Vercel, Cloudflare, etc. have secure environment variable storage
3. Rotate compromised secrets: If a secret is exposed, regenerate it immediately
4. Limit access: Only give team members access to secrets they need

Platform-Specific Notes

Vercel

• Add variables in Project Settings > Environment Variables
• Separate variables by environment (Production, Preview, Development)
• Use Vercel's sensitive variable feature for secrets

Cloudflare

• Add variables to .dev.vars for local development
• Use Wrangler secrets for production: wrangler secret put VARIABLE_NAME
• Some variables may need to be in wrangler.toml for build-time access

Docker

• Pass variables via --env-file flag
• Never bake secrets into Docker images
• Use Docker secrets or external secret managers for production

Troubleshooting

"Required environment variable X is missing"

The variable isn't set in your hosting provider. Add it and redeploy.

"Invalid value for environment variable X"

The variable value doesn't match the expected format. Check:

• URLs should start with https:// and have no trailing slash
• Boolean values should be true or false (not "true")
• Provider names must match exactly (stripe, not Stripe)

Variables work locally but not in production

1. Verify variables are set in your hosting provider (not just .env.local)
2. Check for typos in variable names
3. Ensure NEXT_PUBLIC_ prefix is correct for client-side variables
4. Redeploy after adding variables (Vercel caches builds)

Secrets appearing in client-side code

Only variables with NEXT_PUBLIC_ prefix should be in client code. If server-only secrets appear:

1. Check you're not importing server modules in client components
2. Verify the variable name doesn't have NEXT_PUBLIC_ prefix
3. Review your bundle with next build --analyze

Next Steps

• Deployment Checklist: Complete deployment steps
• Vercel Deployment: Deploy to Vercel with CI/CD
• Supabase Configuration: Set up Supabase with migrations and RLS