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:

typescript 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 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).

1. Files & Scripts: Preserve devDependencies, test framework (jest), and

test scripts.

Step 2: Configure package.json

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

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

• 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._