Environment Management | Bootspring Docs

Patterns for managing multiple deployment environments.

Overview#

Proper environment management ensures safe deployments and configuration. This pattern covers:

Environment variable structure
Environment-specific configuration
Feature flags per environment
Secret management
Preview environments

Prerequisites#

npm install zod

Code Example#

Environment Variable Schema#

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

const envSchema = z.object({
  // Runtime environment
  NODE_ENV: z.enum(['development', 'production', 'test']),
  VERCEL_ENV: z.enum(['development', 'preview', 'production']).optional(),

  // Database
  DATABASE_URL: z.string().url(),

  // Auth
  NEXTAUTH_SECRET: z.string().min(32),
  NEXTAUTH_URL: z.string().url(),

  // API URLs
  NEXT_PUBLIC_APP_URL: z.string().url(),
  NEXT_PUBLIC_API_URL: z.string().url().optional(),

  // Third-party services
  STRIPE_SECRET_KEY: z.string().startsWith('sk_'),
  STRIPE_WEBHOOK_SECRET: z.string().startsWith('whsec_'),
  RESEND_API_KEY: z.string().startsWith('re_'),

  // Feature flags
  ENABLE_ANALYTICS: z.coerce.boolean().default(false),
  ENABLE_BETA_FEATURES: z.coerce.boolean().default(false)
})

function validateEnv() {
  const parsed = envSchema.safeParse(process.env)

  if (!parsed.success) {
    console.error('Invalid environment variables:')
    console.error(JSON.stringify(parsed.error.flatten().fieldErrors, null, 2))
    throw new Error('Invalid environment configuration')
  }

  return parsed.data
}

export const env = validateEnv()
export type Env = z.infer<typeof envSchema>

Environment Files Structure#

# .env.example - Template for developers
DATABASE_URL="postgresql://localhost:5432/myapp"
NEXTAUTH_SECRET="your-secret-here"
NEXTAUTH_URL="http://localhost:3000"
NEXT_PUBLIC_APP_URL="http://localhost:3000"

# .env.local - Local development (git ignored)
DATABASE_URL="postgresql://localhost:5432/myapp_dev"
NEXTAUTH_SECRET="dev-secret-32-characters-long!!"
NEXTAUTH_URL="http://localhost:3000"
NEXT_PUBLIC_APP_URL="http://localhost:3000"
ENABLE_BETA_FEATURES="true"

# .env.test - Test environment
DATABASE_URL="postgresql://localhost:5432/myapp_test"
NEXTAUTH_SECRET="test-secret-32-characters-long!!"

# .env.production - Production values (git ignored, in CI secrets)
# Set via Vercel dashboard or CI/CD secrets

Environment-Aware Configuration#

// lib/config.ts
import { env } from './env'

interface Config {
  isProduction: boolean
  isDevelopment: boolean
  isPreview: boolean
  baseUrl: string
  apiUrl: string
  features: {
    analytics: boolean
    betaFeatures: boolean
    debugMode: boolean
  }
  rateLimit: {
    window: number
    max: number
  }
}

export function getConfig(): Config {
  const isProduction = env.NODE_ENV === 'production' &&
    env.VERCEL_ENV === 'production'
  const isDevelopment = env.NODE_ENV === 'development'
  const isPreview = env.VERCEL_ENV === 'preview'

  return {
    isProduction,
    isDevelopment,
    isPreview,
    baseUrl: env.NEXT_PUBLIC_APP_URL,
    apiUrl: env.NEXT_PUBLIC_API_URL ?? env.NEXT_PUBLIC_APP_URL,
    features: {
      analytics: isProduction && env.ENABLE_ANALYTICS,
      betaFeatures: !isProduction || env.ENABLE_BETA_FEATURES,
      debugMode: isDevelopment
    },
    rateLimit: {
      window: isProduction ? 60 : 1,
      max: isProduction ? 100 : 1000
    }
  }
}

export const config = getConfig()

Dynamic Base URL#

// lib/url.ts
export function getBaseUrl(): string {
  // Browser
  if (typeof window !== 'undefined') {
    return ''
  }

  // Vercel preview deployments
  if (process.env.VERCEL_URL) {
    return `https://${process.env.VERCEL_URL}`
  }

  // Production
  if (process.env.NEXT_PUBLIC_APP_URL) {
    return process.env.NEXT_PUBLIC_APP_URL
  }

  // Local development
  return `http://localhost:${process.env.PORT ?? 3000}`
}

