Environment Variables Reference
Complete reference for all environment variables used in the AI Store application.
Overview
Environment variables are loaded from .env.local (development) or system environment (production).
Required Variables
NEXT_PUBLIC_SITE_URL
Description: The public URL of your site.
Example:
NEXT_PUBLIC_SITE_URL=https://your-domain.com
Required: Yes
Used In: SEO, PWA, Analytics
Optional Variables
Analytics
NEXT_PUBLIC_ANALYTICS_ID
Description: Analytics service ID (e.g., Google Analytics).
Example:
NEXT_PUBLIC_ANALYTICS_ID=G-XXXXXXXXXX
Required: No
Default: None
Feature Flags
NEXT_PUBLIC_ENABLE_DEV_TOOLS
Description: Enable developer tools (Ctrl+Shift+D).
Example:
NEXT_PUBLIC_ENABLE_DEV_TOOLS=true
Required: No
Default: false (enabled in development)
NEXT_PUBLIC_ENABLE_ANALYTICS
Description: Enable analytics tracking.
Example:
NEXT_PUBLIC_ENABLE_ANALYTICS=true
Required: No
Default: true
API Configuration
NEXT_PUBLIC_API_URL
Description: Base URL for API requests.
Example:
NEXT_PUBLIC_API_URL=https://api.your-domain.com
Required: No
Default: /api
PWA Configuration
NEXT_PUBLIC_PWA_ENABLED
Description: Enable PWA features.
Example:
NEXT_PUBLIC_PWA_ENABLED=true
Required: No
Default: true
Security
SECRET_KEY
Description: Secret key for encryption (server-only).
Example:
SECRET_KEY=your-secret-key-here
Required: No (recommended for production)
Note: Never commit this to version control
Database (if applicable)
DATABASE_URL
Description: Database connection string (server-only).
Example:
DATABASE_URL=postgresql://user:password@localhost:5432/dbname
Required: No
Note: Server-only variable
Environment-Specific
Development
.env.local:
NEXT_PUBLIC_SITE_URL=http://localhost:3000
NEXT_PUBLIC_ENABLE_DEV_TOOLS=true
NEXT_PUBLIC_ENABLE_ANALYTICS=false
Staging
.env.staging:
NEXT_PUBLIC_SITE_URL=https://staging.your-domain.com
NEXT_PUBLIC_ENABLE_DEV_TOOLS=false
NEXT_PUBLIC_ENABLE_ANALYTICS=true
Production
System environment or .env.production:
NEXT_PUBLIC_SITE_URL=https://your-domain.com
NEXT_PUBLIC_ENABLE_DEV_TOOLS=false
NEXT_PUBLIC_ENABLE_ANALYTICS=true
SECRET_KEY=production-secret-key
Variable Naming
Client-Side Variables
Variables accessible in the browser must be prefixed with NEXT_PUBLIC_:
NEXT_PUBLIC_SITE_URL=https://your-domain.com
Server-Only Variables
Variables without NEXT_PUBLIC_ prefix are server-only:
SECRET_KEY=secret
DATABASE_URL=postgresql://...
Accessing Variables
Client-Side
const siteUrl = process.env.NEXT_PUBLIC_SITE_URL;
Server-Side
// In API routes or Server Components
const secretKey = process.env.SECRET_KEY;
Security Best Practices
1. Never Commit Secrets
Add to .gitignore:
.env.local
.env*.local
2. Use Different Keys Per Environment
- Development:
.env.local - Staging:
.env.staging - Production: System environment
3. Rotate Keys Regularly
Change secret keys periodically for security.
4. Use Strong Keys
Generate strong random keys:
openssl rand -base64 32
Validation
Type Safety
// lib/env.ts
export const env = {
siteUrl: process.env.NEXT_PUBLIC_SITE_URL || 'http://localhost:3000',
analyticsId: process.env.NEXT_PUBLIC_ANALYTICS_ID,
devTools: process.env.NEXT_PUBLIC_ENABLE_DEV_TOOLS === 'true',
} as const;
Runtime Validation
// Validate required variables
if (!process.env.NEXT_PUBLIC_SITE_URL) {
throw new Error('NEXT_PUBLIC_SITE_URL is required');
}
Troubleshooting
Variables Not Loading
- Restart dev server after changing
.env.local - Check file name: Must be
.env.local(not.env) - Check prefix: Client variables need
NEXT_PUBLIC_ - Clear cache: Delete
.nextdirectory
Variables Not Available
- Check scope: Server-only variables not available in client
- Check prefix: Missing
NEXT_PUBLIC_for client variables - Check build: Variables are embedded at build time
Example Configuration
Complete .env.local
# Site Configuration
NEXT_PUBLIC_SITE_URL=http://localhost:3000
# Analytics
NEXT_PUBLIC_ANALYTICS_ID=G-XXXXXXXXXX
NEXT_PUBLIC_ENABLE_ANALYTICS=true
# Feature Flags
NEXT_PUBLIC_ENABLE_DEV_TOOLS=true
# API
NEXT_PUBLIC_API_URL=http://localhost:3000/api
# PWA
NEXT_PUBLIC_PWA_ENABLED=true
# Security (server-only)
SECRET_KEY=development-secret-key