Extension to Functions Codebase & npm Package Migration

Overview

1. A local Cloud Functions codebase (

   functions/src/

   for app integration).
2. A publishable npm package (reusable open-source package exporting V2 functions).

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)

gcloud

• 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

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

  :
  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

src/index.ts

• onInstall

  →

  afterFirstDeploy({ task: { function: "initTask" } })

• onUpdate

  /

  onConfigure

  →

  afterRedeploy({ task: { function: "setupTask" } })

Step 5: Package README & Export Instructions

README.md

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.

npm publish