THE3RDTRAINER/Homepage

확장 프로그램 → Functions 코드베이스 및 npm 패키지 마이그레이션

개요

Firebase 확장 프로그램을 다음 중 하나로 마이그레이션합니다.

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

네이티브 Cloud Functions 기능(선언적 IAM, 매개변수화된 구성, SDK 라이프사이클 훅)을 활용하고, 구조 분해 호환성 Shim(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()를 호출하지 마십시오.
• onInit() 내부 또는 지연 게터(lazy getter)에서 전역 SDK 인스턴스를 초기화합니다.

  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단계: 확장 프로그램 리소스 목록 작성

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)를 예상하는 곳에 구조 분해 호환성 Shim({ change, context }, { snapshot, context })을 적용합니다.

4단계: 라이프사이클 이벤트 변환

확장 프로그램 라이프사이클 이벤트를 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. 변경 사항 비교 표(확장 프로그램 vs 패키지).

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