Skip to main content

Environment Setup

Environment variables are split between extension apps (browser) and backend (server). All keys live in the root envs/ directory.

Extension Apps (Vite)​

The extension entry apps (apps/main, apps/popup, apps/in-page, apps/background) read env vars from:

  • envs/.env.development — local dev
  • envs/.env.production — production build

The shared Vite config (@repo/vite-config) sets envDir to envs/, so all apps use the same env files.

Start from: envs/.env.example

Set VITE_BACKEND to supabase, firebase, or custom. See Choosing Your Backend for copy-paste env blocks per backend. Or run pnpm choose:backend for an interactive wizard.

Create:

  • envs/.env.development for local development
  • envs/.env.production for production builds

Required Keys by Integration​

IntegrationRequired Keys
SupabaseVITE_SUPABASE_URL, VITE_SUPABASE_ANON_KEY
FirebaseVITE_FIREBASE_API_KEY, VITE_FIREBASE_AUTH_DOMAIN, VITE_FIREBASE_PROJECT_ID
StripeVITE_STRIPE_PUBLISHABLE_KEY
Stripe (optional)VITE_STRIPE_PRICE_ID_MONTHLY, VITE_STRIPE_PRICE_ID_YEARLY — fallback for edge checkout
CustomVITE_CUSTOM_API_URL, VITE_CUSTOM_COOKIE_DOMAIN, VITE_CUSTOM_COOKIE_NAME (when VITE_BACKEND=custom)

Validation​

  • Env is validated at runtime in background startup via Zod
  • If you provide any key for an integration, all required keys for that integration must be present
  • Invalid configuration throws a clear startup error listing missing keys

Choose One Backend Runtime​

Use one server backend for auth/database and server flows:

  • Supabase: apps/supabase/functions/*
  • Firebase: apps/firebase/functions/*

Both backends use server secrets from envs/* and must not depend on browser-only VITE_* keys.

Supabase Backend​

Use envs/.env.supabase.local. Common keys:

  • SUPABASE_URL
  • SUPABASE_SERVICE_ROLE_KEY
  • STRIPE_API_KEY
  • STRIPE_PRICE_ID_MONTHLY, STRIPE_PRICE_ID_YEARLY
  • STRIPE_WEBHOOK_SIGNING_SECRET
  • RESEND_API_KEY

Local development:

supabase functions serve --env-file envs/.env.supabase.local

Firebase Backend​

Use envs/.env.firebase.local. Common keys:

  • FIREBASE_PROJECT_ID
  • FIREBASE_CLIENT_EMAIL
  • FIREBASE_PRIVATE_KEY
  • STRIPE_API_KEY
  • STRIPE_PRICE_ID_MONTHLY, STRIPE_PRICE_ID_YEARLY
  • STRIPE_WEBHOOK_SIGNING_SECRET

Rule of Thumb​

  • Browser extension code: only VITE_* keys in envs/*
  • Supabase backend mode: server secrets in envs/.env.supabase.local
  • Firebase backend mode: server secrets in envs/.env.firebase.local
  • Do not run both backends for the same environment unless you explicitly need both