extension-to-functions-codebase

関数コードベースへの拡張機能の移行と npm パッケージへの移行

概要

Firebase Extension を、次のいずれかに移行します。

1. ローカル Cloud Functions コードベース（アプリ統合用の functions/src/）。
2. 公開可能な npm パッケージ（V2 関数をエクスポートする、再利用可能なオープンソースパッケージ）。

ネイティブの Cloud Functions 機能（宣言型 IAM、パラメーター化設定、SDK ライフサイクルフック）を活用し、Destructuring Compatibility Shim を使用して第 1 世代のトリガーを第 2 世代に最新化します。

---

対象となる移行ワークフロー

• 対象 A：ローカル Functions コードベース（エンドユーザーアプリとの統合）

  • 出力：functions/src/ 配下のコード。設定は .env に記述します。
  • デプロイ：firebase deploy --only functions。

• 対象 B：公開可能な npm パッケージ／共有可能なパッケージ

  • 出力：V2 関数をエクスポートする再利用可能な npm パッケージ。
  • 設定：exports マップ、engines: { "node": ">=22" }、peerDependencies: { "firebase-functions": ">=6.0.0" } を指定する package.json。
  • 使用方法：利用者はパッケージをインストールし、index.ts で関数を再エクスポートします（export * from "<package-name>"）。

---

主なルールと制約

1. 宣言型 IAM と API（ローカルでの作業をゼロに）

手動の gcloud スクリプトやコンソールでの手順ではなく、ネイティブ SDK の宣言を使用します。

• 必須の GCP IAM 権限には requiresRole("roles/...") を使用します。
• Google API には requiresAPI("service.googleapis.com", "Description") を使用します。

2. グローバルパラメーターへのアクセス制限

• モジュールのトップレベル読み込み時に .value() を絶対に呼び出さないでください。
• グローバル SDK インスタンスは onInit() 内または遅延ゲッターで初期化します。

  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 の同時実行とコストの同等性

V2 では同時実行（最大 80 リクエスト）が可能になります。V1 の単一同時実行時と同等の料金を維持するには、cpu: "gcf_gen1" を設定します。

---

移行の手順

ステップ 1：Extension リソースの一覧を作成する

1. extension.yaml：
   • params → defineString、defineInt、defineBoolean、defineSecret。
   • apis → requiresAPI(...)。
   • roles → requiresRole(...)。
   • lifecycleEvents → afterFirstDeploy と afterRedeploy。
   • resources → 第 1 世代のトリガーを第 2 世代にアップグレードします（onDocumentWritten、onTaskDispatched、onRequest）。
2. ファイルとスクリプト：devDependencies、テストフレームワーク（jest）、テストスクリプトを維持します。

ステップ 2：package.json を設定する

• name: "<package-name>"、engines: { "node": ">=22" } を設定します。
• peerDependencies を設定します。

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

• ESM/CommonJS と TypeScript 宣言（lib/index.js、lib/index.d.ts）を対象とする exports マップを設定します。

ステップ 3：トリガーを V1 から V2 にアップグレードする

• Firestore：firebase-functions/v2/firestore の onDocumentWritten を使用します。
• Tasks：firebase-functions/v2/tasks の onTaskDispatched を使用します。タスクの登録時に EXT_INSTANCE_ID を削除します。
• HTTP：firebase-functions/v2/https の onRequest を使用します。
• レガシーな第 1 世代のハンドラーが (change, context) を期待する場合は、Destructuring Compatibility Shim（{ change, context }、{ snapshot, context }）を適用します。

ステップ 4：ライフサイクルイベントを変換する

Extension のライフサイクルイベントを src/index.ts の SDK ライフサイクルフックに対応付けます。

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

ステップ 5：パッケージの README とエクスポート手順

次の内容を含む README.md を生成します。

1. インストール手順（npm install）。
2. 再エクスポート用のコード（export * from "<package-name>"）。
3. パラメーター化設定の .env 参照テーブル。
4. 変更点（Extension とパッケージ）の比較テーブル。

注意：npm publish は絶対に実行しないでください。