momabrouk18-eng/Website

Migration d'Extension vers une Base de Code Functions et un Package npm

Aperçu

Migre une extension Firebase vers l'un des deux formats suivants :

1. Une base de code Cloud Functions locale (functions/src/ pour une intégration applicative).
2. Un package npm publiable (package open-source réutilisable exportant des fonctions V2).

Exploite les fonctionnalités natives de Cloud Functions (IAM déclaratif, configuration paramétrée, hooks SDK de cycle de vie) et modernise les déclencheurs de 1ère génération vers la 2ème génération à l'aide du shim de compatibilité par déstructuration.

---

Workflows de Migration Cibles

• Cible A : Base de code Functions locale (intégration applicative pour l'utilisateur final)

  • Sortie : Code dans functions/src/. Configuration dans .env.
  • Déploiement : firebase deploy --only functions.

• Cible B : Package npm publiable / Package partageable

  • Sortie : Package npm réutilisable exportant des fonctions V2.
  • Configuration : package.json spécifiant la map exports, engines: { "node": ">=22" }, et peerDependencies: { "firebase-functions": ">=6.0.0" }.
  • Utilisation : Les consommateurs installent le package et réexportent les fonctions dans index.ts (export * from "<nom-du-package>").

---

Règles et Contraintes Fondamentales

1. IAM et API Déclaratifs (Zéro surcharge locale)

Utilisez les déclarations natives du SDK au lieu de scripts gcloud manuels ou d'instructions console :

• Utilisez requiresRole("roles/...") pour les permissions IAM GCP requises.
• Utilisez requiresAPI("service.googleapis.com", "Description") pour les API Google.

2. Restriction d'accès aux paramètres globaux

• N'appelez jamais .value() au niveau de la portée de chargement du module.
• Initialisez les instances SDK globales à l'intérieur de onInit() ou de getters paresseux :

  import { defineString } from "firebase-functions/params";
  import { onInit } from "firebase-functions/v2";
  
  const dataset = defineString("DATASET_ID");
  let client: BigQuery;
  
  onInit(() => {
    client = new BigQuery({ datasetId: dataset.value() });
  });
  

3. Parité de concurrence et de coût V2

V2 active la concurrence (jusqu'à 80 requêtes). Pour préserver le tarif monoconcurrentiel de V1, définissez cpu: "gcf_gen1".

---

Exécution de la Migration Pas à Pas

Étape 1 : Inventaire des Ressources de l'Extension

1. extension.yaml :
   • params → defineString, defineInt, defineBoolean, defineSecret.
   • apis → requiresAPI(...).
   • roles → requiresRole(...).
   • lifecycleEvents → afterFirstDeploy & afterRedeploy.
   • resources → Mettez à niveau les déclencheurs de 1ère génération vers la 2ème génération (onDocumentWritten, onTaskDispatched, onRequest).
2. Fichiers et scripts : Conservez les devDependencies, le framework de test (jest) et les scripts de test.

Étape 2 : Configurer package.json

• Définissez name: "<nom-du-package>", engines: { "node": ">=22" }.
• Définissez peerDependencies :

  "peerDependencies": {
    "firebase-admin": "^11.0.0 || ^12.0.0",
    "firebase-functions": ">=6.0.0"
  }
  

• Configurez la map exports ciblant ESM/CommonJS et les déclarations TypeScript (lib/index.js, lib/index.d.ts).

Étape 3 : Mettre à Niveau les Déclencheurs de V1 vers V2

• Firestore : Utilisez onDocumentWritten depuis firebase-functions/v2/firestore.
• Tasks : Utilisez onTaskDispatched depuis firebase-functions/v2/tasks. Supprimez EXT_INSTANCE_ID lors de la mise en file d'attente des tâches.
• HTTP : Utilisez onRequest depuis firebase-functions/v2/https.
• Appliquez le shim de compatibilité par déstructuration ({ change, context }, { snapshot, context }) là où les gestionnaires de 1ère génération hérités attendent (change, context).

Étape 4 : Convertir les Événements de Cycle de Vie

Mappez les événements de cycle de vie de l'extension aux hooks SDK de cycle de vie dans src/index.ts :

• onInstall → afterFirstDeploy({ task: { function: "initTask" } })
• onUpdate / onConfigure → afterRedeploy({ task: { function: "setupTask" } })

Étape 5 : README du Package et Instructions d'Exportation

Générez README.md contenant :

1. Instructions d'installation (npm install).
2. Extrait de réexportation (export * from "<nom-du-package>").
3. Tableau de référence de la configuration paramétrée .env.
4. Tableau comparatif Ce Qui a Changé (Extension vs Package).

Rappel : N'exécutez JAMAIS npm publish.