git:20260316.d7ef49c to git:20260316.7fd397a

---

name: api-baas-firebase

description: Firebase backend-as-a-service — Firestore, Authentication, Cloud Functions v2, Storage, Hosting, Admin SDK, security rules, emulator suite

---

# 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 NEVER expose Firebase Admin SDK credentials or service account keys in client-side code)**

</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 SQL database with Drizzle/Prisma)

- Full server-side ORM patterns (Firestore is a document database, not relational)

- Non-Firebase authentication providers (use dedicated auth skills)

- Applications requiring complex server-side business logic beyond Cloud Functions scope

---

<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:**

**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)

- 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.

```typescript

// 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);

```

---

### Pattern 2: Firestore CRUD Operations

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

```typescript

const POSTS_COLLECTION = "posts";

// Update specific fields

```

---

### Pattern 3: Firestore Real-Time Listeners

Subscribe to document and collection changes with `onSnapshot`. Always unsubscribe to prevent memory leaks.

```typescript

function subscribeToPublishedPosts(

onUpdate: (posts: Post[]) => void,

onError: (error: Error) => void,

): Unsubscribe {

const q = query(

where("published", "==", true),

orderBy("createdAt", "desc"),

);

return onSnapshot(

q,

(snapshot) => {

);

},

(error) => {

},

);

}

```

---

### Pattern 4: Firestore Transactions and Batched Writes

Use transactions for atomic read-then-write operations. Use batched writes for multiple writes without reads.

```typescript

}

```

---

### Pattern 5: Authentication Flows

Use Firebase Authentication with the modular SDK. Handle auth state changes with `onAuthStateChanged`.

```typescript

```

---

### Pattern 6: Cloud Functions v2

Write Cloud Functions using the v2 API. Import from `firebase-functions/v2/*` subpackages.

```typescript

import { onRequest } from "firebase-functions/v2/https";

export const getPosts = onRequest(

{ cors: true, region: "us-central1" },

async (req, res) => {

},

);

import { onCall, HttpsError } from "firebase-functions/v2/https";

export const createPost = onCall({ region: "us-central1" }, async (request) => {

});

import { onDocumentCreated } from "firebase-functions/v2/firestore";

export const onPostCreated = onDocumentCreated(

{ document: "posts/{postId}", region: "us-central1" },

async (event) => {

},

);

import { onSchedule } from "firebase-functions/v2/scheduler";

{ schedule: "every 24 hours", region: "us-central1" },

async () => {

},

);

```

---

### Pattern 7: Firebase Admin SDK (Server-Side)

```typescript

import { getFirestore } from "firebase-admin/firestore";

import { getAuth } from "firebase-admin/auth";

export const adminDb = getFirestore();

export const adminAuth = getAuth();

```

---

### Pattern 8: Firebase Storage

```typescript

```

---

### Pattern 9: Security Rules

```

rules_version = '2';

service cloud.firestore {

match /databases/{database}/documents {

match /posts/{postId} {

allow read: if resource.data.published == true

|| isOwner(resource.data.authorId);

allow create: if isAuthenticated()

}

}

}

```

</patterns>

---

<performance>

## Performance Optimization

### Query Performance

### Bundle Size

### Cloud Functions

</performance>

---

<decision_framework>

## Decision Framework

### Firestore vs Realtime Database

```

What does your app need?

+-- Complex queries (where, orderBy, compound) --> Firestore

+-- Simple key-value lookups with low latency --> Realtime Database

+-- Offline support with rich queries --> Firestore

+-- Presence system (online/offline status) --> Realtime Database

+-- Multi-region availability --> Firestore

+-- Very frequent small updates (typing indicators) --> Realtime Database

+-- For most new projects --> Firestore (recommended default)

```

### Auth Method Selection

```

What auth flow does the user need?

+-- Email + Password --> createUserWithEmailAndPassword / signInWithEmailAndPassword

+-- Social login (Google, GitHub, etc.) --> signInWithPopup / signInWithRedirect

+-- Phone + SMS --> signInWithPhoneNumber (requires reCAPTCHA)

+-- Email link (passwordless) --> sendSignInLinkToEmail

+-- Custom backend auth --> Admin SDK createCustomToken + client signInWithCustomToken

+-- Anonymous (guest) --> signInAnonymously (upgrade later with linkWithCredential)

```

### Cloud Functions: onRequest vs onCall

```

Who is calling the function?

+-- External webhooks, third-party services --> onRequest (raw HTTP)

+-- Your own client app (web/mobile) --> onCall (automatic auth, input validation)

+-- Firestore document changes --> onDocumentCreated / onDocumentUpdated / onDocumentDeleted

+-- Scheduled/cron tasks --> onSchedule

+-- Authentication events --> onUserCreated / onUserDeleted (from firebase-functions/v2/identity)

```

### Client SDK vs Admin SDK

```

Where is the code running?

+-- NEVER use Admin SDK in client code --> It bypasses all security

```

### Storage: When to Use Firebase Storage

```

What kind of files?

+-- User-generated content (avatars, uploads) --> Firebase Storage with security rules

+-- Public static assets (CSS, images) --> Firebase Hosting (faster CDN)

+-- Large files with progress tracking --> Firebase Storage with uploadBytesResumable

+-- Server-generated files (reports, exports) --> Firebase Storage via Admin SDK

```

</decision_framework>

---

<integration>

## Integration Guide

**Works with:**

- **React / Next.js**: Use `onAuthStateChanged` in a context provider, Firestore listeners in `useEffect` with cleanup

- **React Query / TanStack Query**: Wrap Firestore reads in query functions, use `onSnapshot` for real-time invalidation

- **Firebase Hosting + Cloud Functions**: Rewrite rules in `firebase.json` route requests to functions

- **App Check**: Protect your backend resources from abuse by verifying requests come from your app (`initializeAppCheck` with reCAPTCHA Enterprise)

- **Firebase Extensions**: Pre-built Cloud Functions for common tasks (Stripe payments, image resizing, email sending)

**Replaces / Conflicts with:**

</integration>

---

<red_flags>

## RED FLAGS

**High Priority Issues:**

**Medium Priority Issues:**

**Common Mistakes:**

**Gotchas & Edge Cases:**

</red_flags>

---

<critical_reminders>

## CRITICAL REMINDERS

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

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

**Failure to follow these rules will create security vulnerabilities, bloated bundles, deprecated code paths, and silent runtime failures.**

</critical_reminders>