# Firebase -- Authentication Examples

> Email/password auth, OAuth providers, auth state management, and token handling. See [SKILL.md](../SKILL.md) for core concepts and [reference.md](../reference.md) for quick lookups.

**Related examples:**

- [core.md](core.md) -- Firebase project setup, emulator suite
- [firestore.md](firestore.md) -- Firestore CRUD, queries, real-time listeners
- [functions.md](functions.md) -- Cloud Functions v2, Admin SDK
- [storage.md](storage.md) -- File upload, download, delete
- [security-rules.md](security-rules.md) -- Firestore and Storage security rules

---

## Email/Password Auth

```typescript
import {
  createUserWithEmailAndPassword,
  signInWithEmailAndPassword,
  signOut,
  onAuthStateChanged,
  type User,
  type Unsubscribe,
} from "firebase/auth";
import { auth } from "../lib/firebase";

// Sign up
async function signUp(email: string, password: string): Promise<User> {
  const credential = await createUserWithEmailAndPassword(
    auth,
    email,
    password,
  );
  return credential.user;
}

// Sign in
async function signIn(email: string, password: string): Promise<User> {
  const credential = await signInWithEmailAndPassword(auth, email, password);
  return credential.user;
}

// Sign out
async function logOut(): Promise<void> {
  await signOut(auth);
}

// Listen to auth state -- register early in app lifecycle
function subscribeToAuthState(
  callback: (user: User | null) => void,
): Unsubscribe {
  return onAuthStateChanged(auth, callback);
}
```

---

## OAuth (Social Login)

```typescript
import {
  signInWithPopup,
  signInWithRedirect,
  GoogleAuthProvider,
  GithubAuthProvider,
  type User,
} from "firebase/auth";
import { auth } from "../lib/firebase";

const googleProvider = new GoogleAuthProvider();
const githubProvider = new GithubAuthProvider();

// Sign in with Google (popup)
async function signInWithGoogle(): Promise<User> {
  const result = await signInWithPopup(auth, googleProvider);
  return result.user;
}

// Sign in with GitHub (redirect -- better for mobile)
async function signInWithGithub(): Promise<void> {
  await signInWithRedirect(auth, githubProvider);
}
```

---

## Get Current User Token (for API calls)

```typescript
import { auth } from "../lib/firebase";

async function getIdToken(): Promise<string | null> {
  const user = auth.currentUser;

  if (!user) {
    return null;
  }

  // Force refresh if token is expired
  return user.getIdToken(/* forceRefresh */ true);
}

// Use in API calls
async function fetchFromApi(endpoint: string): Promise<Response> {
  const token = await getIdToken();

  if (!token) {
    throw new Error("User not authenticated");
  }

  return fetch(endpoint, {
    headers: { Authorization: `Bearer ${token}` },
  });
}
```

**Key patterns:** Modular imports for each auth function, typed `User` return values, `Unsubscribe` for cleanup, separate providers as constants, token retrieval with force refresh for API calls

---

## Auth Service with User Profile Sync

A complete auth service that manages sign-up with Firestore profile creation, OAuth with profile sync, and auth state observation.

```typescript
// services/auth-service.ts
import {
  onAuthStateChanged,
  signInWithEmailAndPassword,
  createUserWithEmailAndPassword,
  signInWithPopup,
  GoogleAuthProvider,
  signOut,
  type User,
  type Unsubscribe,
} from "firebase/auth";
import { doc, setDoc, serverTimestamp } from "firebase/firestore";
import { auth, db } from "../lib/firebase";

// --- Constants ---

const USERS_COLLECTION = "users";

// --- Auth State Observer ---

export function subscribeToAuthState(
  callback: (user: User | null) => void,
): Unsubscribe {
  return onAuthStateChanged(auth, callback);
}

// --- Sign Up with Profile Creation ---

const googleProvider = new GoogleAuthProvider();

export async function signUp(
  email: string,
  password: string,
  displayName: string,
): Promise<User> {
  const credential = await createUserWithEmailAndPassword(
    auth,
    email,
    password,
  );

  // Create user profile document in Firestore
  await setDoc(doc(db, USERS_COLLECTION, credential.user.uid), {
    email,
    displayName,
    createdAt: serverTimestamp(),
  });

  return credential.user;
}

// --- OAuth with Profile Sync ---

export async function signInWithGoogle(): Promise<User> {
  const result = await signInWithPopup(auth, googleProvider);

  // Create/update user profile on first OAuth sign-in
  await setDoc(
    doc(db, USERS_COLLECTION, result.user.uid),
    {
      email: result.user.email,
      displayName: result.user.displayName,
      photoURL: result.user.photoURL,
      lastLoginAt: serverTimestamp(),
    },
    { merge: true },
  );

  return result.user;
}

// --- Sign In / Sign Out ---

export async function signIn(email: string, password: string): Promise<User> {
  const credential = await signInWithEmailAndPassword(auth, email, password);
  return credential.user;
}

export async function logOut(): Promise<void> {
  await signOut(auth);
}
```

**Key patterns:** Framework-agnostic auth service (wire into your framework's state/context layer), `subscribeToAuthState` returns `Unsubscribe` for cleanup, profile creation on sign-up with `serverTimestamp()`, `merge: true` for OAuth profile updates (don't overwrite existing data), typed `User` return values

---

_For core concepts, see [SKILL.md](../SKILL.md). For quick reference tables, see [reference.md](../reference.md)._

# Firebase -- Core Examples

> Project initialization, modular SDK setup, emulator connections, and environment configuration. See [SKILL.md](../SKILL.md) for core concepts and [reference.md](../reference.md) for quick lookups.

**Related examples:**

- [firestore.md](firestore.md) -- Firestore CRUD, queries, real-time listeners
- [auth.md](auth.md) -- Authentication flows
- [functions.md](functions.md) -- Cloud Functions v2, Admin SDK
- [storage.md](storage.md) -- File upload, download, delete
- [security-rules.md](security-rules.md) -- Firestore and Storage security rules

---

## 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";
import { getFunctions } from "firebase/functions";

const firebaseConfig = {
  apiKey: process.env.FIREBASE_API_KEY!,
  authDomain: process.env.FIREBASE_AUTH_DOMAIN!,
  projectId: process.env.FIREBASE_PROJECT_ID!,
  storageBucket: process.env.FIREBASE_STORAGE_BUCKET!,
  messagingSenderId: process.env.FIREBASE_MESSAGING_SENDER_ID!,
  appId: process.env.FIREBASE_APP_ID!,
};

// Initialize Firebase -- call once at app startup
const app = initializeApp(firebaseConfig);

// Export service instances
export const db = getFirestore(app);
export const auth = getAuth(app);
export const storage = getStorage(app);
export const functions = getFunctions(app);
```

**Why good:** Modular imports enable tree-shaking, environment variables keep config out of code, each service initialized from the app instance, named exports for all services

```typescript
// BAD: Legacy compat namespace API
import firebase from "firebase/compat/app";
import "firebase/compat/firestore";
import "firebase/compat/auth";

firebase.initializeApp({
  apiKey: "AIza...", // Hardcoded
  projectId: "my-project",
});

const db = firebase.firestore();
const auth = firebase.auth();
export default { db, auth };
```

**Why bad:** Compat imports prevent tree-shaking (entire SDK bundled), hardcoded credentials leak in source control, side-effect imports, default export

---

## Emulator Suite for Local Development

Use the Firebase Emulator Suite for local development and testing without touching production data.

### Connect to Emulators

```typescript
// lib/firebase.ts -- add emulator connections in development
import { initializeApp } from "firebase/app";
import { getFirestore, connectFirestoreEmulator } from "firebase/firestore";
import { getAuth, connectAuthEmulator } from "firebase/auth";
import { getStorage, connectStorageEmulator } from "firebase/storage";
import { getFunctions, connectFunctionsEmulator } from "firebase/functions";

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

const FIRESTORE_EMULATOR_PORT = 8080;
const AUTH_EMULATOR_PORT = 9099;
const STORAGE_EMULATOR_PORT = 9199;
const FUNCTIONS_EMULATOR_PORT = 5001;

if (process.env.NODE_ENV === "development") {
  connectFirestoreEmulator(db, "localhost", FIRESTORE_EMULATOR_PORT);
  connectAuthEmulator(auth, `http://localhost:${AUTH_EMULATOR_PORT}`);
  connectStorageEmulator(storage, "localhost", STORAGE_EMULATOR_PORT);
  connectFunctionsEmulator(functions, "localhost", FUNCTIONS_EMULATOR_PORT);
}
```

### Start Emulators

```bash
# Install Firebase CLI
npm install -g firebase-tools

# Initialize project (creates firebase.json)
firebase init

# Start all emulators with data persistence
firebase emulators:start --import=./emulator-data --export-on-exit=./emulator-data

# Start specific emulators only
firebase emulators:start --only firestore,auth,functions

