Extension to Functions Codebase & npm Package Migration

Extension to Functions Codebase & npm Package Migration은(는) 무엇을 하나요?

개요

Firebase Extension을 다음 중 하나로 마이그레이션합니다:

1. 로컬 Cloud Functions 코드베이스(앱 통합용 functions/src/)
2. 게시 가능한 npm 패키지(V2 함수를 내보내는 재사용 가능한 오픈 소스 패키지)

네이티브 Cloud Functions 기능(선언적 IAM, Parameterized Config, SDK Lifecycle Hooks)을 활용하고, Destructuring Compatibility Shim을 사용하여 1세대 트리거를 2세대 트리거로 현대화합니다.

---

대상 마이그레이션 워크플로

• 대상 A: 로컬 Functions 코드베이스(최종 사용자 앱 통합)

  • 출력: functions/src/ 아래 코드. .env 파일의 설정.
  • 배포: firebase deploy --only functions

• 대상 B: 게시 가능한 npm 패키지 / 공유 가능한 패키지

  • 출력: V2 함수를 내보내는 재사용 가능한 npm 패키지.
  • 설정: package.json에 exports 맵, engines: { "node": ">=22" }, peerDependencies: { "firebase-functions": ">=6.0.0" } 명시.
  • 사용법: 소비자가 패키지를 설치하고 index.ts에서 함수를 다시 내보냅니다 (export * from "<package-name>").

---

핵심 규칙 및 제약 사항

1. 선언적 IAM 및 API (로컬 오버헤드 제로)

수동 gcloud 스크립트나 콘솔 지침 대신 네이티브 SDK 선언을 사용합니다:

• requiresRole("roles/...")로 필요한 GCP IAM 권한을 명시합니다.
• requiresAPI("service.googleapis.com", "설명")로 Google API를 활성화합니다.

2. 전역 파라미터 접근 제한

• 최상위 모듈 로드 스코프에서 .value()를 절대 호출하지 마세요.
• 전역 SDK 인스턴스는 onInit() 또는 지연 게터(lazy getter) 내부에서 초기화합니다:

  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. Parameterized Configuration .env 참조 테이블
4. 변경 사항 (Extension vs Package) 비교 테이블

참고: npm publish를 절대 실행하지 마십시오.