FrappDocs
Docs/Guide

Environment & Configuration

This guide explains how we configure Frapp across local, staging, and production environments.

1. Environment matrix

We maintain three main environments:

  • Local — developer machine, Supabase CLI + Docker, *.env.local files
  • Staging — Supabase Cloud (staging project), containerized API, Vercel preview frontends
  • Production — Supabase Cloud (prod project), API with multiple replicas, Vercel prod frontends

2. Environment variables by app

API (apps/api)

Local (apps/api/.env.local):

SUPABASE_URL=http://127.0.0.1:54321
SUPABASE_SERVICE_ROLE_KEY=...
SUPABASE_ANON_KEY=...
STRIPE_SECRET_KEY=...
STRIPE_WEBHOOK_SECRET=...
STRIPE_PRICE_ID=...
PORT=3001
NODE_ENV=development

Staging/production:

  • Same variable names as local.
  • Values are stored in the hosting platform's secret manager (Railway/Render/AWS).

Web (apps/web) and Landing (apps/landing)

Local (.env.local):

NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=...
NEXT_PUBLIC_API_URL=http://localhost:3001

Staging/production:

  • NEXT_PUBLIC_SUPABASE_URL points at the staging/prod Supabase project.
  • NEXT_PUBLIC_API_URL points at the deployed API base URL.
  • Configured in Vercel project settings.

Mobile (apps/mobile)

Local (.env.local):

EXPO_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
EXPO_PUBLIC_SUPABASE_ANON_KEY=...
EXPO_PUBLIC_API_URL=http://localhost:3001

Staging/production:

  • Same env names, different values per EAS profile (staging, production).

3. Config module in the API

The NestJS API uses @nestjs/config to load environment variables:

  • Reads from process.env and .env.local in development.
  • Provides typed access to configuration (database, Supabase, Stripe, etc.).
  • Centralizes validation of required variables.

When adding new env vars:

  • Add them to the config module.
  • Update .env.example files (API, web, landing, mobile).
  • Document them in this guide if they matter to other developers.

4. Secrets and safety

Warning

Never commit real secrets. Only commit .env.example files with placeholder values.

  • Use .env.local for local only values.
  • Use your hosting provider's secret manager for staging/production.
  • Rotate keys if they are ever exposed.

5. Supabase projects

We use separate Supabase projects for:

  • Local — CLI-managed project via supabase start
  • Staging — Cloud project in test mode
  • Production — Cloud project with real data

Rules:

  • Schema is identical across environments (migrations from supabase/migrations/).
  • Never manually edit the prod schema via the UI without a migration.
  • Keep staging as close to production as possible (schema + configuration).