Skip to main content

​
Environment Variables

This guide documents all environment variables used to configure Openfront. Environment variables control database connections, authentication, payment providers, shipping integrations, file storage, email services, and more.
All environment variables should be defined in a .env file in your project root. Never commit this file to version control.

​
Required Variables

These variables are required for Openfront to function:

​
Database Connection

​
DATABASE_URL
string
required
PostgreSQL database connection string.Format: postgresql://username:password@host:port/databaseExample:
DATABASE_URL="postgresql://openfront:password@localhost:5432/openfront"
Most hosting providers (Vercel, Railway, etc.) automatically set this variable when you add a PostgreSQL database.
​
SESSION_SECRET
string
required
Secret key for encrypting session data. Must be at least 32 characters long.Example:
SESSION_SECRET="your-very-long-session-secret-minimum-32-characters"
Generate a secure secret:
# Using Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Using OpenSSL
openssl rand -base64 32
Never use the default value in production. Generate a unique, random secret for each environment.

​
Optional Variables

​
Database (Advanced)

​
SHADOW_DATABASE_URL
string
Shadow database URL for Prisma migrations. Used when your main database doesn’t support schema diffing.Format: postgresql://username:password@host:port/database_shadowExample:
SHADOW_DATABASE_URL="postgresql://openfront:password@localhost:5432/openfront_shadow"

​
Application Settings

​
NODE_ENV
string
default:"development"
Node.js environment mode.Options: development, production, testExample:
NODE_ENV="production"
In production mode, secure cookies are enforced and additional optimizations are enabled.
​
PORT
number
default:"3000"
Port for the Next.js application server.Example:
PORT="3001"
​
NEXT_PUBLIC_DEFAULT_REGION
string
default:"us"
Default region code for the storefront.Example:
NEXT_PUBLIC_DEFAULT_REGION="us"
​
NEXT_PUBLIC_BACKEND_URL
string
Backend URL for API calls. Useful when frontend and backend are on different domains.Example:
NEXT_PUBLIC_BACKEND_URL="https://api.yourstore.com"

​
Payment Providers

Configure payment providers to accept online payments.

​
Stripe

​
STRIPE_SECRET_KEY
string
Stripe secret API key. Get this from your Stripe Dashboard.Format: Starts with sk_test_ (test) or sk_live_ (production)Example:
STRIPE_SECRET_KEY="sk_test_51abc123..."
​
STRIPE_WEBHOOK_SECRET
string
Stripe webhook signing secret for verifying webhook events.Format: Starts with whsec_Example:
STRIPE_WEBHOOK_SECRET="whsec_abc123..."
Create a webhook endpoint at https://yourdomain.com/api/webhooks/stripe in your Stripe Dashboard to get this secret.
​
NEXT_PUBLIC_STRIPE_KEY
string
Stripe publishable key for client-side operations.Format: Starts with pk_test_ (test) or pk_live_ (production)Example:
NEXT_PUBLIC_STRIPE_KEY="pk_test_51abc123..."

​
PayPal

​
PAYPAL_CLIENT_ID
string
PayPal REST API client ID from your PayPal Developer Dashboard.Example:
PAYPAL_CLIENT_ID="your-paypal-client-id"
​
PAYPAL_CLIENT_SECRET
string
PayPal REST API client secret.Example:
PAYPAL_CLIENT_SECRET="your-paypal-client-secret"
​
NEXT_PUBLIC_PAYPAL_CLIENT_ID
string
PayPal client ID for client-side SDK initialization.Example:
NEXT_PUBLIC_PAYPAL_CLIENT_ID="your-paypal-client-id"
​
NEXT_PUBLIC_PAYPAL_SANDBOX
string
default:"true"
Enable PayPal sandbox mode for testing.Options: true (sandbox), false (production)Example:
NEXT_PUBLIC_PAYPAL_SANDBOX="false"
​
PAYPAL_WEBHOOK_ID
string
PayPal webhook ID for verifying webhook signatures.Example:
PAYPAL_WEBHOOK_ID="your-webhook-id"
​
PAYPAL_API_URL
string
default:"https://api.paypal.com"
PayPal API base URL. Override for sandbox testing.Example:
PAYPAL_API_URL="https://api.sandbox.paypal.com"

​
Shipping Providers

Configure shipping providers for rate calculation and label generation.

​
Shippo