# Run emulators and execute tests, then shut down
firebase emulators:exec "npm test"
```

**Why good:** Emulator connections guarded by `NODE_ENV`, named constants for ports, `--import/--export-on-exit` persists emulator data between sessions, `emulators:exec` for CI pipelines

---

## Offline Persistence

Enable Firestore offline persistence for apps that need to work without connectivity.

```typescript
import {
  initializeFirestore,
  persistentLocalCache,
  persistentMultipleTabManager,
} from "firebase/firestore";
import { initializeApp } from "firebase/app";

const app = initializeApp(firebaseConfig);

// Enable persistent offline cache with multi-tab support
export const db = initializeFirestore(app, {
  localCache: persistentLocalCache({
    tabManager: persistentMultipleTabManager(),
  }),
});
```

**Why good:** `initializeFirestore` with `persistentLocalCache` is the modern approach (replaces deprecated `enableIndexedDbPersistence`), `persistentMultipleTabManager` enables multi-tab sync, configured at initialization time

```typescript
// BAD: Deprecated persistence API
import { getFirestore, enableIndexedDbPersistence } from "firebase/firestore";

const db = getFirestore(app);
enableIndexedDbPersistence(db); // Deprecated -- use initializeFirestore instead
```

**Why bad:** `enableIndexedDbPersistence` is deprecated, must be called before any other Firestore operations, does not support multi-tab by default

---

_For core concepts, see [SKILL.md](../SKILL.md). For quick reference tables, see [reference.md](../reference.md)._

# Firebase Examples

> Practical examples for Firestore CRUD, authentication flows, Cloud Functions v2, and Storage. See [SKILL.md](../SKILL.md) for core concepts and [reference.md](../reference.md) for quick lookups.

---

## Example 1: Complete Firestore CRUD Service

A full-featured service for managing posts with typed documents, error handling, and pagination.

```typescript
// services/post-service.ts
import {
  collection,
  doc,
  getDoc,
  getDocs,
  setDoc,
  updateDoc,
  deleteDoc,
  query,
  where,
  orderBy,
  limit,
  startAfter,
  serverTimestamp,
  type DocumentSnapshot,
  type QueryDocumentSnapshot,
  Timestamp,
} from "firebase/firestore";
import { db } from "../lib/firebase";

// --- Types ---

export interface Post {
  id: string;
  title: string;
  content: string;
  authorId: string;
  published: boolean;
  tags: string[];
  createdAt: Timestamp;
  updatedAt: Timestamp;
}

export type PostCreate = Omit<Post, "id" | "createdAt" | "updatedAt">;
export type PostUpdate = Partial<Omit<Post, "id" | "createdAt" | "updatedAt">>;

export interface PaginatedResult<T> {
  items: T[];
  lastDoc: QueryDocumentSnapshot | null;
  hasMore: boolean;
}

// --- Constants ---

const POSTS_COLLECTION = "posts";
const DEFAULT_PAGE_SIZE = 20;

// --- Helpers ---

function mapDoc(doc: DocumentSnapshot): Post {
  if (!doc.exists()) {
    throw new Error(`Document not found: ${doc.id}`);
  }
  return { id: doc.id, ...doc.data() } as Post;
}

function mapDocs(docs: QueryDocumentSnapshot[]): Post[] {
  return docs.map((doc) => ({ id: doc.id, ...doc.data() }) as Post);
}

// --- CRUD Operations ---

export async function getPost(postId: string): Promise<Post> {
  const docRef = doc(db, POSTS_COLLECTION, postId);
  const snapshot = await getDoc(docRef);
  return mapDoc(snapshot);
}

export async function createPost(data: PostCreate): Promise<string> {
  const docRef = doc(collection(db, POSTS_COLLECTION));
  await setDoc(docRef, {
    ...data,
    createdAt: serverTimestamp(),
    updatedAt: serverTimestamp(),
  });
  return docRef.id;
}

export async function updatePost(
  postId: string,
  data: PostUpdate,
): Promise<void> {
  const docRef = doc(db, POSTS_COLLECTION, postId);
  await updateDoc(docRef, {
    ...data,
    updatedAt: serverTimestamp(),
  });
}

export async function deletePost(postId: string): Promise<void> {
  const docRef = doc(db, POSTS_COLLECTION, postId);
  await deleteDoc(docRef);
}

// --- Queries ---

export async function getPublishedPosts(
  pageSize: number = DEFAULT_PAGE_SIZE,
  lastDoc?: QueryDocumentSnapshot,
): Promise<PaginatedResult<Post>> {
  const postsRef = collection(db, POSTS_COLLECTION);
  const constraints = [
    where("published", "==", true),
    orderBy("createdAt", "desc"),
    limit(pageSize + 1), // Fetch one extra to check if there's more
  ];

  if (lastDoc) {
    constraints.push(startAfter(lastDoc));
  }

  const q = query(postsRef, ...constraints);
  const snapshot = await getDocs(q);

  const hasMore = snapshot.docs.length > pageSize;
  const docs = hasMore ? snapshot.docs.slice(0, pageSize) : snapshot.docs;

  return {
    items: mapDocs(docs),
    lastDoc: docs.length > 0 ? docs[docs.length - 1] : null,
    hasMore,
  };
}

export async function getPostsByAuthor(authorId: string): Promise<Post[]> {
  const postsRef = collection(db, POSTS_COLLECTION);
  const q = query(
    postsRef,
    where("authorId", "==", authorId),
    orderBy("createdAt", "desc"),
  );
  const snapshot = await getDocs(q);
  return mapDocs(snapshot.docs);
}

export async function getPostsByTag(tag: string): Promise<Post[]> {
  const postsRef = collection(db, POSTS_COLLECTION);
  const q = query(
    postsRef,
    where("tags", "array-contains", tag),
    orderBy("createdAt", "desc"),
    limit(DEFAULT_PAGE_SIZE),
  );
  const snapshot = await getDocs(q);
  return mapDocs(snapshot.docs);
}
```

**Key patterns:** Typed document interfaces with `Omit<>` for create/update variants, `serverTimestamp()` for consistent timestamps, cursor-based pagination with `startAfter()`, "fetch N+1" pattern to detect `hasMore`, helper functions for doc mapping

---

## Example 2: Real-Time Chat with Firestore Listeners

A complete chat implementation using `onSnapshot` for real-time updates.

```typescript
// services/chat-service.ts
import {
  collection,
  doc,
  setDoc,
  query,
  where,
  orderBy,
  limit,
  onSnapshot,
  serverTimestamp,
  type Unsubscribe,
  type Timestamp,
} from "firebase/firestore";
import { db, auth } from "../lib/firebase";

// --- Types ---

export interface Message {
  id: string;
  text: string;
  senderId: string;
  senderName: string;
  roomId: string;
  createdAt: Timestamp;
}

export interface ChatRoom {
  id: string;
  name: string;
  memberIds: string[];
  lastMessage?: string;
  lastMessageAt?: Timestamp;
}

// --- Constants ---

const ROOMS_COLLECTION = "rooms";
const MESSAGES_SUBCOLLECTION = "messages";
const RECENT_MESSAGES_LIMIT = 50;

// --- Real-Time Listeners ---

export function subscribeToMessages(
  roomId: string,
  onUpdate: (messages: Message[]) => void,
  onError?: (error: Error) => void,
): Unsubscribe {
  const messagesRef = collection(
    db,
    ROOMS_COLLECTION,
    roomId,
    MESSAGES_SUBCOLLECTION,
  );
  const q = query(
    messagesRef,
    orderBy("createdAt", "asc"),
    limit(RECENT_MESSAGES_LIMIT),
  );

  return onSnapshot(
    q,
    (snapshot) => {
      const messages = snapshot.docs.map(
        (doc) => ({ id: doc.id, ...doc.data() }) as Message,
      );
      onUpdate(messages);
    },
    (error) => {
      if (onError) {
        onError(new Error(`Chat listener failed: ${error.message}`));
      }
    },
  );
}

export function subscribeToUserRooms(
  userId: string,
  onUpdate: (rooms: ChatRoom[]) => void,
): Unsubscribe {
  const roomsRef = collection(db, ROOMS_COLLECTION);
  const q = query(
    roomsRef,
    where("memberIds", "array-contains", userId),
    orderBy("lastMessageAt", "desc"),
  );

  return onSnapshot(q, (snapshot) => {
    const rooms = snapshot.docs.map(
      (doc) => ({ id: doc.id, ...doc.data() }) as ChatRoom,
    );
    onUpdate(rooms);
  });
}

// --- Send Message ---

