Environment Setup — Quick Start Guide

Time to complete: ~20 minutes

Follow these steps in order to get your local development environment running and deployments configured.

Environment Detection Pattern

IMPORTANT: When adding dev-only features (debug panels, simulate buttons, etc.), use hostname-based detection:

javascript

const hostname = typeof window !== 'undefined' ? window.location.hostname : ''
const isProductionEnv = import.meta.env.VITE_APP_ENV === 'production' || hostname === 'ourlantern.app'
const isDev = !isProductionEnv

Why hostname check?

import.meta.env.DEV only works on localhost (Vite dev server)
Deployed dev sites (dev.ourlantern.app) need hostname detection
Production site (ourlantern.app) should hide all dev features

Examples in codebase:

src/screens/dashboard/Dashboard.jsx - "Simulate Wave" button
src/screens/profile/ProfileSettings.jsx - Location spoof panel
src/firebase.js - Firebase environment logging

Step-by-Step Checklist

✅ Step 1: Install Dependencies (2 min)

bash

cd lantern_app
npm install

Verify: Run npm --version — should show v8 or higher.

✅ Step 2: Create Firebase DEV Project (5 min)

Go to https://console.firebase.google.com
Click "Add project"
Name: lantern-app-dev
Disable Google Analytics (or enable if you want)
Click "Create project"

Wait for project to be created (~1 minute).

✅ Step 3: Enable Firebase Services in DEV (3 min)

In your lantern-app-dev project:

Authentication:

Click "Authentication" in left sidebar
Click "Get started"
Click "Email/Password"
Enable the toggle
Click "Save"

Firestore Database:

Click "Firestore Database"
Click "Create database"
Choose "Start in test mode"
Select region (e.g., us-central1)
Click "Enable"

Storage:

Click "Storage"
Click "Get started"
Start in test mode
Click "Next" → "Done"

✅ Step 4: Get Firebase DEV Config (2 min)

In Firebase Console, click ⚙️ (gear icon) → "Project settings"
Scroll down to "Your apps"
Click web icon </> (if no apps exist)
App nickname: "Lantern Dev"
Click "Register app"
COPY the config object that looks like:

javascript

const firebaseConfig = {
  apiKey: "AIzaSy...",
  authDomain: "lantern-app-dev.firebaseapp.com",
  projectId: "lantern-app-dev",
  storageBucket: "lantern-app-dev.appspot.com",
  messagingSenderId: "123456789",
  appId: "1:123456789:web:abc..."
};

⚠️ Keep this open — you'll need it in the next step!

✅ Step 5: Set Up Local Environment File (2 min)

In your terminal:

bash

# Copy the example file
cp .env.local.example .env.local

Open .env.local in your editor and paste your Firebase config values:

bash

VITE_FIREBASE_API_KEY=AIzaSy...  # Copy from firebaseConfig.apiKey
VITE_FIREBASE_AUTH_DOMAIN=lantern-app-dev.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=lantern-app-dev
VITE_FIREBASE_STORAGE_BUCKET=lantern-app-dev.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=123456789
VITE_FIREBASE_APP_ID=1:123456789:web:abc...
VITE_APP_ENV=local

# OPTIONAL: Development Location Spoofing
# For testing venue-based features without leaving home
# Format: "latitude,longitude" (no spaces)
# Example: VITE_DEV_TEST_LOCATION="40.7128,-74.0060"
VITE_DEV_TEST_LOCATION=""

Save the file.

🧪 Optional: Location Spoofing for Development

Lantern includes location-based features (check-ins, nearby users, venue offers). To test these features without physically visiting venues, you can spoof your location in development.

Two ways to set your test location:

Option 1: Environment Variable (Auto-loads on startup)

In .env.local, set your test coordinates:

bash

VITE_DEV_TEST_LOCATION="40.7128,-74.0060"

Get coordinates from Google Maps:

Right-click any location on Google Maps
Click the coordinates that appear (e.g., "40.7128, -74.0060")
They'll copy to your clipboard
Paste into .env.local

