MailComposer/FIREBASE_SETUP.md

Firebase Setup Guide for Mail Composer

This guide will help you set up Firebase for your Mail Composer application to send real emails.

Prerequisites

1. A Google account
2. Node.js installed on your machine
3. Firebase CLI installed globally: npm install -g firebase-tools

Step 1: Create a Firebase Project

1. Go to the Firebase Console
2. Click "Add project"
3. Enter a project name (e.g., "mail-composer")
4. Enable Google Analytics (optional)
5. Create the project

Step 2: Enable Firestore Database

1. In your Firebase project console, go to "Firestore Database"
2. Click "Create database"
3. Choose "Start in test mode" for now
4. Select a location for your database

Step 3: Set up Firebase Functions

1. In the Firebase console, go to "Functions"
2. Click "Get started"
3. This will enable the Cloud Functions API

Step 4: Configure Email Service

Option A: Gmail (Recommended for development)

1. Enable 2-factor authentication on your Gmail account
2. Generate an App Password:
   • Go to Google Account settings
   • Security → 2-Step Verification → App passwords
   • Generate a password for "Mail"
   • Save this password securely

Option B: Other Email Providers

Configure SMTP settings for your email provider (SendGrid, Mailgun, etc.)

Step 5: Configure Your Local Environment

1. Copy the environment file:

   cp .env.example .env
   

2. Get your Firebase configuration:

   • In Firebase console, go to Project Settings (gear icon)
   • Scroll down to "Your apps"
   • Click the web icon </>
   • Register your app with a nickname
   • Copy the config object values

3. Update your .env file with the Firebase config values:

   VITE_FIREBASE_API_KEY=your-actual-api-key
   VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
   VITE_FIREBASE_PROJECT_ID=your-actual-project-id
   VITE_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
   VITE_FIREBASE_MESSAGING_SENDER_ID=your-actual-sender-id
   VITE_FIREBASE_APP_ID=your-actual-app-id
   

Step 6: Deploy Firebase Functions

1. Login to Firebase CLI:

   firebase login
   

2. Initialize Firebase in your project:

   firebase init
   

   • Select "Functions", "Firestore", and "Hosting"
   • Choose your existing project
   • Accept defaults for most options

3. Install function dependencies:

   cd functions
   npm install
   cd ..
   

4. Set environment variables for functions:

   firebase functions:config:set gmail.user="your-email@gmail.com"
   firebase functions:config:set gmail.password="your-app-password"
   

5. Deploy functions:

   firebase deploy --only functions
   

Step 7: Update Firestore Security Rules

1. Go to Firestore Database → Rules
2. Replace the rules with the content from firestore.rules
3. Publish the rules

Step 8: Test the Application

1. Start your development server:

   npm run dev
   

2. Open the application and try sending a test email

Alternative Email Services

SendGrid

// In functions/index.js, replace the transporter with:
const sgMail = require('@sendgrid/mail');
sgMail.setApiKey(process.env.SENDGRID_API_KEY);

Mailgun

// In functions/index.js, replace the transporter with:
const formData = require('form-data');
const Mailgun = require('mailgun.js');
const mailgun = new Mailgun(formData);
const mg = mailgun.client({
  username: 'api',
  key: process.env.MAILGUN_API_KEY,
  url: 'https://api.mailgun.net' // or 'https://api.eu.mailgun.net'
});

Security Considerations

1. Never commit your .env file - it's already in .gitignore
2. Use Firebase Security Rules to protect your Firestore data
3. Implement user authentication for production use
4. Set rate limits in Firebase Functions to prevent abuse
5. Validate all inputs on both client and server side

Troubleshooting

Common Issues

1. "Permission denied" errors

   • Check your Firestore security rules
   • Ensure your Firebase project is properly configured

2. Email sending fails

   • Verify your email credentials
   • Check Firebase Functions logs: firebase functions:log
   • Ensure "Less secure app access" is disabled and App Password is used

3. "Function not found" errors

   • Ensure functions are deployed: firebase deploy --only functions
   • Check function names match in your code

4. CORS errors

   • Functions should handle CORS automatically
   • Check browser developer console for specific errors

Getting Help

• Check Firebase Functions logs: firebase functions:log
• View Firestore data in the Firebase console
• Check browser developer console for client-side errors

Production Deployment

1. Build the application:

   npm run build
   

2. Deploy to Firebase Hosting:

   firebase deploy
   

Your application will be available at https://your-project-id.web.app