​
SHIPPO_API_KEY
string
Shippo API key for shipping label generation and rate calculation.Format: Starts with shippo_test_ (test) or shippo_live_ (production)Example:
SHIPPO_API_KEY="shippo_test_abc123..."
Get your API key from Shippo Dashboard.

​
File Storage (S3-Compatible)

Configure S3-compatible storage for product images and other files.
​
S3_BUCKET_NAME
string
default:"keystone-test"
S3 bucket name for file storage.Example:
S3_BUCKET_NAME="openfront-assets"
​
S3_REGION
string
default:"ap-southeast-2"
AWS region for your S3 bucket.Example:
S3_REGION="us-east-1"
​
S3_ACCESS_KEY_ID
string
default:"keystone"
AWS access key ID with S3 permissions.Example:
S3_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
​
S3_SECRET_ACCESS_KEY
string
default:"keystone"
AWS secret access key.Example:
S3_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
​
S3_ENDPOINT
string
default:"https://sfo3.digitaloceanspaces.com"
S3-compatible endpoint URL. Use this for DigitalOcean Spaces, Cloudflare R2, MinIO, etc.Examples:
# AWS S3 (optional, uses default)
S3_ENDPOINT="https://s3.us-east-1.amazonaws.com"

# DigitalOcean Spaces
S3_ENDPOINT="https://nyc3.digitaloceanspaces.com"

# Cloudflare R2
S3_ENDPOINT="https://abc123.r2.cloudflarestorage.com"
S3 Alternatives: Openfront works with any S3-compatible storage provider including:
  • AWS S3: Native support
  • DigitalOcean Spaces: Set custom endpoint
  • Cloudflare R2: Set custom endpoint
  • MinIO: Self-hosted S3-compatible storage
  • Backblaze B2: S3-compatible API

​
Email Configuration (SMTP)

Configure SMTP for transactional emails like order confirmations and password resets.
​
SMTP_HOST
string
SMTP server hostname.Example:
SMTP_HOST="smtp.gmail.com"
​
SMTP_PORT
string
default:"587"
SMTP server port.Common ports: 587 (TLS), 465 (SSL), 25 (unencrypted)Example:
SMTP_PORT="587"
​
SMTP_USER
string
SMTP authentication username (usually your email address).Example:
SMTP_USER="[email protected]"
​
SMTP_PASSWORD
string
SMTP authentication password or app-specific password.Example:
SMTP_PASSWORD="your-app-password"
For Gmail, you need to generate an App Password instead of using your regular password.
​
SMTP_FROM
string
“From” email address for outgoing emails.Example:
SMTP_FROM="[email protected]"
​
SMTP_STORE_LINK
string
Store URL to include in email templates.Example:
SMTP_STORE_LINK="https://yourstore.com"

​
AI Assistant (Optional)

Configure the built-in AI assistant powered by OpenRouter.
​
OPENROUTER_API_KEY
string
OpenRouter API key for AI assistant functionality.Example:
OPENROUTER_API_KEY="sk-or-v1-abc123..."
Get your API key from OpenRouter.
​
OPENROUTER_MODEL
string
Model to use for AI assistant.Example:
OPENROUTER_MODEL="anthropic/claude-3.5-sonnet"
​
OPENROUTER_MAX_TOKENS
string
default:"4000"
Maximum tokens for AI responses.Example:
OPENROUTER_MAX_TOKENS="8000"

​
Advanced Configuration

​
View Order

​
NEXT_PUBLIC_VIEW_ORDER
string
Custom field ordering for admin dashboard views.Example:
NEXT_PUBLIC_VIEW_ORDER="title,description,price"

​
Complete Example

Here’s a complete .env.example file with all variables:
.env.example
# ============================================
# REQUIRED - Core Configuration
# ============================================

# Database Connection
DATABASE_URL="postgresql://username:password@localhost:5432/openfront"

# Session Secret (minimum 32 characters)
SESSION_SECRET="your-very-long-session-secret-minimum-32-characters"

# ============================================
# OPTIONAL - Application Settings
# ============================================

# Environment
NODE_ENV="development"
PORT="3000"

# Frontend Configuration
NEXT_PUBLIC_DEFAULT_REGION="us"
NEXT_PUBLIC_BACKEND_URL="http://localhost:3000"

# ============================================
# OPTIONAL - Payment Providers
# ============================================

