Firebase Implementation Patterns

Ce skill couvre les patterns concrets pour construire un backend Firebase production-grade. Il complète l'agent firebase-expert en donnant des recettes prêtes à coller.

MCP server disponible : ce plugin déclare firebase dans .mcp.json. Claude Code peut invoquer firebase-tools directement pour lister les projets, déployer, lire les logs.

1. Firestore data modeling

Pattern subcollections vs root collections

Subcollections quand :

• Ownership stricte parent → enfants
• Tu as toujours besoin de l'enfant via le parent
• Exemple : users/{userId}/notifications/{notifId}

Root collections + foreign key quand :

• Tu fais des queries cross-tenant
• L'enfant a une vie indépendante du parent
• Exemple : projects avec ownerId

Counter sharding (anti hot doc)

Un document Firestore = 1 write/sec max. Pour un compteur de likes/views/votes :

// 10 shards aléatoires
const NUM_SHARDS = 10

async function incrementLikeCount(postId: string) {
  const shardId = Math.floor(Math.random() * NUM_SHARDS)
  const shardRef = db.doc(`posts/${postId}/likes_shards/${shardId}`)
  await shardRef.set({ count: FieldValue.increment(1) }, { merge: true })
}

async function getLikeCount(postId: string) {
  const shards = await db.collection(`posts/${postId}/likes_shards`).get()
  return shards.docs.reduce((sum, doc) => sum + (doc.data().count ?? 0), 0)
}

Denormalization (lecture optimisée)

Stocker le userName et userAvatar dans chaque post au lieu de joindre, parce que Firestore n'a PAS de jointures et chaque lookup = facturation.

Synchronisation via Cloud Function users.onUpdate qui propage le changement aux posts.

2. Firestore Security Rules

Pattern multi-tenant avec custom claims

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {

    function isSignedIn() {
      return request.auth != null;
    }

    function isAppCheckValid() {
      return request.app != null && request.app.attested == true;
    }

    function isOwner(userId) {
      return request.auth.uid == userId;
    }

    function tenantId() {
      return request.auth.token.tenant_id;
    }

    function hasRole(role) {
      return request.auth.token.role == role;
    }

    // Empêche tout par défaut
    match /{document=**} {
      allow read, write: if false;
    }

    match /tenants/{tid}/projects/{pid} {
      allow read: if isSignedIn() && isAppCheckValid() && tid == tenantId();
      allow create: if isSignedIn() && isAppCheckValid() && tid == tenantId()
                    && request.resource.data.ownerId == request.auth.uid
                    && request.resource.data.keys().hasOnly(['name', 'ownerId', 'createdAt']);
      allow update: if isSignedIn() && isAppCheckValid() && tid == tenantId()
                    && (isOwner(resource.data.ownerId) || hasRole('admin'));
      allow delete: if isSignedIn() && isAppCheckValid() && hasRole('admin');
    }
  }
}

Tests RLS avec emulator

// firestore.rules.test.ts
import { initializeTestEnvironment, assertSucceeds, assertFails } from '@firebase/rules-unit-testing'

const env = await initializeTestEnvironment({
  projectId: 'test-project',
  firestore: { rules: readFileSync('firestore.rules', 'utf8') },
})

const alice = env.authenticatedContext('alice', { tenant_id: 'tenantA', role: 'user' })
const bob = env.authenticatedContext('bob', { tenant_id: 'tenantB', role: 'user' })

await assertSucceeds(alice.firestore().doc('tenants/tenantA/projects/p1').get())
await assertFails(bob.firestore().doc('tenants/tenantA/projects/p1').get())

firebase emulators:exec --only firestore "vitest run firestore.rules.test.ts"

3. Cloud Functions Gen 2

Pattern idempotent Firestore trigger

import { onDocumentCreated } from 'firebase-functions/v2/firestore'
import { defineSecret } from 'firebase-functions/params'
import { initializeApp } from 'firebase-admin/app'
import { getFirestore, FieldValue } from 'firebase-admin/firestore'

initializeApp()
const db = getFirestore()

const sendgridKey = defineSecret('SENDGRID_API_KEY')

export const onNewOrder = onDocumentCreated(
  {
    document: 'orders/{orderId}',
    secrets: [sendgridKey],
    region: 'europe-west1',
    minInstances: 1,
  },
  async (event) => {
    const order = event.data?.data()
    if (!order) return

    // IDEMPOTENCY: utilise event.id comme clé unique
    const processedRef = db.doc(`processed_events/${event.id}`)
    const processed = await processedRef.get()
    if (processed.exists) {
      console.log('Already processed', event.id)
      return
    }

    try {
      // ... logique métier ...
      await sendOrderConfirmation(order, sendgridKey.value())

      // Marque comme traité APRÈS le succès
      await processedRef.set({ processedAt: FieldValue.serverTimestamp() })
    } catch (err) {
      console.error('Failed to process order', err)
      throw err // Firebase retry
    }
  }
)

HTTPS Callable function (RPC depuis le client)

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