export async function sendMessage(roomId: string, text: string): Promise<void> {
  const user = auth.currentUser;

  if (!user) {
    throw new Error("Must be signed in to send messages");
  }

  const messagesRef = collection(
    db,
    ROOMS_COLLECTION,
    roomId,
    MESSAGES_SUBCOLLECTION,
  );
  const messageRef = doc(messagesRef);

  // Write message and update room's last message in parallel
  const roomRef = doc(db, ROOMS_COLLECTION, roomId);

  await Promise.all([
    setDoc(messageRef, {
      text,
      senderId: user.uid,
      senderName: user.displayName ?? "Anonymous",
      roomId,
      createdAt: serverTimestamp(),
    }),
    setDoc(
      roomRef,
      {
        lastMessage: text,
        lastMessageAt: serverTimestamp(),
      },
      { merge: true },
    ),
  ]);
}
```

**Key patterns:** Subcollection pattern for messages within rooms, `array-contains` for membership queries, `onSnapshot` with error callback, `Unsubscribe` return type, `merge: true` for partial document updates, auth check before writes

---

## Example 3: Authentication with React Context

A complete auth context pattern using Firebase Authentication with React.

```typescript
// contexts/auth-context.tsx
import {
  createContext,
  useContext,
  useEffect,
  useState,
  type ReactNode,
} from "react";
import {
  onAuthStateChanged,
  signInWithEmailAndPassword,
  createUserWithEmailAndPassword,
  signInWithPopup,
  GoogleAuthProvider,
  signOut,
  type User,
} from "firebase/auth";
import { doc, setDoc, serverTimestamp } from "firebase/firestore";
import { auth, db } from "../lib/firebase";

// --- Types ---

interface AuthContextValue {
  user: User | null;
  loading: boolean;
  signIn: (email: string, password: string) => Promise<void>;
  signUp: (email: string, password: string, displayName: string) => Promise<void>;
  signInWithGoogle: () => Promise<void>;
  logOut: () => Promise<void>;
}

// --- Constants ---

const USERS_COLLECTION = "users";

// --- Context ---

const AuthContext = createContext<AuthContextValue | null>(null);

export function useAuth(): AuthContextValue {
  const context = useContext(AuthContext);

  if (!context) {
    throw new Error("useAuth must be used within an AuthProvider");
  }

  return context;
}

// --- Provider ---

const googleProvider = new GoogleAuthProvider();

export function AuthProvider({ children }: { children: ReactNode }) {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const unsubscribe = onAuthStateChanged(auth, (firebaseUser) => {
      setUser(firebaseUser);
      setLoading(false);
    });

    return unsubscribe;
  }, []);

  async function signIn(email: string, password: string): Promise<void> {
    await signInWithEmailAndPassword(auth, email, password);
  }

  async function signUp(
    email: string,
    password: string,
    displayName: string
  ): Promise<void> {
    const credential = await createUserWithEmailAndPassword(
      auth,
      email,
      password
    );

    // Create user profile document in Firestore
    await setDoc(doc(db, USERS_COLLECTION, credential.user.uid), {
      email,
      displayName,
      createdAt: serverTimestamp(),
    });
  }

  async function signInWithGoogle(): Promise<void> {
    const result = await signInWithPopup(auth, googleProvider);

    // Create/update user profile on first OAuth sign-in
    await setDoc(
      doc(db, USERS_COLLECTION, result.user.uid),
      {
        email: result.user.email,
        displayName: result.user.displayName,
        photoURL: result.user.photoURL,
        lastLoginAt: serverTimestamp(),
      },
      { merge: true }
    );
  }

  async function logOut(): Promise<void> {
    await signOut(auth);
  }

  const value: AuthContextValue = {
    user,
    loading,
    signIn,
    signUp,
    signInWithGoogle,
    logOut,
  };

  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
}

// --- Usage ---
// function ProtectedPage() {
//   const { user, loading, logOut } = useAuth();
//
//   if (loading) return <div>Loading...</div>;
//   if (!user) return <Navigate to="/login" />;
//
//   return (
//     <div>
//       <p>Welcome, {user.displayName}</p>
//       <button onClick={logOut}>Sign Out</button>
//     </div>
//   );
// }
```

**Key patterns:** Auth state in React context, `loading` state for initial auth check, `onAuthStateChanged` cleanup in `useEffect`, user profile creation on sign-up, `merge: true` for OAuth profile updates (don't overwrite existing data), typed context value

---

## Example 4: Cloud Functions v2 — Complete API

A full API example with HTTP endpoints, callable functions, and Firestore triggers.

```typescript
// functions/src/index.ts
import { initializeApp } from "firebase-admin/app";
import { getFirestore, FieldValue } from "firebase-admin/firestore";
import { getAuth } from "firebase-admin/auth";

// Initialize Admin SDK (call once, before any function definitions)
initializeApp();

const db = getFirestore();
const adminAuth = getAuth();

// Re-export functions from separate modules
export { getPosts, getPostById } from "./api/posts";
export { createPost, updatePost } from "./api/post-mutations";
export { onPostCreated, onPostDeleted } from "./triggers/post-triggers";
export { cleanupExpiredSessions } from "./scheduled/cleanup";
```

```typescript
// functions/src/api/posts.ts
import { onRequest } from "firebase-functions/v2/https";
import { getFirestore } from "firebase-admin/firestore";

const db = getFirestore();
const POSTS_COLLECTION = "posts";
const DEFAULT_LIMIT = 20;

export const getPosts = onRequest(
  { cors: true, region: "us-central1", memory: "256MiB" },
  async (req, res) => {
    if (req.method !== "GET") {
      res.status(405).json({ error: "Method not allowed" });
      return;
    }

    try {
      const pageSize = Math.min(
        Number(req.query.limit) || DEFAULT_LIMIT,
        DEFAULT_LIMIT,
      );

      const snapshot = await db
        .collection(POSTS_COLLECTION)
        .where("published", "==", true)
        .orderBy("createdAt", "desc")
        .limit(pageSize)
        .get();

      const posts = snapshot.docs.map((doc) => ({
        id: doc.id,
        ...doc.data(),
      }));

      res.json({ posts, count: posts.length });
    } catch (error) {
      console.error("Failed to fetch posts:", error);
      res.status(500).json({ error: "Internal server error" });
    }
  },
);

export const getPostById = onRequest(
  { cors: true, region: "us-central1" },
  async (req, res) => {
    const postId = req.path.split("/").pop();

    if (!postId) {
      res.status(400).json({ error: "Post ID required" });
      return;
    }

    try {
      const doc = await db.collection(POSTS_COLLECTION).doc(postId).get();

      if (!doc.exists) {
        res.status(404).json({ error: "Post not found" });
        return;
      }

      res.json({ id: doc.id, ...doc.data() });
    } catch (error) {
      console.error("Failed to fetch post:", error);
      res.status(500).json({ error: "Internal server error" });
    }
  },
);
```

```typescript
// functions/src/api/post-mutations.ts
import { onCall, HttpsError } from "firebase-functions/v2/https";
import { getFirestore, FieldValue } from "firebase-admin/firestore";

const db = getFirestore();
const POSTS_COLLECTION = "posts";
const MAX_TITLE_LENGTH = 200;
const MAX_CONTENT_LENGTH = 50000;

export const createPost = onCall({ region: "us-central1" }, async (request) => {
  if (!request.auth) {
    throw new HttpsError("unauthenticated", "Must be signed in");
  }

  const { title, content, tags } = request.data;

  // Input validation
  if (!title || typeof title !== "string" || title.length > MAX_TITLE_LENGTH) {
    throw new HttpsError(
      "invalid-argument",
      `Title is required and must be under ${MAX_TITLE_LENGTH} characters`,
    );
  }

  if (
    !content ||
    typeof content !== "string" ||
    content.length > MAX_CONTENT_LENGTH
  ) {
    throw new HttpsError(
      "invalid-argument",
      `Content is required and must be under ${MAX_CONTENT_LENGTH} characters`,
    );
  }

  const docRef = await db.collection(POSTS_COLLECTION).add({
    title: title.trim(),
    content: content.trim(),
    tags: Array.isArray(tags) ? tags : [],
    authorId: request.auth.uid,
    published: false,
    createdAt: FieldValue.serverTimestamp(),
    updatedAt: FieldValue.serverTimestamp(),
  });

  return { id: docRef.id };
});

export const updatePost = onCall({ region: "us-central1" }, async (request) => {
  if (!request.auth) {
    throw new HttpsError("unauthenticated", "Must be signed in");
  }

  const { postId, ...updates } = request.data;

  if (!postId) {
    throw new HttpsError("invalid-argument", "Post ID is required");
  }

  // Verify ownership
  const postSnap = await db.collection(POSTS_COLLECTION).doc(postId).get();

  if (!postSnap.exists) {
    throw new HttpsError("not-found", "Post not found");
  }

  if (postSnap.data()?.authorId !== request.auth.uid) {
    throw new HttpsError(
      "permission-denied",
      "You can only edit your own posts",
    );
  }

  await db
    .collection(POSTS_COLLECTION)
    .doc(postId)
    .update({
      ...updates,
      updatedAt: FieldValue.serverTimestamp(),
    });

  return { success: true };
});
```

```typescript
// functions/src/triggers/post-triggers.ts
import {
  onDocumentCreated,
  onDocumentDeleted,
} from "firebase-functions/v2/firestore";
import { getFirestore, FieldValue } from "firebase-admin/firestore";

const db = getFirestore();
const USERS_COLLECTION = "users";

export const onPostCreated = onDocumentCreated(
  { document: "posts/{postId}", region: "us-central1" },
  async (event) => {
    const data = event.data?.data();

    if (!data) {
      return;
    }

    // Increment the author's post count
    await db
      .collection(USERS_COLLECTION)
      .doc(data.authorId)
      .update({
        postCount: FieldValue.increment(1),
        lastPostAt: FieldValue.serverTimestamp(),
      });
  },
);