# Stripe
STRIPE_SECRET_KEY="sk_test_51..."
STRIPE_WEBHOOK_SECRET="whsec_..."
NEXT_PUBLIC_STRIPE_KEY="pk_test_51..."

# PayPal
PAYPAL_CLIENT_ID="your-paypal-client-id"
PAYPAL_CLIENT_SECRET="your-paypal-client-secret"
NEXT_PUBLIC_PAYPAL_CLIENT_ID="your-paypal-client-id"
NEXT_PUBLIC_PAYPAL_SANDBOX="true"
PAYPAL_WEBHOOK_ID="your-webhook-id"

# ============================================
# OPTIONAL - Shipping Providers
# ============================================

# Shippo
SHIPPO_API_KEY="shippo_test_..."

# ============================================
# OPTIONAL - File Storage (S3-Compatible)
# ============================================

S3_BUCKET_NAME="openfront-assets"
S3_REGION="us-east-1"
S3_ACCESS_KEY_ID="your-access-key"
S3_SECRET_ACCESS_KEY="your-secret-key"
S3_ENDPOINT="https://s3.us-east-1.amazonaws.com"

# ============================================
# OPTIONAL - Email Configuration
# ============================================

SMTP_HOST="smtp.gmail.com"
SMTP_PORT="587"
SMTP_USER="[email protected]"
SMTP_PASSWORD="your-app-password"
SMTP_FROM="[email protected]"
SMTP_STORE_LINK="https://yourstore.com"

# ============================================
# OPTIONAL - AI Assistant
# ============================================

OPENROUTER_API_KEY="sk-or-v1-..."
OPENROUTER_MODEL="anthropic/claude-3.5-sonnet"
OPENROUTER_MAX_TOKENS="4000"

​
Environment-Specific Configuration

.env.development
NODE_ENV="development"
DATABASE_URL="postgresql://localhost:5432/openfront_dev"
SESSION_SECRET="dev-secret-at-least-32-characters-long"

# Test mode for payment providers
STRIPE_SECRET_KEY="sk_test_..."
NEXT_PUBLIC_STRIPE_KEY="pk_test_..."
NEXT_PUBLIC_PAYPAL_SANDBOX="true"

# Local S3 (MinIO)
S3_ENDPOINT="http://localhost:9000"
S3_ACCESS_KEY_ID="minioadmin"
S3_SECRET_ACCESS_KEY="minioadmin"

​
Security Best Practices

Never commit secrets to version control. Always use .env files and add them to .gitignore.
1
Use Strong Secrets
2
Generate cryptographically secure random values:
3
# Generate 32-byte secret
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Or with OpenSSL
openssl rand -hex 32
4
Use Environment-Specific Files
5
Create separate .env files for each environment:
6
  • .env.development - Local development
  • .env.production - Production deployment
  • .env.test - Automated testing
    • 7
    Rotate Secrets Regularly
    8
    Update SESSION_SECRET and API keys periodically, especially after team member changes.
    9
    Use Secret Management
    10
    For production, consider using secret management services:
    11
  • Vercel: Environment variables in project settings
  • Railway: Environment variables per deployment
  • AWS: AWS Secrets Manager or Parameter Store
  • HashiCorp Vault: Enterprise secret management

    • ​
    Troubleshooting

    Make sure your .env file is in the project root and properly formatted:
    # Correct
DATABASE_URL="postgresql://localhost/db"

# Wrong - no spaces around =
DATABASE_URL = "postgresql://localhost/db"

# Wrong - no quotes
DATABASE_URL=postgresql://localhost/db
    NEXT_PUBLIC_ variables are embedded at build time. Restart your dev server or rebuild:
    # Kill and restart dev server
npm run dev

# Or rebuild
npm run build
    Double-check:
    • Using correct test vs. live keys
    • Keys match the environment (test keys in development)
    • No extra spaces or line breaks in values
    • Webhook secrets match configured endpoints
    Verify:
    • Bucket exists and is accessible
    • Access keys have proper permissions
    • Region matches bucket region
    • Endpoint URL is correct for S3 alternative
    • CORS is configured if using browser uploads

    ​
    Next Steps

    Payment Setup

    Configure Stripe or PayPal for payment processing

    Shipping Setup

    Set up shipping providers and rates

    Email Templates

    Customize transactional email templates

    API Reference

    Explore the GraphQL API

    Build docs developers (and LLMs) love

    Get started for freeTalk to us