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:**
   ```bash
   npm install -g firebase-tools
   ```

2. **Login to Firebase:**
   ```bash
   firebase login
   ```

3. **Initialize or select your Firebase project:**
   ```bash
   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
```bash
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:
```typescript
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:

```bash
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:

```bash
npm run firebase:deploy:all
```

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

## Alternative Deployment Commands

```bash
# 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:**
   ```bash
   npm run firebase:emulators
   ```

2. **Update local environment:**
   In `.env.local`, set:
   ```bash
   VITE_API_BASE=http://localhost:5001/<your-project-id>/us-central1/api
   ```

3. **Start React dev server:**
   ```bash
   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

```bash
# 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