export const onPostDeleted = onDocumentDeleted(
  { document: "posts/{postId}", region: "us-central1" },
  async (event) => {
    const data = event.data?.data();

    if (!data) {
      return;
    }

    // Decrement the author's post count
    await db
      .collection(USERS_COLLECTION)
      .doc(data.authorId)
      .update({
        postCount: FieldValue.increment(-1),
      });
  },
);
```

```typescript
// functions/src/scheduled/cleanup.ts
import { onSchedule } from "firebase-functions/v2/scheduler";
import { getFirestore } from "firebase-admin/firestore";

const db = getFirestore();
const SESSIONS_COLLECTION = "sessions";
const SESSION_EXPIRY_DAYS = 30;
const MAX_BATCH_SIZE = 500;

export const cleanupExpiredSessions = onSchedule(
  {
    schedule: "every day 03:00",
    region: "us-central1",
    timeZone: "America/New_York",
  },
  async () => {
    const cutoff = new Date();
    cutoff.setDate(cutoff.getDate() - SESSION_EXPIRY_DAYS);

    const expired = await db
      .collection(SESSIONS_COLLECTION)
      .where("lastActive", "<", cutoff)
      .limit(MAX_BATCH_SIZE)
      .get();

    if (expired.empty) {
      console.log("No expired sessions to clean up");
      return;
    }

    const batch = db.batch();
    for (const doc of expired.docs) {
      batch.delete(doc.ref);
    }
    await batch.commit();

    console.log(`Deleted ${expired.docs.length} expired sessions`);
  },
);
```

**Key patterns:** Modular v2 imports from subpackages, `HttpsError` for typed error codes in callable functions, auth verification in callable functions, input validation with length limits, Firestore triggers for denormalized counter updates, scheduled functions with timezone, Admin SDK for server-side operations, `FieldValue.increment()` for atomic counters, named constants throughout

---

## Example 5: Storage Upload with Progress and Validation

Complete file upload flow with client-side validation, progress tracking, and security rules.

```typescript
// services/storage-service.ts
import {
  ref,
  uploadBytesResumable,
  getDownloadURL,
  deleteObject,
  listAll,
  type UploadTaskSnapshot,
} from "firebase/storage";
import { storage, auth } from "../lib/firebase";

// --- Constants ---

const MAX_IMAGE_SIZE_BYTES = 5 * 1024 * 1024; // 5 MB
const MAX_DOCUMENT_SIZE_BYTES = 20 * 1024 * 1024; // 20 MB
const ALLOWED_IMAGE_TYPES = ["image/jpeg", "image/png", "image/webp"];
const ALLOWED_DOCUMENT_TYPES = [
  "application/pdf",
  "application/msword",
  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
];

// --- Types ---

export interface UploadResult {
  url: string;
  path: string;
}

export interface UploadProgress {
  bytesTransferred: number;
  totalBytes: number;
  percent: number;
}

// --- Validation ---

function validateImageFile(file: File): void {
  if (!ALLOWED_IMAGE_TYPES.includes(file.type)) {
    throw new Error(
      `Invalid image type: ${file.type}. Allowed: ${ALLOWED_IMAGE_TYPES.join(", ")}`,
    );
  }
  if (file.size > MAX_IMAGE_SIZE_BYTES) {
    throw new Error("Image exceeds 5MB size limit");
  }
}

function validateDocumentFile(file: File): void {
  if (!ALLOWED_DOCUMENT_TYPES.includes(file.type)) {
    throw new Error(`Invalid document type: ${file.type}`);
  }
  if (file.size > MAX_DOCUMENT_SIZE_BYTES) {
    throw new Error("Document exceeds 20MB size limit");
  }
}

// --- Upload Functions ---

export function uploadImage(
  file: File,
  path: string,
  onProgress?: (progress: UploadProgress) => void,
): Promise<UploadResult> {
  validateImageFile(file);
  return uploadFile(file, path, onProgress);
}

export function uploadDocument(
  file: File,
  path: string,
  onProgress?: (progress: UploadProgress) => void,
): Promise<UploadResult> {
  validateDocumentFile(file);
  return uploadFile(file, path, onProgress);
}

function uploadFile(
  file: File,
  path: string,
  onProgress?: (progress: UploadProgress) => void,
): Promise<UploadResult> {
  const user = auth.currentUser;

  if (!user) {
    throw new Error("Must be authenticated to upload files");
  }

  const storageRef = ref(storage, path);
  const uploadTask = uploadBytesResumable(storageRef, file, {
    contentType: file.type,
    customMetadata: { uploadedBy: user.uid },
  });

  return new Promise((resolve, reject) => {
    const PERCENT_MULTIPLIER = 100;

    uploadTask.on(
      "state_changed",
      (snapshot: UploadTaskSnapshot) => {
        if (onProgress) {
          onProgress({
            bytesTransferred: snapshot.bytesTransferred,
            totalBytes: snapshot.totalBytes,
            percent:
              (snapshot.bytesTransferred / snapshot.totalBytes) *
              PERCENT_MULTIPLIER,
          });
        }
      },
      (error) => reject(new Error(`Upload failed: ${error.message}`)),
      async () => {
        const url = await getDownloadURL(uploadTask.snapshot.ref);
        resolve({ url, path });
      },
    );
  });
}

// --- Delete ---

export async function deleteFile(path: string): Promise<void> {
  const storageRef = ref(storage, path);
  await deleteObject(storageRef);
}

// --- List Files ---

export async function listUserFiles(userId: string): Promise<string[]> {
  const listRef = ref(storage, `documents/${userId}`);
  const result = await listAll(listRef);
  return result.items.map((item) => item.fullPath);
}
```

**Key patterns:** Client-side validation before upload (type and size), resumable upload with progress callback, auth check before upload, `customMetadata` for audit trail, typed upload result with URL and path, separate validation functions per file category

---

## Example 6: Calling Cloud Functions from Client

Use `httpsCallable` to call `onCall` Cloud Functions from the client with automatic auth token handling.

```typescript
// services/api-service.ts
import { httpsCallable, type HttpsCallableResult } from "firebase/functions";
import { functions } from "../lib/firebase";
import type { Post, PostCreate, PostUpdate } from "../types/post";

// --- Types ---

interface CreatePostResponse {
  id: string;
}

interface UpdatePostResponse {
  success: boolean;
}

// --- Callable Function Wrappers ---

const createPostFn = httpsCallable<PostCreate, CreatePostResponse>(
  functions,
  "createPost",
);

const updatePostFn = httpsCallable<
  PostUpdate & { postId: string },
  UpdatePostResponse
>(functions, "updatePost");

// --- Service Functions ---

export async function createPost(data: PostCreate): Promise<string> {
  const result: HttpsCallableResult<CreatePostResponse> =
    await createPostFn(data);
  return result.data.id;
}

export async function updatePost(
  postId: string,
  data: PostUpdate,
): Promise<void> {
  await updatePostFn({ postId, ...data });
}
```

**Key patterns:** `httpsCallable` generic types for request and response, named function variables, wrapped in service functions for abstraction, auth token automatically included by the client SDK

---

## Example 7: App Check Setup

Protect your backend resources from abuse by verifying requests come from your app.

```typescript
// lib/firebase.ts — add App Check initialization
import { initializeApp } from "firebase/app";
import {
  initializeAppCheck,
  ReCaptchaEnterpriseProvider,
} from "firebase/app-check";

const app = initializeApp(firebaseConfig);

// Enable App Check with reCAPTCHA Enterprise
const RECAPTCHA_SITE_KEY = process.env.NEXT_PUBLIC_RECAPTCHA_SITE_KEY!;

// Enable debug token in development
if (process.env.NODE_ENV === "development") {
  // @ts-expect-error -- Firebase debug token global
  self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
}

const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider(RECAPTCHA_SITE_KEY),
  isTokenAutoRefreshEnabled: true,
});
```

**Key patterns:** reCAPTCHA Enterprise is the recommended provider (reCAPTCHA v3 is being phased out), debug token in development for emulator support, `isTokenAutoRefreshEnabled` keeps the token fresh, `@ts-expect-error` for the global debug token

---

_For core concepts, see [SKILL.md](../SKILL.md). For quick reference tables, see [reference.md](../reference.md)._

# Firebase -- Firestore Examples

> CRUD operations, queries, real-time listeners, batch writes, transactions, and pagination. See [SKILL.md](../SKILL.md) for core concepts and [reference.md](../reference.md) for quick lookups.

**Related examples:**

- [core.md](core.md) -- Firebase project setup, emulator suite
- [auth.md](auth.md) -- Authentication flows
- [functions.md](functions.md) -- Cloud Functions v2, Admin SDK
- [storage.md](storage.md) -- File upload, download, delete
- [security-rules.md](security-rules.md) -- Firestore and Storage security rules

---

## Complete Firestore CRUD Service

A full-featured service for managing posts with typed documents, error handling, and pagination.

```typescript
// services/post-service.ts
import {
  collection,
  doc,
  getDoc,
  getDocs,
  setDoc,
  updateDoc,
  deleteDoc,
  query,
  where,
  orderBy,
  limit,
  startAfter,
  serverTimestamp,
  type DocumentSnapshot,
  type QueryDocumentSnapshot,
  Timestamp,
} from "firebase/firestore";
import { db } from "../lib/firebase";