export const refundOrder = onCall(
  { region: 'europe-west1', enforceAppCheck: true },
  async (request) => {
    if (!request.auth) {
      throw new HttpsError('unauthenticated', 'Sign in required')
    }
    if (request.auth.token.role !== 'admin') {
      throw new HttpsError('permission-denied', 'Admin only')
    }

    const { orderId } = request.data
    if (!orderId || typeof orderId !== 'string') {
      throw new HttpsError('invalid-argument', 'orderId required')
    }

    // ... refund logic ...
    return { success: true }
  }
)

4. Auth patterns

Custom claims pour RBAC

import { getAuth } from 'firebase-admin/auth'

// Côté admin (Cloud Function ou backend privilégié)
await getAuth().setCustomUserClaims(userId, {
  tenant_id: 'tenantA',
  role: 'admin',
})

// Le client doit refresh son token pour voir les nouveaux claims :
// firebase.auth().currentUser?.getIdToken(true)

Anonymous auth + linking

// Client web
import { getAuth, signInAnonymously, linkWithCredential, EmailAuthProvider } from 'firebase/auth'

const auth = getAuth()

// 1. User commence en anonymous
await signInAnonymously(auth)
// 2. Plus tard, il s'inscrit
const credential = EmailAuthProvider.credential('user@example.com', 'password')
await linkWithCredential(auth.currentUser!, credential)
// → Garde le même UID, conserve toutes les données Firestore liées

5. Cloud Storage avec rules

rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
    match /users/{userId}/avatars/{filename} {
      allow read: if true; // Avatars publics
      allow write: if request.auth != null
                   && request.auth.uid == userId
                   && request.resource.size < 5 * 1024 * 1024  // 5 MB max
                   && request.resource.contentType.matches('image/.*');
    }
  }
}

6. App Check enforcement

Activation client (web)

import { initializeAppCheck, ReCaptchaEnterpriseProvider } from 'firebase/app-check'

const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider('SITE_KEY'),
  isTokenAutoRefreshEnabled: true,
})

Enforcement Firestore + Functions

• Firestore : request.app.attested == true dans les rules
• Functions : enforceAppCheck: true dans les options

Audit avant enforcement

Activer en mode "Unenforced" dans Firebase Console pour 2-4 semaines, surveiller la distribution des requêtes attestées vs non-attestées dans Metrics, puis switcher en "Enforced" quand >99% des requêtes légitimes sont attestées.

7. FCM push notifications

Stockage des tokens

// Côté client mobile (iOS Swift, Android Kotlin, web)
const token = await getToken(messaging, { vapidKey: VAPID_KEY })
await db.doc(`users/${userId}/devices/${deviceId}`).set({
  token,
  platform: 'ios',
  updatedAt: FieldValue.serverTimestamp(),
})

Envoi d'une notif (Cloud Function)

import { getMessaging } from 'firebase-admin/messaging'

const tokens = (await db.collection(`users/${userId}/devices`).get())
  .docs.map(d => d.data().token)

await getMessaging().sendEachForMulticast({
  tokens,
  notification: { title: 'Nouvelle commande', body: '#42 reçue' },
  data: { orderId: '42' },
})

8. Vertex AI in Firebase

import { getVertexAI, getGenerativeModel } from 'firebase/vertexai'

const vertexAI = getVertexAI(firebaseApp)
const model = getGenerativeModel(vertexAI, { model: 'gemini-1.5-flash' })

const result = await model.generateContent('Résume ce texte en 3 lignes : ...')
console.log(result.response.text())

App Check est obligatoire pour empêcher l'abus.

9. Backup et disaster recovery

# Export programmé via gcloud
gcloud firestore export gs://my-backup-bucket/$(date +%F)

# Restore (vers un nouveau projet ou un staging)
gcloud firestore import gs://my-backup-bucket/2026-04-08

À automatiser avec une Cloud Scheduler + Cloud Function ou un job pg_cron-style.

Anti-patterns critiques

1. Rules allow read, write: if true — exfiltration de toute la base
2. Pas d'App Check — bots / scripts qui flooden la base
3. Listener onSnapshot non-détaché — fuite mémoire + facturation
4. Counter incrementé sur 1 doc — perte de writes
5. Service account JSON committé en Git — game over
6. Schema sans keys().hasOnly([...]) dans les rules — injection de champs malveillants
7. Real-time listeners sur 10k+ docs sans pagination — bill choc
8. Pas de monitoring billing — surprise facture en fin de mois

Checklist

• Firebase project + plan Blaze (pay-as-you-go) si besoin de Cloud Functions
• Auth providers configurés
• Firestore rules écrites + testées avec emulator
• App Check activé
• Cloud Functions Gen 2 avec idempotency
• Secrets via Cloud Secret Manager
• Backup auto Firestore
• Crashlytics + Performance Monitoring
• Budget alerts Cloud Billing

Quand déléguer

• Schema design lourd → agent nosql-specialist
• Mobile app native intégrant Firebase → agents flutter-dart-expert, expo-expert
• Choix Firebase vs Supabase → agent firebase-expert (j'ai aussi supabase-architect)
• Auth providers complémentaires → skill auth-providers (atum-stack-web)