THE3RDTRAINER/Homepage

Migration von Extension zur Functions-Codebasis & npm-Paket

Übersicht

Migriert eine Firebase Extension in eines von zwei Zielen:

1. Eine lokale Cloud Functions-Codebasis (functions/src/ für die App-Integration).
2. Ein veröffentlichtes npm-Paket (wiederverwendbares Open-Source-Paket, das V2-Funktionen exportiert).

Nutzt native Cloud Functions-Funktionen (deklaratives IAM, parametrisierte Konfiguration, SDK-Lifecycle-Hooks) und modernisiert Erstgeneration-Trigger auf die Zweite Generation mithilfe des Destrukturierungs-Kompatibilitäts-Shims.

---

Ziel-Migrationsworkflows

• Ziel A: Lokale Functions-Codebasis (Endbenutzer-App-Integration)

  • Ausgabe: Code unter functions/src/. Konfiguration in .env.
  • Bereitstellung: firebase deploy --only functions.

• Ziel B: Veröffentlichtes npm-Paket / Teilbares Paket

  • Ausgabe: Wiederverwendbares npm-Paket, das V2-Funktionen exportiert.
  • Konfiguration: package.json mit exports-Map, engines: { "node": ">=22" } und peerDependencies: { "firebase-functions": ">=6.0.0" }.
  • Nutzung: Konsumenten installieren das Paket und exportieren die Funktionen in index.ts erneut (export * from "<paket-name>").

---

Kernregeln & Einschränkungen

1. Deklaratives IAM & APIs (Kein lokaler Overhead)

Verwenden Sie native SDK-Deklarationen anstelle von manuellen gcloud-Skripten oder Konsolenanweisungen:

• Verwenden Sie requiresRole("roles/...") für erforderliche GCP-IAM-Berechtigungen.
• Verwenden Sie requiresAPI("service.googleapis.com", "Beschreibung") für Google-APIs.

2. Einschränkung des globalen Parameterzugriffs

• Rufen Sie niemals .value() auf der obersten Modul-Ladeebene auf.
• Initialisieren Sie globale SDK-Instanzen innerhalb von onInit() oder Lazy-Gettern:

  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. V2-Nebenläufigkeit & Kostenparität

V2 ermöglicht Nebenläufigkeit (bis zu 80 Anfragen). Um die V1-Einzelnebenläufigkeitspreise beizubehalten, setzen Sie cpu: "gcf_gen1".

---

Schritt-für-Schritt-Migrationsausführung

Schritt 1: Bestandsaufnahme der Extension-Ressourcen

1. extension.yaml:
   • params → defineString, defineInt, defineBoolean, defineSecret.
   • apis → requiresAPI(...).
   • roles → requiresRole(...).
   • lifecycleEvents → afterFirstDeploy & afterRedeploy.
   • resources → Upgrade von Erstgeneration-Triggern auf Zweite Generation (onDocumentWritten, onTaskDispatched, onRequest).
2. Dateien & Skripte: Bewahren Sie devDependencies, Test-Framework (jest) und Testskripte auf.

Schritt 2: Konfigurieren Sie package.json

• Setzen Sie name: "<paket-name>", engines: { "node": ">=22" }.
• Setzen Sie peerDependencies:

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

• Konfigurieren Sie die exports-Map für ESM/CommonJS und TypeScript-Deklarationen (lib/index.js, lib/index.d.ts).

Schritt 3: Trigger von V1 auf V2 upgraden

• Firestore: Verwenden Sie onDocumentWritten aus firebase-functions/v2/firestore.
• Tasks: Verwenden Sie onTaskDispatched aus firebase-functions/v2/tasks. Entfernen Sie EXT_INSTANCE_ID beim Einreihen von Tasks.
• HTTP: Verwenden Sie onRequest aus firebase-functions/v2/https.
• Wenden Sie den Destrukturierungs-Kompatibilitäts-Shim ({ change, context }, { snapshot, context }) an, wenn Legacy-Erstgeneration-Handler (change, context) erwarten.

Schritt 4: Lifecycle-Ereignisse konvertieren

Ordnen Sie Extension-Lifecycle-Ereignisse SDK-Lifecycle-Hooks in src/index.ts zu:

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

Schritt 5: Paket-README & Exportanweisungen

Generieren Sie README.md mit:

1. Installationsanweisungen (npm install).
2. Re-Export-Snippet (export * from "<paket-name>").
3. Referenztabelle zur parametrisierten Konfiguration .env.
4. Vergleichstabelle „Was hat sich geändert (Extension vs. Paket)“.

Hinweis: Führen Sie NIEMALS npm publish aus.