// --- Types ---

export interface Post {
  id: string;
  title: string;
  content: string;
  authorId: string;
  published: boolean;
  tags: string[];
  createdAt: Timestamp;
  updatedAt: Timestamp;
}

export type PostCreate = Omit<Post, "id" | "createdAt" | "updatedAt">;
export type PostUpdate = Partial<Omit<Post, "id" | "createdAt" | "updatedAt">>;

export interface PaginatedResult<T> {
  items: T[];
  lastDoc: QueryDocumentSnapshot | null;
  hasMore: boolean;
}

// --- Constants ---

const POSTS_COLLECTION = "posts";
const DEFAULT_PAGE_SIZE = 20;

// --- Helpers ---

function mapDoc(doc: DocumentSnapshot): Post {
  if (!doc.exists()) {
    throw new Error(`Document not found: ${doc.id}`);
  }
  return { id: doc.id, ...doc.data() } as Post;
}

function mapDocs(docs: QueryDocumentSnapshot[]): Post[] {
  return docs.map((doc) => ({ id: doc.id, ...doc.data() }) as Post);
}

// --- CRUD Operations ---

export async function getPost(postId: string): Promise<Post> {
  const docRef = doc(db, POSTS_COLLECTION, postId);
  const snapshot = await getDoc(docRef);
  return mapDoc(snapshot);
}

export async function createPost(data: PostCreate): Promise<string> {
  const docRef = doc(collection(db, POSTS_COLLECTION));
  await setDoc(docRef, {
    ...data,
    createdAt: serverTimestamp(),
    updatedAt: serverTimestamp(),
  });
  return docRef.id;
}

export async function updatePost(
  postId: string,
  data: PostUpdate,
): Promise<void> {
  const docRef = doc(db, POSTS_COLLECTION, postId);
  await updateDoc(docRef, {
    ...data,
    updatedAt: serverTimestamp(),
  });
}

export async function deletePost(postId: string): Promise<void> {
  const docRef = doc(db, POSTS_COLLECTION, postId);
  await deleteDoc(docRef);
}

// --- Queries ---

export async function getPublishedPosts(
  pageSize: number = DEFAULT_PAGE_SIZE,
  lastDoc?: QueryDocumentSnapshot,
): Promise<PaginatedResult<Post>> {
  const postsRef = collection(db, POSTS_COLLECTION);
  const constraints = [
    where("published", "==", true),
    orderBy("createdAt", "desc"),
    limit(pageSize + 1), // Fetch one extra to check if there's more
  ];

  if (lastDoc) {
    constraints.push(startAfter(lastDoc));
  }

  const q = query(postsRef, ...constraints);
  const snapshot = await getDocs(q);

  const hasMore = snapshot.docs.length > pageSize;
  const docs = hasMore ? snapshot.docs.slice(0, pageSize) : snapshot.docs;

  return {
    items: mapDocs(docs),
    lastDoc: docs.length > 0 ? docs[docs.length - 1] : null,
    hasMore,
  };
}

export async function getPostsByAuthor(authorId: string): Promise<Post[]> {
  const postsRef = collection(db, POSTS_COLLECTION);
  const q = query(
    postsRef,
    where("authorId", "==", authorId),
    orderBy("createdAt", "desc"),
  );
  const snapshot = await getDocs(q);
  return mapDocs(snapshot.docs);
}

export async function getPostsByTag(tag: string): Promise<Post[]> {
  const postsRef = collection(db, POSTS_COLLECTION);
  const q = query(
    postsRef,
    where("tags", "array-contains", tag),
    orderBy("createdAt", "desc"),
    limit(DEFAULT_PAGE_SIZE),
  );
  const snapshot = await getDocs(q);
  return mapDocs(snapshot.docs);
}
```

**Key patterns:** Typed document interfaces with `Omit<>` for create/update variants, `serverTimestamp()` for consistent timestamps, cursor-based pagination with `startAfter()`, "fetch N+1" pattern to detect `hasMore`, helper functions for doc mapping

---

## Real-Time Chat with Firestore Listeners

A complete chat implementation using `onSnapshot` for real-time updates.

```typescript
// services/chat-service.ts
import {
  collection,
  doc,
  setDoc,
  query,
  where,
  orderBy,
  limit,
  onSnapshot,
  serverTimestamp,
  type Unsubscribe,
  type Timestamp,
} from "firebase/firestore";
import { db, auth } from "../lib/firebase";

// --- Types ---

export interface Message {
  id: string;
  text: string;
  senderId: string;
  senderName: string;
  roomId: string;
  createdAt: Timestamp;
}

export interface ChatRoom {
  id: string;
  name: string;
  memberIds: string[];
  lastMessage?: string;
  lastMessageAt?: Timestamp;
}

// --- Constants ---

const ROOMS_COLLECTION = "rooms";
const MESSAGES_SUBCOLLECTION = "messages";
const RECENT_MESSAGES_LIMIT = 50;

// --- Real-Time Listeners ---

export function subscribeToMessages(
  roomId: string,
  onUpdate: (messages: Message[]) => void,
  onError?: (error: Error) => void,
): Unsubscribe {
  const messagesRef = collection(
    db,
    ROOMS_COLLECTION,
    roomId,
    MESSAGES_SUBCOLLECTION,
  );
  const q = query(
    messagesRef,
    orderBy("createdAt", "asc"),
    limit(RECENT_MESSAGES_LIMIT),
  );

  return onSnapshot(
    q,
    (snapshot) => {
      const messages = snapshot.docs.map(
        (doc) => ({ id: doc.id, ...doc.data() }) as Message,
      );
      onUpdate(messages);
    },
    (error) => {
      if (onError) {
        onError(new Error(`Chat listener failed: ${error.message}`));
      }
    },
  );
}

export function subscribeToUserRooms(
  userId: string,
  onUpdate: (rooms: ChatRoom[]) => void,
): Unsubscribe {
  const roomsRef = collection(db, ROOMS_COLLECTION);
  const q = query(
    roomsRef,
    where("memberIds", "array-contains", userId),
    orderBy("lastMessageAt", "desc"),
  );

  return onSnapshot(q, (snapshot) => {
    const rooms = snapshot.docs.map(
      (doc) => ({ id: doc.id, ...doc.data() }) as ChatRoom,
    );
    onUpdate(rooms);
  });
}

// --- Send Message ---

export async function sendMessage(roomId: string, text: string): Promise<void> {
  const user = auth.currentUser;

  if (!user) {
    throw new Error("Must be signed in to send messages");
  }

  const messagesRef = collection(
    db,
    ROOMS_COLLECTION,
    roomId,
    MESSAGES_SUBCOLLECTION,
  );
  const messageRef = doc(messagesRef);

  // Write message and update room's last message in parallel
  const roomRef = doc(db, ROOMS_COLLECTION, roomId);

  await Promise.all([
    setDoc(messageRef, {
      text,
      senderId: user.uid,
      senderName: user.displayName ?? "Anonymous",
      roomId,
      createdAt: serverTimestamp(),
    }),
    setDoc(
      roomRef,
      {
        lastMessage: text,
        lastMessageAt: serverTimestamp(),
      },
      { merge: true },
    ),
  ]);
}
```

**Key patterns:** Subcollection pattern for messages within rooms, `array-contains` for membership queries, `onSnapshot` with error callback, `Unsubscribe` return type, `merge: true` for partial document updates, auth check before writes

---

## Transactions and Batched Writes

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

```typescript
import {
  runTransaction,
  writeBatch,
  doc,
  increment,
  serverTimestamp,
} from "firebase/firestore";
import { db } from "../lib/firebase";

const POSTS_COLLECTION = "posts";
const USERS_COLLECTION = "users";

// Transaction: atomic read-then-write (e.g., increment a counter)
async function likePost(postId: string, userId: string): Promise<void> {
  const postRef = doc(db, POSTS_COLLECTION, postId);
  const likeRef = doc(db, POSTS_COLLECTION, postId, "likes", userId);

  await runTransaction(db, async (transaction) => {
    const postSnap = await transaction.get(postRef);

    if (!postSnap.exists()) {
      throw new Error(`Post not found: ${postId}`);
    }

    transaction.update(postRef, { likeCount: increment(1) });
    transaction.set(likeRef, { createdAt: serverTimestamp() });
  });
}

// Batched write: multiple writes without reads (up to 500 operations)
const MAX_BATCH_SIZE = 500;

