api-baas-firebase

Firebase Patterns

Quick Guide: Use Firebase as your backend-as-a-service for Firestore database, authentication, Cloud Functions, file storage, and hosting. Always use the modular SDK (firebase/app, firebase/firestore, etc.) for tree-shaking, type Firestore documents with TypeScript interfaces, write security rules for every collection, and use the Admin SDK only on the server.

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST use the modular Firebase SDK imports (firebase/app, firebase/firestore, firebase/auth) -- NEVER use the deprecated firebase/compat namespace API)

(You MUST write Firestore security rules for EVERY collection -- a collection without rules is wide open in production)

(You MUST NEVER expose Firebase Admin SDK credentials or service account keys in client-side code)

(You MUST use Cloud Functions v2 API (firebase-functions/v2/https, firebase-functions/v2/firestore) -- NOT the deprecated v1 API)

(You MUST handle all Firestore operations with error checking -- never assume reads/writes succeed)

</critical_requirements>

Auto-detection: Firebase, initializeApp, firebase/app, firebase/firestore, firebase/auth, getFirestore, getAuth, onAuthStateChanged, collection, doc, getDocs, setDoc, updateDoc, deleteDoc, onSnapshot, firebase-admin, firebase-functions, Cloud Functions, Firestore security rules, firebase.json, firebase deploy

When to use:

• Initializing Firebase and configuring services (Firestore, Auth, Storage, Functions)
• Implementing authentication (email/password, OAuth, phone, custom tokens)
• Querying and writing Firestore documents (CRUD, real-time listeners, transactions)
• Writing Cloud Functions v2 (HTTP handlers, callable functions, Firestore triggers, scheduled functions)
• Uploading and serving files from Firebase Storage
• Deploying to Firebase Hosting with function rewrites
• Writing Firestore and Storage security rules
• Using the Firebase Admin SDK for server-side operations

Key patterns covered:

• Modular SDK setup with initializeApp and service getters (getFirestore, getAuth, getStorage)
• Auth flows: sign up, sign in, OAuth, phone auth, onAuthStateChanged, session management
• Firestore CRUD with doc(), collection(), getDocs(), setDoc(), updateDoc(), deleteDoc()
• Firestore real-time listeners with onSnapshot()
• Firestore queries with where(), orderBy(), limit(), composite indexes
• Cloud Functions v2: onRequest, onCall, onDocumentCreated, onSchedule
• Firebase Admin SDK: initializeApp(), getFirestore(), getAuth(), custom tokens, user management
• Security rules: read/write granularity, auth-based access, data validation
• Emulator suite for local development and testing
• Offline persistence with persistentLocalCache

When NOT to use:

• Complex relational queries needing JOIN operations (use a relational database with an ORM)
• Full server-side ORM patterns (Firestore is a document database, not relational)
• Applications using a non-Firebase authentication provider
• Applications requiring complex server-side business logic beyond Cloud Functions scope

Examples:

• [Core Setup & Configuration](examples/core.md) -- App init, emulators, offline persistence
• [Firestore Database](examples/firestore.md) -- CRUD, queries, real-time listeners, transactions
• [Authentication](examples/auth.md) -- Email/password, OAuth, auth state, profile sync
• [Cloud Functions & Admin SDK](examples/functions.md) -- HTTP, callable, triggers, scheduled, Admin SDK
• [Cloud Storage](examples/storage.md) -- Upload with progress, validation, App Check
• [Security Rules](examples/security-rules.md) -- Firestore and Storage rules patterns

<philosophy>

Philosophy

Firebase is Google's Backend-as-a-Service platform providing a complete backend through Firestore (document database), Authentication, Cloud Functions, Storage, Hosting, and more. The modular SDK (v12+) uses tree-shakeable ES module imports for minimal bundle sizes.

Core principles:

1. Modular imports for tree-shaking -- Import only what you need from firebase/firestore, firebase/auth, etc. The modular SDK can reduce bundle size by 80%+ compared to the legacy namespace API.
2. Document-oriented data model -- Firestore stores data as documents in collections. Design your data model around your query patterns, not normalized relations. Denormalization is expected.
3. Security rules are mandatory -- Firestore and Storage are directly accessible from clients. Security rules are your only server-side access control. Every collection needs rules.
4. Cloud Functions v2 on Cloud Run -- 2nd generation functions run on Cloud Run with better scaling, concurrency, longer timeouts (up to 60 minutes), and traffic splitting. Always use v2 for new projects.
5. Offline-first with persistence -- Firestore supports offline persistence via IndexedDB. Enable it with persistentLocalCache for apps that must work without connectivity.
6. Admin SDK for server-side -- The Firebase Admin SDK bypasses security rules and has full access. Use it only in trusted server environments (Cloud Functions, API servers).

When to use Firebase:

• Rapid prototyping and MVPs with auth, database, and storage out of the box
• Real-time applications (chat, live dashboards, collaborative editing) via Firestore listeners
• Mobile and web apps needing offline support with automatic sync
• Projects wanting serverless backend logic with Cloud Functions
• Applications needing simple file storage with security rules

When NOT to use:

• Complex relational data with many-to-many relationships and JOINs (use a relational database)
• Applications needing full-text search (Firestore has limited query capabilities -- use a dedicated search service)
• High-write-throughput scenarios exceeding 10,000 writes/second to a single document
• Applications requiring complex server-side transactions spanning multiple services

</philosophy>

<patterns>

Core Patterns

Pattern 1: Firebase App Initialization (Modular SDK)

Initialize Firebase with the modular SDK for tree-shaking. Each service has its own import path.

// lib/firebase.ts
import { initializeApp } from "firebase/app";
import { getFirestore } from "firebase/firestore";
import { getAuth } from "firebase/auth";
import { getStorage } from "firebase/storage";

const app = initializeApp(firebaseConfig);
export const db = getFirestore(app);
export const auth = getAuth(app);
export const storage = getStorage(app);

Why good: Modular imports enable tree-shaking, each service initialized from the app instance, named exports

Full setup with emulators and offline persistence: [examples/core.md](examples/core.md)

Pattern 2: Firestore CRUD Operations

Use modular functions for all Firestore read/write operations. Always type your documents.

const POSTS_COLLECTION = "posts";

// Read
const docSnap = await getDoc(doc(db, POSTS_COLLECTION, postId));
if (!docSnap.exists()) throw new Error(`Not found: ${postId}`);

// Create with auto-ID and server timestamp
const docRef = doc(collection(db, POSTS_COLLECTION));
await setDoc(docRef, { ...data, createdAt: serverTimestamp() });

// Update specific fields
await updateDoc(doc(db, POSTS_COLLECTION, postId), {
  ...data,
  updatedAt: serverTimestamp(),
});

// Delete
await deleteDoc(doc(db, POSTS_COLLECTION, postId));

Why good: Named constants for collection names, existence check before accessing data, serverTimestamp() for consistent timestamps, typed input parameters

Full CRUD service with pagination: [examples/firestore.md](examples/firestore.md)

Pattern 3: Firestore Real-Time Listeners

Subscribe to document and collection cha