Source: ocean/docs/environment-variables-naming.md | ✏️ Edit on GitHub

Environment Variables Naming Convention

Overview

To avoid confusion between frontend and backend services, we use clear prefixes to indicate where each variable is used.

Naming Conventions

Frontend Variables (Vercel/Browser)

• Prefix: VITE_ (required by Vite for client-side exposure)
• Examples:
  • VITE_SENTRY_DSN → Sentry for browser/React app
  • VITE_POSTHOG_API_KEY → PostHog analytics
  • VITE_SUPABASE_URL → Supabase URL for client
  • VITE_SUPABASE_ANON_KEY → Public anon key

Edge Function Variables (Supabase/Deno)

• Prefix: EDGE_ or service-specific prefix
• Examples:
  • EDGE_SENTRY_DSN → Sentry for Edge Functions
  • EDGE_STRIPE_SECRET_KEY → Stripe for server-side
  • SUPABASE_SERVICE_ROLE_KEY → Supabase admin key
  • NEON_API_KEY → Database provisioning

Build/Deploy Variables (CI/CD)

• Prefix: BUILD_ or tool-specific
• Examples:
  • SENTRY_AUTH_TOKEN → For source map uploads
  • SENTRY_ORG → Organization for builds
  • VERCEL_ → Vercel system variables
  • GITHUB_ → GitHub Actions variables

Current → Recommended Mapping

Sentry

# Current (confusing)
VITE_SENTRY_DSN    # Frontend
SENTRY_DSN         # Edge Functions - same name!

# Recommended
VITE_SENTRY_DSN         # Frontend (browser)
EDGE_SENTRY_DSN         # Edge Functions (Deno)
BUILD_SENTRY_AUTH_TOKEN # CI/CD uploads

Stripe

# Current
STRIPE_SECRET_KEY       # Which service?
STRIPE_WEBHOOK_SECRET   # Which service?

# Recommended
EDGE_STRIPE_SECRET_KEY      # Edge Functions only
EDGE_STRIPE_WEBHOOK_SECRET  # Webhook handler
VITE_STRIPE_PUBLISHABLE_KEY # Frontend (if needed)

Supabase

# Current (mixed)
VITE_SUPABASE_URL          # Frontend
VITE_SUPABASE_ANON_KEY     # Frontend
SUPABASE_SERVICE_ROLE_KEY  # Backend
SUPABASE_URL               # Backend

# Recommended (clearer)
VITE_SUPABASE_URL          # Frontend URL
VITE_SUPABASE_ANON_KEY     # Frontend public key
EDGE_SUPABASE_URL          # Edge Functions URL
EDGE_SUPABASE_SERVICE_KEY  # Edge Functions admin key

Implementation Plan

1. Phase 1: Add new variables with clear names
2. Phase 2: Update code to use new names
3. Phase 3: Remove old variables

Benefits

1. No Confusion: Instantly know where a variable is used
2. Security: Harder to accidentally expose server keys
3. Debugging: Easier to track which service has issues
4. Onboarding: New developers understand the architecture

Quick Reference

Prefix	Used In	Exposed To	Example
VITE_	Frontend	Browser	VITE_SENTRY_DSN
EDGE_	Edge Functions	Server only	EDGE_SENTRY_DSN
BUILD_	CI/CD	Build only	BUILD_SENTRY_AUTH_TOKEN
None	System	Various	VERCEL_GIT_COMMIT_SHA