async function deleteUserPosts(postIds: string[]): Promise<void> {
  const batch = writeBatch(db);

  for (const postId of postIds.slice(0, MAX_BATCH_SIZE)) {
    const docRef = doc(db, POSTS_COLLECTION, postId);
    batch.delete(docRef);
  }

  await batch.commit();
}
```

**Key patterns:** Transaction ensures atomic increment (no race conditions), `increment()` for safe counter updates, batch write for bulk operations, `MAX_BATCH_SIZE` constant documents the 500 limit

---

_For core concepts, see [SKILL.md](../SKILL.md). For quick reference tables, see [reference.md](../reference.md)._

# Firebase -- Cloud Functions v2 & Admin SDK Examples

> HTTP endpoints, callable functions, Firestore triggers, scheduled functions, and Admin SDK patterns. See [SKILL.md](../SKILL.md) for core concepts and [reference.md](../reference.md) for quick lookups.

**Related examples:**

- [core.md](core.md) -- Firebase project setup, emulator suite
- [firestore.md](firestore.md) -- Firestore CRUD, queries, real-time listeners
- [auth.md](auth.md) -- Authentication flows
- [storage.md](storage.md) -- File upload, download, delete
- [security-rules.md](security-rules.md) -- Firestore and Storage security rules

---

## Complete Cloud Functions v2 API

A full API example with HTTP endpoints, callable functions, Firestore triggers, and scheduled tasks.

### Entry Point

```typescript
// functions/src/index.ts
import { initializeApp } from "firebase-admin/app";
import { getFirestore, FieldValue } from "firebase-admin/firestore";
import { getAuth } from "firebase-admin/auth";

// Initialize Admin SDK (call once, before any function definitions)
initializeApp();

const db = getFirestore();
const adminAuth = getAuth();

// Re-export functions from separate modules
export { getPosts, getPostById } from "./api/posts";
export { createPost, updatePost } from "./api/post-mutations";
export { onPostCreated, onPostDeleted } from "./triggers/post-triggers";
export { cleanupExpiredSessions } from "./scheduled/cleanup";
```

### HTTP Function (onRequest)

```typescript
// functions/src/api/posts.ts
import { onRequest } from "firebase-functions/v2/https";
import { getFirestore } from "firebase-admin/firestore";

const db = getFirestore();
const POSTS_COLLECTION = "posts";
const DEFAULT_LIMIT = 20;

export const getPosts = onRequest(
  { cors: true, region: "us-central1", memory: "256MiB" },
  async (req, res) => {
    if (req.method !== "GET") {
      res.status(405).json({ error: "Method not allowed" });
      return;
    }

    try {
      const pageSize = Math.min(
        Number(req.query.limit) || DEFAULT_LIMIT,
        DEFAULT_LIMIT,
      );

      const snapshot = await db
        .collection(POSTS_COLLECTION)
        .where("published", "==", true)
        .orderBy("createdAt", "desc")
        .limit(pageSize)
        .get();

      const posts = snapshot.docs.map((doc) => ({
        id: doc.id,
        ...doc.data(),
      }));

      res.json({ posts, count: posts.length });
    } catch (error) {
      console.error("Failed to fetch posts:", error);
      res.status(500).json({ error: "Internal server error" });
    }
  },
);

export const getPostById = onRequest(
  { cors: true, region: "us-central1" },
  async (req, res) => {
    const postId = req.path.split("/").pop();

    if (!postId) {
      res.status(400).json({ error: "Post ID required" });
      return;
    }

    try {
      const doc = await db.collection(POSTS_COLLECTION).doc(postId).get();

      if (!doc.exists) {
        res.status(404).json({ error: "Post not found" });
        return;
      }

      res.json({ id: doc.id, ...doc.data() });
    } catch (error) {
      console.error("Failed to fetch post:", error);
      res.status(500).json({ error: "Internal server error" });
    }
  },
);
```

### Callable Function (onCall)

```typescript
// functions/src/api/post-mutations.ts
import { onCall, HttpsError } from "firebase-functions/v2/https";
import { getFirestore, FieldValue } from "firebase-admin/firestore";

const db = getFirestore();
const POSTS_COLLECTION = "posts";
const MAX_TITLE_LENGTH = 200;
const MAX_CONTENT_LENGTH = 50000;

export const createPost = onCall({ region: "us-central1" }, async (request) => {
  if (!request.auth) {
    throw new HttpsError("unauthenticated", "Must be signed in");
  }

  const { title, content, tags } = request.data;

  // Input validation
  if (!title || typeof title !== "string" || title.length > MAX_TITLE_LENGTH) {
    throw new HttpsError(
      "invalid-argument",
      `Title is required and must be under ${MAX_TITLE_LENGTH} characters`,
    );
  }

  if (
    !content ||
    typeof content !== "string" ||
    content.length > MAX_CONTENT_LENGTH
  ) {
    throw new HttpsError(
      "invalid-argument",
      `Content is required and must be under ${MAX_CONTENT_LENGTH} characters`,
    );
  }

  const docRef = await db.collection(POSTS_COLLECTION).add({
    title: title.trim(),
    content: content.trim(),
    tags: Array.isArray(tags) ? tags : [],
    authorId: request.auth.uid,
    published: false,
    createdAt: FieldValue.serverTimestamp(),
    updatedAt: FieldValue.serverTimestamp(),
  });

  return { id: docRef.id };
});

export const updatePost = onCall({ region: "us-central1" }, async (request) => {
  if (!request.auth) {
    throw new HttpsError("unauthenticated", "Must be signed in");
  }

  const { postId, ...updates } = request.data;

  if (!postId) {
    throw new HttpsError("invalid-argument", "Post ID is required");
  }

  // Verify ownership
  const postSnap = await db.collection(POSTS_COLLECTION).doc(postId).get();

  if (!postSnap.exists) {
    throw new HttpsError("not-found", "Post not found");
  }

  if (postSnap.data()?.authorId !== request.auth.uid) {
    throw new HttpsError(
      "permission-denied",
      "You can only edit your own posts",
    );
  }

  await db
    .collection(POSTS_COLLECTION)
    .doc(postId)
    .update({
      ...updates,
      updatedAt: FieldValue.serverTimestamp(),
    });

  return { success: true };
});
```

### Firestore Trigger

```typescript
// functions/src/triggers/post-triggers.ts
import {
  onDocumentCreated,
  onDocumentDeleted,
} from "firebase-functions/v2/firestore";
import { getFirestore, FieldValue } from "firebase-admin/firestore";

const db = getFirestore();
const USERS_COLLECTION = "users";

export const onPostCreated = onDocumentCreated(
  { document: "posts/{postId}", region: "us-central1" },
  async (event) => {
    const data = event.data?.data();

    if (!data) {
      return;
    }

    // Increment the author's post count
    await db
      .collection(USERS_COLLECTION)
      .doc(data.authorId)
      .update({
        postCount: FieldValue.increment(1),
        lastPostAt: FieldValue.serverTimestamp(),
      });
  },
);

export const onPostDeleted = onDocumentDeleted(
  { document: "posts/{postId}", region: "us-central1" },
  async (event) => {
    const data = event.data?.data();

    if (!data) {
      return;
    }

    // Decrement the author's post count
    await db
      .collection(USERS_COLLECTION)
      .doc(data.authorId)
      .update({
        postCount: FieldValue.increment(-1),
      });
  },
);
```

### Scheduled Function

```typescript
// functions/src/scheduled/cleanup.ts
import { onSchedule } from "firebase-functions/v2/scheduler";
import { getFirestore } from "firebase-admin/firestore";

const db = getFirestore();
const SESSIONS_COLLECTION = "sessions";
const SESSION_EXPIRY_DAYS = 30;
const MAX_BATCH_SIZE = 500;

export const cleanupExpiredSessions = onSchedule(
  {
    schedule: "every day 03:00",
    region: "us-central1",
    timeZone: "America/New_York",
  },
  async () => {
    const cutoff = new Date();
    cutoff.setDate(cutoff.getDate() - SESSION_EXPIRY_DAYS);

    const expired = await db
      .collection(SESSIONS_COLLECTION)
      .where("lastActive", "<", cutoff)
      .limit(MAX_BATCH_SIZE)
      .get();

    if (expired.empty) {
      console.log("No expired sessions to clean up");
      return;
    }

    const batch = db.batch();
    for (const doc of expired.docs) {
      batch.delete(doc.ref);
    }
    await batch.commit();

    console.log(`Deleted ${expired.docs.length} expired sessions`);
  },
);
```

**Key patterns:** Modular v2 imports from subpackages, `HttpsError` for typed error codes in callable functions, auth verification in callable functions, input validation with length limits, Firestore triggers for denormalized counter updates, scheduled functions with timezone, Admin SDK for server-side operations, `FieldValue.increment()` for atomic counters, named constants throughout

---

## Calling Cloud Functions from Client

Use `httpsCallable` to call `onCall` Cloud Functions from the client with automatic auth token handling.

```typescript
// services/api-service.ts
import { httpsCallable, type HttpsCallableResult } from "firebase/functions";
import { functions } from "../lib/firebase";
import type { Post, PostCreate, PostUpdate } from "../types/post";

// --- Types ---

interface CreatePostResponse {
  id: string;
}

interface UpdatePostResponse {
  success: boolean;
}

// --- Callable Function Wrappers ---

