extension-to-functions-codebase

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