/api-baas-firebase

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