const createPostFn = httpsCallable<PostCreate, CreatePostResponse>(
  functions,
  "createPost",
);

const updatePostFn = httpsCallable<
  PostUpdate & { postId: string },
  UpdatePostResponse
>(functions, "updatePost");

// --- Service Functions ---

export async function createPost(data: PostCreate): Promise<string> {
  const result: HttpsCallableResult<CreatePostResponse> =
    await createPostFn(data);
  return result.data.id;
}

export async function updatePost(
  postId: string,
  data: PostUpdate,
): Promise<void> {
  await updatePostFn({ postId, ...data });
}
```

**Key patterns:** `httpsCallable` generic types for request and response, named function variables, wrapped in service functions for abstraction, auth token automatically included by the client SDK

---

## Admin SDK (Server-Side)

Use the Admin SDK in Cloud Functions, API routes, or any trusted server environment. The Admin SDK bypasses all security rules.

```typescript
// functions/src/admin.ts
import { initializeApp, cert } from "firebase-admin/app";
import { getFirestore } from "firebase-admin/firestore";
import { getAuth } from "firebase-admin/auth";
import { getStorage } from "firebase-admin/storage";

// In Cloud Functions, initializeApp() uses default credentials automatically
initializeApp();

// In standalone servers, use a service account
// initializeApp({
//   credential: cert(JSON.parse(process.env.FIREBASE_SERVICE_ACCOUNT!)),
// });

export const adminDb = getFirestore();
export const adminAuth = getAuth();
export const adminStorage = getStorage();

// Create a custom token for a user
async function createCustomToken(
  uid: string,
  claims?: object,
): Promise<string> {
  return adminAuth.createCustomToken(uid, claims);
}

// Verify an ID token from a client
async function verifyIdToken(idToken: string) {
  return adminAuth.verifyIdToken(idToken);
}

// Admin Firestore operations bypass security rules
async function adminGetUser(userId: string) {
  const userRecord = await adminAuth.getUser(userId);
  return userRecord;
}

// Set custom claims on a user (e.g., admin role)
async function setAdminRole(uid: string): Promise<void> {
  await adminAuth.setCustomUserClaims(uid, { admin: true });
}
```

**Key patterns:** Modular Admin SDK imports (`firebase-admin/app`, `firebase-admin/firestore`), default credentials in Cloud Functions, explicit `cert()` for standalone servers, custom tokens for third-party auth integration, custom claims for role-based access

---

_For core concepts, see [SKILL.md](../SKILL.md). For quick reference tables, see [reference.md](../reference.md)._

# Firebase -- Security Rules Examples

> Firestore and Storage security rules: auth-based access, data validation, helper functions, and common patterns. See [SKILL.md](../SKILL.md) for core concepts and [reference.md](../reference.md) for quick lookups.

**Related examples:**

- [core.md](core.md) -- Firebase project setup, emulator suite
- [firestore.md](firestore.md) -- Firestore CRUD, queries, real-time listeners
- [auth.md](auth.md) -- Authentication flows
- [functions.md](functions.md) -- Cloud Functions v2, Admin SDK
- [storage.md](storage.md) -- File upload, download, delete

---

## Firestore Security Rules

```
// firestore.rules
rules_version = '2';

service cloud.firestore {
  match /databases/{database}/documents {

    // Helper function: check if user is authenticated
    function isAuthenticated() {
      return request.auth != null;
    }

    // Helper function: check if user owns the resource
    function isOwner(userId) {
      return request.auth.uid == userId;
    }

    // Helper function: check if user has admin custom claim
    function isAdmin() {
      return request.auth.token.admin == true;
    }

    // Posts collection
    match /posts/{postId} {
      // Anyone can read published posts; authors can read their own drafts
      allow read: if resource.data.published == true
                  || isOwner(resource.data.authorId);

      // Only authenticated users can create posts as themselves
      allow create: if isAuthenticated()
                    && request.resource.data.authorId == request.auth.uid
                    && request.resource.data.title is string
                    && request.resource.data.title.size() > 0
                    && request.resource.data.title.size() <= 200;

      // Authors can update their own posts
      allow update: if isOwner(resource.data.authorId)
                    && request.resource.data.authorId == resource.data.authorId;

      // Authors and admins can delete posts
      allow delete: if isOwner(resource.data.authorId) || isAdmin();

      // Subcollection: likes
      match /likes/{likeId} {
        allow read: if true;
        allow create: if isAuthenticated() && likeId == request.auth.uid;
        allow delete: if isAuthenticated() && likeId == request.auth.uid;
      }
    }

    // User profiles
    match /users/{userId} {
      allow read: if true;
      allow create: if isOwner(userId);
      allow update: if isOwner(userId);
      allow delete: if false; // Users cannot delete their own profile document
    }
  }
}
```

**Why good:** `rules_version = '2'` required for collection group queries, helper functions reduce duplication, granular read/write split into create/update/delete, data validation on create, ownership check prevents authorId spoofing on update, subcollection rules nested properly

---

## Storage Security Rules

```
// storage.rules
rules_version = '2';

service firebase.storage {
  match /b/{bucket}/o {

    // Avatars: users can upload/read their own avatar
    match /avatars/{userId}/{fileName} {
      allow read: if true;
      allow write: if request.auth != null
                   && request.auth.uid == userId
                   && request.resource.size < 5 * 1024 * 1024
                   && request.resource.contentType.matches('image/.*');
    }

    // Documents: authenticated users can upload, only owner can read
    match /documents/{userId}/{fileName} {
      allow read: if request.auth != null && request.auth.uid == userId;
      allow write: if request.auth != null
                   && request.auth.uid == userId
                   && request.resource.size < 10 * 1024 * 1024;
    }

    // Deny everything else by default
    match /{allPaths=**} {
      allow read, write: if false;
    }
  }
}
```

**Why good:** File size limits enforced in rules, content type validation for images, owner-based access control, default deny for unmatched paths

---

## Bad Example: Wide-Open Rules

```
// BAD: Wide-open security rules
rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read, write: if true; // DANGER: Anyone can read/write everything
    }
  }
}
```

**Why bad:** No authentication check, no access control, no data validation, entire database is public read/write -- this is the default test-mode rule and must NEVER be deployed to production

---

_For core concepts, see [SKILL.md](../SKILL.md). For quick reference tables, see [reference.md](../reference.md)._

# Firebase -- Core Examples

> Project initialization, modular SDK setup, emulator connections, and environment configuration. See [SKILL.md](../SKILL.md) for core concepts and [reference.md](../reference.md) for quick lookups.

**Related examples:**

- [firestore.md](firestore.md) -- Firestore CRUD, queries, real-time listeners
- [auth.md](auth.md) -- Authentication flows
- [functions.md](functions.md) -- Cloud Functions v2, Admin SDK
- [storage.md](storage.md) -- File upload, download, delete
- [security-rules.md](security-rules.md) -- Firestore and Storage security rules

---

## 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";
import { getFunctions } from "firebase/functions";

const firebaseConfig = {
  apiKey: process.env.FIREBASE_API_KEY!,
  authDomain: process.env.FIREBASE_AUTH_DOMAIN!,
  projectId: process.env.FIREBASE_PROJECT_ID!,
  storageBucket: process.env.FIREBASE_STORAGE_BUCKET!,
  messagingSenderId: process.env.FIREBASE_MESSAGING_SENDER_ID!,
  appId: process.env.FIREBASE_APP_ID!,
};

// Initialize Firebase -- call once at app startup
const app = initializeApp(firebaseConfig);

// Export service instances
export const db = getFirestore(app);
export const auth = getAuth(app);
export const storage = getStorage(app);
export const functions = getFunctions(app);
```

**Why good:** Modular imports enable tree-shaking, environment variables keep config out of code, each service initialized from the app instance, named exports for all services

```typescript
// BAD: Legacy compat namespace API
import firebase from "firebase/compat/app";
import "firebase/compat/firestore";
import "firebase/compat/auth";

firebase.initializeApp({
  apiKey: "AIza...", // Hardcoded
  projectId: "my-project",
});

const db = firebase.firestore();
const auth = firebase.auth();
export default { db, auth };
```

**Why bad:** Compat imports prevent tree-shaking (entire SDK bundled), hardcoded credentials leak in source control, side-effect imports, default export

---

## Emulator Suite for Local Development

Use the Firebase Emulator Suite for local development and testing without touching production data.

### Connect to Emulators

```typescript
// lib/firebase.ts -- add emulator connections in development
import { initializeApp } from "firebase/app";
import { getFirestore, connectFirestoreEmulator } from "firebase/firestore";
import { getAuth, connectAuthEmulator } from "firebase/auth";
import { getStorage, connectStorageEmulator } from "firebase/storage";
import { getFunctions, connectFunctionsEmulator } from "firebase/functions";

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

const FIRESTORE_EMULATOR_PORT = 8080;
const AUTH_EMULATOR_PORT = 9099;
const STORAGE_EMULATOR_PORT = 9199;
const FUNCTIONS_EMULATOR_PORT = 5001;

if (process.env.NODE_ENV === "development") {
  connectFirestoreEmulator(db, "localhost", FIRESTORE_EMULATOR_PORT);
  connectAuthEmulator(auth, `http://localhost:${AUTH_EMULATOR_PORT}`);
  connectStorageEmulator(storage, "localhost", STORAGE_EMULATOR_PORT);
  connectFunctionsEmulator(functions, "localhost", FUNCTIONS_EMULATOR_PORT);
}
```

### Start Emulators

```bash
# Install Firebase CLI
npm install -g firebase-tools

