Firebase Email Collector

A simple, reusable package for collecting emails via Firebase Firestore. Perfect for landing pages, waitlists, and newsletter signups.

Installation

npm install @nback/firebase-email-collector firebase

Quick Start

import { EmailCollector } from "@nback/firebase-email-collector";

const collector = new EmailCollector(
  {
    apiKey: "YOUR_API_KEY",
    authDomain: "your-app.firebaseapp.com",
    projectId: "your-project-id",
    storageBucket: "your-app.appspot.com",
    messagingSenderId: "123456789",
    appId: "1:123456789:web:abcdef",
  },
  {
    collectionPath: "waitlist",
  }
);

// Submit an email
try {
  const result = await collector.submitEmail("[email protected]");
  console.log("Success!", result.id);
} catch (error) {
  console.error("Failed:", error);
}

Usage in HTML (CDN)

<script type="module">
  import { EmailCollector } from "https://unpkg.com/@nback/firebase-email-collector";
  import { initializeApp } from "https://www.gstatic.com/firebasejs/11.6.1/firebase-app.js";

  const collector = new EmailCollector(firebaseConfig, {
    collectionPath: "my-emails",
  });

  document.getElementById("email-form").addEventListener("submit", async (e) => {
    e.preventDefault();
    const email = document.getElementById("email-input").value;

    try {
      await collector.submitEmail(email);
      alert("Thank you!");
    } catch (error) {
      alert("Something went wrong");
    }
  });
</script>

API

new EmailCollector(firebaseConfig, options)

Creates a new email collector instance.

Parameters:

• firebaseConfig (Object) - Your Firebase configuration
• options (Object) - Optional configuration
  • collectionPath (string) - Firestore collection path (default: 'emails')
  • appName (string) - Firebase app name (default: 'email-collector')
  • additionalFields (Object) - Fields to include in every submission
  • beforeSubmit (Function) - Hook called before submission
  • onSuccess (Function) - Hook called after successful submission
  • onError (Function) - Hook called on error

submitEmail(email, customData)

Submits an email to Firestore.

Parameters:

• email (string) - Email address to submit
• customData (Object) - Additional data to include (optional)

Returns: Promise<{ success: boolean, id: string }>

isValidEmail(email)

Validates email format.

Parameters:

• email (string) - Email to validate

Returns: boolean

Advanced Usage

With Additional Fields

const collector = new EmailCollector(firebaseConfig, {
  collectionPath: "waitlist",
  additionalFields: {
    source: "landing-page",
    campaign: "launch-2024",
  },
});

await collector.submitEmail("[email protected]", {
  referrer: document.referrer,
  userAgent: navigator.userAgent,
});

With Hooks

const collector = new EmailCollector(firebaseConfig, {
  collectionPath: "emails",
  beforeSubmit: async (data) => {
    // Enrich data before submission
    return {
      ...data,
      timestamp: Date.now(),
      country: await getCountryFromIP(),
    };
  },
  onSuccess: (result) => {
    console.log("Email saved with ID:", result.id);
    gtag("event", "email_submitted");
  },
  onError: (error) => {
    console.error("Submission failed:", error);
    Sentry.captureException(error);
  },
});

Convenience Function

For simple use cases:

import { createEmailCollector } from "@nback/firebase-email-collector";

const collector = createEmailCollector(firebaseConfig, "my-collection");
await collector.submitEmail("[email protected]");

Firestore Data Structure

Each submitted email creates a document with this structure:

{
  email: "[email protected]",
  createdAt: Timestamp,
  // ... any additional fields you specified
}

Firebase Setup

1. Create a Firebase project at https://console.firebase.google.com
2. Enable Firestore Database
3. Set up security rules (example):

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /emails/{document} {
      allow create: if request.auth == null; // Allow anonymous writes
      allow read, update, delete: if false; // Deny all other operations
    }
  }
}

License

MIT