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: ```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`:

"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`).
1. Re-export snippet (`export * from "<package-name>"`).
1. Parameterized Configuration `.env` reference table.
1. What Changed (Extension vs Package) comparison table.

_Reminder: NEVER execute `npm publish`._