# Initialize project (creates firebase.json)
firebase init

# Start all emulators with data persistence
firebase emulators:start --import=./emulator-data --export-on-exit=./emulator-data

# Start specific emulators only
firebase emulators:start --only firestore,auth,functions

# Run emulators and execute tests, then shut down
firebase emulators:exec "npm test"
```

**Why good:** Emulator connections guarded by `NODE_ENV`, named constants for ports, `--import/--export-on-exit` persists emulator data between sessions, `emulators:exec` for CI pipelines

---

## Offline Persistence

Enable Firestore offline persistence for apps that need to work without connectivity.

```typescript
import {
  initializeFirestore,
  persistentLocalCache,
  persistentMultipleTabManager,
} from "firebase/firestore";
import { initializeApp } from "firebase/app";

const app = initializeApp(firebaseConfig);

// Enable persistent offline cache with multi-tab support
export const db = initializeFirestore(app, {
  localCache: persistentLocalCache({
    tabManager: persistentMultipleTabManager(),
  }),
});
```

**Why good:** `initializeFirestore` with `persistentLocalCache` is the modern approach (replaces deprecated `enableIndexedDbPersistence`), `persistentMultipleTabManager` enables multi-tab sync, configured at initialization time

```typescript
// BAD: Deprecated persistence API
import { getFirestore, enableIndexedDbPersistence } from "firebase/firestore";

const db = getFirestore(app);
enableIndexedDbPersistence(db); // Deprecated -- use initializeFirestore instead
```

**Why bad:** `enableIndexedDbPersistence` is deprecated, must be called before any other Firestore operations, does not support multi-tab by default

---

_For core concepts, see [SKILL.md](../SKILL.md). For quick reference tables, see [reference.md](../reference.md)._

# Firebase -- Cloud Storage Examples

> File upload with progress tracking, download URLs, deletion, client-side validation, and App Check. See [SKILL.md](../SKILL.md) for core concepts and [reference.md](../reference.md) for quick lookups.

**Related examples:**

- [core.md](core.md) -- Firebase project setup, emulator suite
- [firestore.md](firestore.md) -- Firestore CRUD, queries, real-time listeners
- [auth.md](auth.md) -- Authentication flows
- [functions.md](functions.md) -- Cloud Functions v2, Admin SDK
- [security-rules.md](security-rules.md) -- Firestore and Storage security rules

---

## Storage Upload with Progress and Validation

Complete file upload flow with client-side validation, progress tracking, and typed results.

```typescript
// services/storage-service.ts
import {
  ref,
  uploadBytesResumable,
  getDownloadURL,
  deleteObject,
  listAll,
  type UploadTaskSnapshot,
} from "firebase/storage";
import { storage, auth } from "../lib/firebase";

// --- Constants ---

const MAX_IMAGE_SIZE_BYTES = 5 * 1024 * 1024; // 5 MB
const MAX_DOCUMENT_SIZE_BYTES = 20 * 1024 * 1024; // 20 MB
const ALLOWED_IMAGE_TYPES = ["image/jpeg", "image/png", "image/webp"];
const ALLOWED_DOCUMENT_TYPES = [
  "application/pdf",
  "application/msword",
  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
];

// --- Types ---

export interface UploadResult {
  url: string;
  path: string;
}

export interface UploadProgress {
  bytesTransferred: number;
  totalBytes: number;
  percent: number;
}

// --- Validation ---

function validateImageFile(file: File): void {
  if (!ALLOWED_IMAGE_TYPES.includes(file.type)) {
    throw new Error(
      `Invalid image type: ${file.type}. Allowed: ${ALLOWED_IMAGE_TYPES.join(", ")}`,
    );
  }
  if (file.size > MAX_IMAGE_SIZE_BYTES) {
    throw new Error("Image exceeds 5MB size limit");
  }
}

function validateDocumentFile(file: File): void {
  if (!ALLOWED_DOCUMENT_TYPES.includes(file.type)) {
    throw new Error(`Invalid document type: ${file.type}`);
  }
  if (file.size > MAX_DOCUMENT_SIZE_BYTES) {
    throw new Error("Document exceeds 20MB size limit");
  }
}

// --- Upload Functions ---

export function uploadImage(
  file: File,
  path: string,
  onProgress?: (progress: UploadProgress) => void,
): Promise<UploadResult> {
  validateImageFile(file);
  return uploadFile(file, path, onProgress);
}

export function uploadDocument(
  file: File,
  path: string,
  onProgress?: (progress: UploadProgress) => void,
): Promise<UploadResult> {
  validateDocumentFile(file);
  return uploadFile(file, path, onProgress);
}

function uploadFile(
  file: File,
  path: string,
  onProgress?: (progress: UploadProgress) => void,
): Promise<UploadResult> {
  const user = auth.currentUser;

  if (!user) {
    throw new Error("Must be authenticated to upload files");
  }

  const storageRef = ref(storage, path);
  const uploadTask = uploadBytesResumable(storageRef, file, {
    contentType: file.type,
    customMetadata: { uploadedBy: user.uid },
  });

  return new Promise((resolve, reject) => {
    const PERCENT_MULTIPLIER = 100;

    uploadTask.on(
      "state_changed",
      (snapshot: UploadTaskSnapshot) => {
        if (onProgress) {
          onProgress({
            bytesTransferred: snapshot.bytesTransferred,
            totalBytes: snapshot.totalBytes,
            percent:
              (snapshot.bytesTransferred / snapshot.totalBytes) *
              PERCENT_MULTIPLIER,
          });
        }
      },
      (error) => reject(new Error(`Upload failed: ${error.message}`)),
      async () => {
        const url = await getDownloadURL(uploadTask.snapshot.ref);
        resolve({ url, path });
      },
    );
  });
}

// --- Delete ---

export async function deleteFile(path: string): Promise<void> {
  const storageRef = ref(storage, path);
  await deleteObject(storageRef);
}

// --- List Files ---

export async function listUserFiles(userId: string): Promise<string[]> {
  const listRef = ref(storage, `documents/${userId}`);
  const result = await listAll(listRef);
  return result.items.map((item) => item.fullPath);
}
```

**Key patterns:** Client-side validation before upload (type and size), resumable upload with progress callback, auth check before upload, `customMetadata` for audit trail, typed upload result with URL and path, separate validation functions per file category

---

## Simple Upload (without progress)

For cases where progress tracking is not needed.

```typescript
import {
  ref,
  uploadBytes,
  getDownloadURL,
  deleteObject,
  type UploadTaskSnapshot,
} from "firebase/storage";
import { storage } from "../lib/firebase";

const AVATARS_PATH = "avatars";
const MAX_FILE_SIZE_BYTES = 5 * 1024 * 1024; // 5 MB

// Simple upload
async function uploadAvatar(userId: string, file: File): Promise<string> {
  if (file.size > MAX_FILE_SIZE_BYTES) {
    throw new Error("File exceeds 5MB limit");
  }

  const storageRef = ref(storage, `${AVATARS_PATH}/${userId}/avatar.png`);
  await uploadBytes(storageRef, file, {
    contentType: file.type,
    customMetadata: { uploadedBy: userId },
  });

  return getDownloadURL(storageRef);
}

// Delete a file
async function deleteAvatar(userId: string): Promise<void> {
  const storageRef = ref(storage, `${AVATARS_PATH}/${userId}/avatar.png`);
  await deleteObject(storageRef);
}
```

**Key patterns:** `uploadBytes` for simple non-resumable uploads, `getDownloadURL` for publicly accessible URLs, named constants for paths and limits

---

## App Check Setup

Protect your backend resources from abuse by verifying requests come from your app.

```typescript
// lib/firebase.ts -- add App Check initialization
import { initializeApp } from "firebase/app";
import {
  initializeAppCheck,
  ReCaptchaEnterpriseProvider,
} from "firebase/app-check";

const app = initializeApp(firebaseConfig);

// Enable App Check with reCAPTCHA Enterprise
const RECAPTCHA_SITE_KEY = process.env.RECAPTCHA_SITE_KEY!;

// Enable debug token in development
if (process.env.NODE_ENV === "development") {
  // @ts-expect-error -- Firebase debug token global
  self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
}

const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider(RECAPTCHA_SITE_KEY),
  isTokenAutoRefreshEnabled: true,
});
```

**Key patterns:** reCAPTCHA Enterprise is the recommended provider (reCAPTCHA v3 is being phased out), debug token in development for emulator support, `isTokenAutoRefreshEnabled` keeps the token fresh, `@ts-expect-error` for the global debug token

---

_For core concepts, see [SKILL.md](../SKILL.md). For quick reference tables, see [reference.md](../reference.md)._