Restart dev server for changes to take effect.

Option 2: Debug Panel (Change on-the-fly)

When running in development mode (npm run dev):

Go to Profile Settings (#/profile)
Click the "Privacy" tab
Scroll down to see the purple "🚧 Dev: Location Spoofing" panel
Enter latitude and longitude
Click "Set Location"

The spoofed location persists in localStorage until you clear it.

Tip: Spoof your location to:

Your home address (for testing from home)
A local bar/venue (test venue check-ins)
Different cities (test geographic features)

⚠️ Location spoofing is only available in development mode — production builds automatically use real geolocation.

✅ Step 6: Test Local Development (1 min)

bash

npm run dev

Open browser to http://localhost:5173

Verify:

App loads without errors
Open browser console (F12)
Look for: 🔥 Firebase initialized (local environment)
Check it says Project: lantern-app-dev

✅ Success! Your local environment is working!

Press Ctrl+C to stop the dev server.

✅ Step 7: Create Firebase PRODUCTION Project (5 min)

Repeat Steps 2-4 but name the project lantern-app-prod:

Firebase Console → Add project
Name: lantern-app-prod
Enable Authentication, Firestore, Storage (same as dev)
Get the config (⚙️ → Project settings → Add web app → "Lantern Prod")

⚠️ Save both configs (dev AND prod) — you'll need them for Cloudflare.

✅ Step 8: Set Up Cloudflare Pages (10 min)

Prerequisites: Have your GitHub repo cattreedev/lantern_app ready.

8.1: Create Cloudflare Pages Project

Go to https://dash.cloudflare.com
Click "Pages" in left sidebar
Click "Create a project"
Click "Connect to Git"
Authorize GitHub (if needed)
Select repository: cattreedev/lantern_app
Click "Begin setup"

8.2: Configure Build Settings

Project name: lantern-app
Production branch: main
Build command: npm run build
Build output directory: dist
Root directory: (leave empty or /)

Click "Save and Deploy" (it will fail first time — that's OK!)

8.3: Set Environment Variables

Go to your Cloudflare Pages project
Click "Settings" → "Environment variables"

For Production (main branch):

Click "Add variable" for each of these (using your lantern-app-prod config):

Variable Name	Value (from lantern-app-prod)
`VITE_FIREBASE_API_KEY`	`AIzaSy...` (prod)
`VITE_FIREBASE_AUTH_DOMAIN`	`lantern-app-prod.firebaseapp.com`
`VITE_FIREBASE_PROJECT_ID`	`lantern-app-prod`
`VITE_FIREBASE_STORAGE_BUCKET`	`lantern-app-prod.appspot.com`
`VITE_FIREBASE_MESSAGING_SENDER_ID`	`123...` (prod)
`VITE_FIREBASE_APP_ID`	`1:123...` (prod)
`VITE_APP_ENV`	`production`
`NODE_VERSION`	`20`

For Preview (all other branches):

Repeat above, but use values from lantern-app-dev config:

Variable Name	Value (from lantern-app-dev)
`VITE_FIREBASE_API_KEY`	`AIzaSy...` (dev)
`VITE_FIREBASE_AUTH_DOMAIN`	`lantern-app-dev.firebaseapp.com`
`VITE_FIREBASE_PROJECT_ID`	`lantern-app-dev`
`VITE_FIREBASE_STORAGE_BUCKET`	`lantern-app-dev.appspot.com`
`VITE_FIREBASE_MESSAGING_SENDER_ID`	`123...` (dev)
`VITE_FIREBASE_APP_ID`	`1:123...` (dev)
`VITE_APP_ENV`	`development`
`NODE_VERSION`	`20`

Click "Save"

✅ Step 9: Trigger First Deployment

In your terminal:

bash

# Make a small change to trigger deployment
echo "# Deployment test" >> README.md

# Commit and push
git add .
git commit -m "Configure deployment environment"
git push origin main

Wait ~2 minutes for build.

Go to Cloudflare Pages → "Deployments" to watch progress.

✅ Success! When build completes, visit your production URL!

✅ Step 10: Create Dev Branch

bash

# Create dev branch from main
git checkout -b dev
git push origin dev

In Cloudflare Pages:

Go to Settings → Builds & deployments
Verify "Preview deployments" is enabled for all branches

Now when you push to dev, it auto-deploys to a preview URL!

🎉 You're Done!

What You Just Set Up

✅ Local development environment
✅ Two Firebase projects (dev + prod)
✅ Cloudflare Pages automatic deployments
✅ Environment-specific configurations
✅ Git branch strategy (main for prod, dev for staging)

Your Workflow Now

Daily development:

bash

# 1. Work locally
npm run dev

# 2. Commit changes
git add .
git commit -m "Add feature"

# 3. Push to dev branch
git push origin dev
# → Auto-deploys to preview URL for testing

# 4. When ready, merge to main
git checkout main
git merge dev
git push origin main
# → Auto-deploys to production!

Common Issues & Fixes

Build fails on Cloudflare:

Check you set NODE_VERSION=20
Verify all VITE_* variables are set
Check build logs in Cloudflare dashboard

"Firebase not initialized" error:

Verify environment variables in Cloudflare
Ensure variable names start with VITE_
Check spelling/typos in variable names

Wrong Firebase project connecting:

Check which branch you're on
Verify Cloudflare environment variables for Production vs Preview
Look in browser console for "Firebase initialized" message

Next Steps

Now that environment is set up:

📖 Read DEPLOYMENT.md for full deployment guide
🔒 Add Firebase Security Rules (don't leave in test mode!)
🔐 Set up Cloudflare Access for password protection
🚀 Start building features!

Need help? Check docs/engineering/ or open an issue!

Environment Setup — Quick Start Guide ​

Environment Detection Pattern ​

Step-by-Step Checklist ​

✅ Step 1: Install Dependencies (2 min) ​

✅ Step 2: Create Firebase DEV Project (5 min) ​

✅ Step 3: Enable Firebase Services in DEV (3 min) ​

✅ Step 4: Get Firebase DEV Config (2 min) ​

✅ Step 5: Set Up Local Environment File (2 min) ​

🧪 Optional: Location Spoofing for Development ​

Option 1: Environment Variable (Auto-loads on startup) ​

Option 2: Debug Panel (Change on-the-fly) ​

✅ Step 6: Test Local Development (1 min) ​

✅ Step 7: Create Firebase PRODUCTION Project (5 min) ​

✅ Step 8: Set Up Cloudflare Pages (10 min) ​

8.1: Create Cloudflare Pages Project ​

8.2: Configure Build Settings ​

8.3: Set Environment Variables ​

✅ Step 9: Trigger First Deployment ​

✅ Step 10: Create Dev Branch ​

🎉 You're Done! ​

What You Just Set Up ​

Your Workflow Now ​

Common Issues & Fixes ​

Next Steps ​

Environment Setup — Quick Start Guide

Environment Detection Pattern

Step-by-Step Checklist

✅ Step 1: Install Dependencies (2 min)

✅ Step 2: Create Firebase DEV Project (5 min)

✅ Step 3: Enable Firebase Services in DEV (3 min)

✅ Step 4: Get Firebase DEV Config (2 min)

✅ Step 5: Set Up Local Environment File (2 min)

🧪 Optional: Location Spoofing for Development

Option 1: Environment Variable (Auto-loads on startup)

Option 2: Debug Panel (Change on-the-fly)

✅ Step 6: Test Local Development (1 min)

✅ Step 7: Create Firebase PRODUCTION Project (5 min)

✅ Step 8: Set Up Cloudflare Pages (10 min)

8.1: Create Cloudflare Pages Project

8.2: Configure Build Settings

8.3: Set Environment Variables

✅ Step 9: Trigger First Deployment

✅ Step 10: Create Dev Branch

🎉 You're Done!

What You Just Set Up

Your Workflow Now

Common Issues & Fixes

Next Steps