setup-env-variables

Setup Environment Variables

Overview

Properly configure and validate environment variables for React/Next.js applications.

Next.js Environment Variables

Types of Variables

1. Public (Client-side): Prefix with NEXT_PUBLIC_

   • Exposed to the browser
   • Safe for client code
   • Example: NEXT_PUBLIC_API_URL

2. Server-only: No prefix

   • Only available on server
   • Never exposed to browser
   • Example: DATABASE_URL, API_SECRET

File Structure

.env.local          # Local development (gitignored)
.env.development    # Development defaults
.env.production     # Production defaults
.env.example        # Template for team (committed)

Setup Steps

1. Create .env.example

# .env.example
# API Configuration
NEXT_PUBLIC_API_URL=
DATABASE_URL=
# Authentication
NEXTAUTH_SECRET=
NEXTAUTH_URL=
# OAuth
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
# External Services
STRIPE_SECRET_KEY=
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=

2. Create .env.local

# .env.local
NEXT_PUBLIC_API_URL=http://localhost:3000/api
DATABASE_URL=postgresql://user:password@localhost:5432/mydb
NEXTAUTH_SECRET=your-secret-key-min-32-characters
NEXTAUTH_URL=http://localhost:3000

3. Add to .gitignore

# .gitignore
.env*.local
.env.production

Type-Safe Environment Variables

Using Zod

// lib/env.ts
import { z } from 'zod';

// Define schema
const envSchema = z.object({
  // Node
  NODE_ENV: z.enum(['development', 'production', 'test']),
  
  // Public
  NEXT_PUBLIC_API_URL: z.string().url(),
  NEXT_PUBLIC_APP_URL: z.string().url(),
  
  // Server-only
  DATABASE_URL: z.string().min(1),
  NEXTAUTH_SECRET: z.string().min(32),
  NEXTAUTH_URL: z.string().url(),
  
  // OAuth
  GOOGLE_CLIENT_ID: z.string().optional(),
  GOOGLE_CLIENT_SECRET: z.string().optional(),
  
  // External Services
  STRIPE_SECRET_KEY: z.string().optional(),
  RESEND_API_KEY: z.string().optional(),
});

// Parse and export
export const env = envSchema.parse({
  NODE_ENV: process.env.NODE_ENV,
  NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
  NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
  DATABASE_URL: process.env.DATABASE_URL,
  NEXTAUTH_SECRET: process.env.NEXTAUTH_SECRET,
  NEXTAUTH_URL: process.env.NEXTAUTH_URL,
  GOOGLE_CLIENT_ID: process.env.GOOGLE_CLIENT_ID,
  GOOGLE_CLIENT_SECRET: process.env.GOOGLE_CLIENT_SECRET,
  STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY,
  RESEND_API_KEY: process.env.RESEND_API_KEY,
});

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