Extension to Functions Codebase & npm Package Migration

Overview

Migrates a Firebase Extension into either:

1. A local Cloud Functions codebase (functions/src/ for app integration).
2. A publishable npm package (reusable open-source package exporting V2 functions).

Leverages native Cloud Functions features (declarative IAM, Parameterized Config, SDK Lifecycle Hooks) and modernizes 1st Gen triggers to 2nd Gen using the Destructuring Compatibility Shim.

---

Target Migration Workflows

• Target A: Local Functions Codebase (End-User App Integration)

  • Output: Code under functions/src/. Config in .env.
  • Deployment: firebase deploy --only functions.

• Target B: Publishable npm Package / Shareable Package

  • Output: Reusable npm package exporting V2 functions.
  • Configuration: package.json specifying exports map, engines: { "node": ">=22" }, and peerDependencies: { "firebase-functions": ">=6.0.0" }.
  • Usage: Consumers install package and re-export functions in index.ts (export * from "<package-name>").

---

Core Rules & Constraints

1. Declarative IAM & APIs (Zero-Local-Overhead)

Use native SDK declarations instead of manual gcloud scripts or console instructions:

• Use requiresRole("roles/...") for required GCP IAM permissions.
• Use requiresAPI("service.googleapis.com", "Description") for Google APIs.

2. Global Parameter Access Restriction

• Never call .value() at top-level module load scope.
• Initialize global SDK instances inside onInit() or lazy getters:

  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() });
  });
  

  Copy

3. V2 Concurrency & Cost Parity

V2 enables concurrency (up to 80 requests). To preserve V1 single-concurrency pricing, set cpu: "gcf_gen1".

---

Step-by-Step Migration Execution

Step 1: Inventory Extension Resources

1. extension.yaml:
   • params → defineString, defineInt, defineBoolean, defineSecret.
   • apis → requiresAPI(...).
   • roles → requiresRole(...).
   • lifecycleEvents → afterFirstDeploy & afterRedeploy.
   • resources → Upgrade 1st Gen triggers to 2nd Gen (onDocumentWritten, onTaskDispatched, onRequest).
2. Files & Scripts: Preserve devDependencies, test framework (jest), and test scripts.

Step 2: Configure package.json

• Set name: "<package-name>", engines: { "node": ">=22" }.
• Set peerDependencies:

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

  Copy
• Configure exports map targeting ESM/CommonJS and TypeScript declarations (lib/index.js, lib/index.d.ts).

Step 3: Upgrade Triggers from V1 to V2

• Firestore: Use onDocumentWritten from firebase-functions/v2/firestore.
• Tasks: Use onTaskDispatched from firebase-functions/v2/tasks. Remove EXT_INSTANCE_ID when enqueueing tasks.
• HTTP: Use onRequest from firebase-functions/v2/https.
• Apply Destructuring Compatibility Shim ({ change, context }, { snapshot, context }) where legacy 1st Gen handlers expect (change, context).

Step 4: Convert Lifecycle Events

Map extension lifecycle events to SDK lifecycle hooks in src/index.ts:

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

Step 5: Package README & Export Instructions

Generate README.md containing:

1. Installation instructions (npm install).
2. Re-export snippet (export * from "<package-name>").
3. Parameterized Configuration .env reference table.
4. What Changed (Extension vs Package) comparison table.

Reminder: NEVER execute npm publish.