// Usage in tRPC, API routes, etc.
const baseUrl = getBaseUrl()

Feature Flags by Environment#

// lib/features.ts
import { env } from './env'

interface FeatureFlags {
  newDashboard: boolean
  aiFeatures: boolean
  betaCheckout: boolean
  darkMode: boolean
}

const featuresByEnvironment: Record<string, Partial<FeatureFlags>> = {
  development: {
    newDashboard: true,
    aiFeatures: true,
    betaCheckout: true,
    darkMode: true
  },
  preview: {
    newDashboard: true,
    aiFeatures: true,
    betaCheckout: true,
    darkMode: true
  },
  production: {
    newDashboard: false, // Gradual rollout
    aiFeatures: true,
    betaCheckout: false,
    darkMode: true
  }
}

export function getFeatureFlags(): FeatureFlags {
  const environment = env.VERCEL_ENV ?? env.NODE_ENV
  const flags = featuresByEnvironment[environment] ?? {}

  return {
    newDashboard: false,
    aiFeatures: false,
    betaCheckout: false,
    darkMode: true,
    ...flags
  }
}

export const features = getFeatureFlags()

// Usage
if (features.newDashboard) {
  // Show new dashboard
}

Database URL by Environment#

// lib/db.ts
import { PrismaClient } from '@prisma/client'

function getDatabaseUrl(): string {
  const url = process.env.DATABASE_URL

  if (!url) {
    throw new Error('DATABASE_URL is required')
  }

  // Add connection pooling for production
  if (process.env.NODE_ENV === 'production') {
    const poolUrl = new URL(url)
    poolUrl.searchParams.set('connection_limit', '10')
    poolUrl.searchParams.set('pool_timeout', '10')
    return poolUrl.toString()
  }

  return url
}

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined
}

export const prisma = globalForPrisma.prisma ?? new PrismaClient({
  datasources: {
    db: { url: getDatabaseUrl() }
  },
  log: process.env.NODE_ENV === 'development'
    ? ['query', 'error', 'warn']
    : ['error']
})

if (process.env.NODE_ENV !== 'production') {
  globalForPrisma.prisma = prisma
}

Vercel Environment Configuration#

// vercel.json
{
  "env": {
    "NEXT_PUBLIC_APP_URL": "https://myapp.com"
  },
  "build": {
    "env": {
      "DATABASE_URL": "@database-url-production"
    }
  }
}

GitHub Environment Secrets#

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main, staging]

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ github.ref == 'refs/heads/main' && 'production' || 'staging' }}
    steps:
      - uses: actions/checkout@v4

      - name: Deploy
        run: |
          echo "Deploying to ${{ github.ref == 'refs/heads/main' && 'production' || 'staging' }}"
        env:
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
          STRIPE_SECRET_KEY: ${{ secrets.STRIPE_SECRET_KEY }}

Preview Environment Database#

// lib/preview-db.ts
export async function getPreviewDatabaseUrl(): Promise<string> {
  const branchName = process.env.VERCEL_GIT_COMMIT_REF

  if (!branchName || process.env.VERCEL_ENV !== 'preview') {
    return process.env.DATABASE_URL!
  }

  // Use Neon or PlanetScale branch databases
  const sanitizedBranch = branchName
    .replace(/[^a-zA-Z0-9]/g, '-')
    .toLowerCase()
    .slice(0, 30)

  // Create branch database if it doesn't exist
  // This would call your database provider's API
  const branchDbUrl = await createBranchDatabase(sanitizedBranch)

  return branchDbUrl
}

Usage Instructions#

Create .env.example with all required variables
Use Zod to validate environment variables at startup
Create environment-specific configurations
Set up feature flags per environment
Configure CI/CD with environment-specific secrets

Best Practices#

Validate early - Check environment variables at startup
Never commit secrets - Use .env.local and CI secrets
Use typed config - Type-safe access to configuration
Environment parity - Keep environments as similar as possible
Preview databases - Use isolated databases for previews
Feature flags - Enable gradual rollouts
Document variables - Keep .env.example up to date

Secrets Management - Secure secret handling
CI/CD - Deployment pipelines
Docker - Container configuration
Feature Flags - Feature management