blackcanyontickets/reactrebuild0825/FIREBASE_DEPLOYMENT_GUIDE.md

Firebase Deployment Guide

This guide walks you through deploying the BCT React app to Firebase Hosting with Cloud Functions backend.

Prerequisites

1. Firebase CLI installed globally:

   npm install -g firebase-tools
   

2. Login to Firebase:

   firebase login
   

3. Initialize or select your Firebase project:

   firebase projects:list
   firebase use <your-firebase-project-id>
   

Configuration Setup

1. Environment Configuration

Development (.env.local)

Already created with placeholder values. Update with your actual development configuration:

• Firebase project config
• Stripe test keys
• Local API endpoints

Production (.env.production)

Already created with placeholder values. Update with your actual production configuration:

• Firebase project config
• Stripe live keys
• Production API endpoints (uses /api for Firebase Functions)

2. Firebase Configuration

The firebase.json is already configured with:

• Functions source in ./functions/
• Hosting pointing to ./dist/ (Vite build output)
• API rewrites: /api/** → api function
• Separate webhook functions for raw body handling
• Proper cache headers for static assets

3. Firebase Functions

The unified API function is created at functions/src/api.ts which:

• Combines all individual functions into Express routes
• Handles CORS properly for hosting origins
• Provides centralized error handling
• Maintains individual functions for backward compatibility

Deployment Steps

1. Install Functions Dependencies

npm run firebase:install
# or manually:
cd functions && npm install

2. Update Environment Variables

Important: Before deploying, update these files with your actual configuration:

• .env.local - Development settings
• .env.production - Production settings

Update the CORS origins in functions/src/api.ts with your actual Firebase hosting URLs:

const allowedOrigins = [
  "https://your-project-id.web.app",
  "https://your-project-id.firebaseapp.com",
  // ... other origins
];

3. Deploy to Staging (Preview Channel)

Test deployment first with a preview channel:

npm run firebase:deploy:preview

This will:

1. Build the React app for production
2. Deploy functions and hosting to a staging URL
3. Give you a URL like: https://staging-<hash>--<your-project-id>.web.app

4. Deploy to Production

When staging looks good, deploy to production:

npm run firebase:deploy:all

This deploys to: https://<your-project-id>.web.app

Alternative Deployment Commands

# Deploy only functions
npm run firebase:deploy:functions

# Deploy only hosting
npm run firebase:deploy:hosting

# Start local emulators for testing
npm run firebase:emulators

# Manual deploy commands
firebase deploy --only functions
firebase deploy --only hosting
firebase deploy --only hosting,functions

Local Development with Firebase Emulators

1. Start Firebase emulators:

   npm run firebase:emulators
   

2. Update local environment: In .env.local, set:

   VITE_API_BASE=http://localhost:5001/<your-project-id>/us-central1/api
   

3. Start React dev server:

   npm run dev
   

The app will call the local Firebase Functions emulator for API requests.

Verification Checklist

After deployment, verify these work:

Mobile/HTTPS Requirements ✅

• Open the preview/production URL on your phone
• Camera access works (HTTPS is required)
• QR scanner loads and functions properly
• No mixed content warnings

API Functionality ✅

• Network tab shows calls to /api/... endpoints
• Ticket verification works: POST /api/tickets/verify
• Stripe Connect flows work: POST /api/stripe/connect/start
• Health check responds: GET /api/health

PWA Features ✅

• PWA install banner appears
• App works offline (cached resources)
• Service worker registers properly

Performance ✅

• Lighthouse score > 90 for Performance
• First Contentful Paint < 2s
• Largest Contentful Paint < 2.5s

Troubleshooting

Common Issues

1. CORS Errors

   • Update allowed origins in functions/src/api.ts
   • Ensure hosting URL is included

2. API 404 Errors

   • Check function names in firebase.json rewrites
   • Verify functions deployed successfully: firebase functions:log

3. Build Errors

   • Run npm run typecheck to catch TypeScript errors
   • Run npm run lint:fix to fix code style issues

4. Environment Variables Not Loading

   • Ensure .env.production exists and has correct values
   • Check Vite environment variable naming (must start with VITE_)

Debug Commands

# View function logs
firebase functions:log

# Check deployment status
firebase projects:list

# View hosting info
firebase hosting:sites:list

# Test functions locally
npm run firebase:emulators

Security Notes

• Environment files are not committed to git
• Stripe webhook signatures are verified
• CORS is properly configured
• HTTPS is enforced by Firebase Hosting
• No sensitive data in client-side code

Production Readiness

This setup provides:

• ✅ HTTPS everywhere (required for PWA + camera)
• ✅ Scalable Functions (max 10 instances)
• ✅ Global CDN via Firebase Hosting
• ✅ Proper caching headers
• ✅ Error monitoring and logging
• ✅ Mobile-optimized performance