extension-to-functions-codebase

Официальный навык Firebase посвящён миграции установленного Firebase Extension или его исходников в отдельную кодовую базу Cloud Functions либо в публикуемый npm-пакет. Его полезно читать как пошаговую карту преобразования, когда расширение уже содержит параметры, роли, API, обработчики и lifecycle-сценарии, а команде нужно сохранить поведение и одновременно перейти к современным возможностям Firebase Functions. Навык не предлагает копировать исходный SKILL.md в продукт: он объясняет, какие части extension.yaml нужно инвентаризировать, какие решения перенести в код и где проверить совместимость. Для локальной кодовой базы результатом миграции становятся функции в functions/src/ и конфигурация окружения в .env. Для переиспользуемого пакета результатом является npm-пакет, который экспортирует функции V2; в таком варианте отдельно описываются package.json, карта exports, требуемая версия Node.js не ниже 22 и peer-зависимость firebase-functions версии 6 или новее. Пользователь пакета подключает экспорт из index.ts, а README должен объяснить установку, повторный экспорт, параметризованную конфигурацию и различия между Extension и пакетом. Само руководство подчёркивает, что публикацию npm-пакета выполнять не следует. Первый рабочий этап — разобрать extension.yaml. Параметры переводятся в defineString, defineInt, defineBoolean или defineSecret; объявленные API — в requiresAPI; роли IAM — в requiresRole; lifecycleEvents — в afterFirstDeploy и afterRedeploy; ресурсы — в соответствующие обработчики второго поколения. Такой инвентарь связывает декларативную конфигурацию с итоговой функцией и уменьшает риск потерять обязательное разрешение или событие при переносе. Для IAM и API навык рекомендует нативные декларации вместо ручных gcloud-скриптов и лишних локальных шагов. Отдельно проверяется граница инициализации параметров. Значение параметра нельзя получать через .value() на верхнем уровне модуля: глобальные клиенты SDK следует создавать в onInit() или через ленивый getter, чтобы конфигурация была доступна в допустимый момент жизненного цикла. При переносе триггеров используются onDocumentWritten для Firestore, onTaskDispatched для задач и onRequest для HTTP из пакетов firebase-functions/v2. Для старых обработчиков применяется совместимый деструктурирующий shim с change/context или snapshot/context. Для задач нужно убрать EXT_INSTANCE_ID из постановки в очередь, если его наличие было связано с первым поколением. Переход на V2 меняет модель конкурентности: навык указывает предел до 80 одновременных запросов и отдельно предупреждает о сохранении стоимости V1, если требуется прежняя одиночная конкурентность. В таком случае следует выставить cpu: "gcf_gen1". Lifecycle-события маппятся в SDK-хуки: инициализация после первого деплоя идёт через afterFirstDeploy, а обновление или конфигурация — через afterRedeploy. Эти решения подходят для миграции с контролируемым изменением, но не заменяют ревизию extension.yaml, исходных файлов, секретов, IAM и тестов конкретного расширения. Ограничения важны: карточка описывает метод переноса и требования к каркасу проекта, а не гарантирует, что любая Extension автоматически совместима с V2. Перед изменением нужно проверить реальные параметры, зависимости, обработчики и lifecycle-события исходника, затем выполнить собственные тесты и deploy-проверки. Нельзя переносить не подтверждённые этой карточкой детали, а npm publish остаётся за пределами рекомендованного workflow.