Migrar as Extensões do Firebase para kits de funções

Neste guia, mostramos como migrar suas extensões do ambiente Firebase Extensions descontinuado para um kit de funções que você pode instalar e implantar na sua própria base de código Cloud Functions para Firebase (2ª geração).

Firebase Extensions gerenciava todos os aspectos da criação, atualização e remoção de extensões. Os kits de funções empacotam os recursos das extensões como Cloud Functions for Firebase típicos de segunda geração. Como os kits de funções são Cloud Functions padrão, você os cria, atualiza, exclui e resolve problemas usando a CLI Firebase no projeto Firebase. Este guia prepara você para gerenciar suas funções agora e adotar atualizações à medida que elas forem disponibilizadas.

Neste guia, a extensão Stream Cloud Firestore para BigQuery (firestore-bigquery-export) é usada como exemplo para mostrar os comandos e a resposta ao comando de cada etapa da migração.

Aviso: este guia de migração tem etapas que buscam a configuração da extensão atual para configurar o kit de funções de substituição de forma idêntica. Isso não será possível após 31 de março de 2027. Recomendamos que você faça a migração antes de 31 de março de 2027. Se você não vai migrar antes disso, pode exportar preventivamente a configuração da extensão seguindo as instruções em Configurar a instância do kit de funções de forma idêntica à extensão.

Determine seu caminho de migração

O Firebase incentiva todos os publishers do Firebase Extensions a criar substituições para as extensões como kits de funções publicados no npm. É possível verificar se uma substituição do kit de funções está disponível para suas extensões de algumas maneiras diferentes:

• Acesse a página "Extensões" do console do Firebase do seu projeto. Cada extensão instalada indica se há uma substituição de kit de funções disponível.

• Execute firebase ext:list no projeto Firebase em um terminal para mostrar quais das suas extensões instaladas têm substituições oficiais:

  firebase ext:list --project my-project
  

  i  extensions: ensuring required API firebaseextensions.googleapis.com is enabled...
  ✔  extensions: required API firebaseextensions.googleapis.com is enabled
  i  extensions: list of extensions installed in my-project:
  ┌────────────────────────────────────┬───────────┬────────────────────────────────┬────────┬─────────┬─────────────────────┬───────────────────────────────────────────────────┐
  │ Extension                          │ Publisher │ Instance ID                    │ State  │ Version │ Your last update    │ Replacement Kit                                   │
  ├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤
  │ firebase/firestore-bigquery-export │ firebase  │ firestore-bigquery-export-zbrp │ ACTIVE │ 0.3.2   │ 2026-06-10 18:35:03 │ @firebase-function-kits/firestore-bigquery-export │
  ├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤
  │ firebase/storage-resize-images     │ firebase  │ storage-resize-images          │ ACTIVE │ 0.3.6   │ 2026-06-03 17:41:24 │                                                   │
  └────────────────────────────────────┴───────────┴────────────────────────────────┴────────┴─────────┴─────────────────────┴───────────────────────────────────────────────────┘
  ⚠ Notice: Firebase Extensions will shut down on March 31, 2027. Learn more: https://firebase.google.com/docs/extensions/faq-and-troubleshooting
  

Se uma substituição oficial do kit de funções estiver disponível para sua extensão, migre-a usando a seção Migrar para kits de funções no npm.

Se você não encontrar uma substituição publicada, crie uma ramificação do código da extensão e crie sua própria substituição, porque todas as extensões são de código aberto. Para fazer isso, siga o guia Migrar para um kit de funções criado por você.

Observação: outros desenvolvedores podem criar substituições não oficiais do kit de funções. O Google não valida nem anuncia substituições não oficiais, mas, se você encontrar e validar uma, use estes guias de migração para migrar para ela.

Selecione o caminho de migração:

Migrar para kits de funções no npm Migrar para um kit de funções criado por você

Migrar para kits de funções no npm

Verificar limitações conhecidas da migração

Antes de começar a migrar uma instância de extensão, verifique se a configuração usa algum dos seguintes recursos que exigem uma solução alternativa ou ainda não são compatíveis em kits de funções:

• Os repositórios Docker personalizados e as chaves do KMS exigem uma solução alternativa manual O Cloud Functions for Firebase não é compatível com parâmetros de sistema de substituição para configurar um repositório Docker personalizado ou uma chave de criptografia gerenciada pelo cliente (chave do KMS). Se a configuração da extensão definir qualquer um desses parâmetros, consulte a solução alternativa para perguntas frequentes.

Antes de começar

Você precisa configurar a CLI Firebase e inicializar um projeto Firebase. Ao usar a CLI, verifique se você está usando a versão >= 15.32.0 do firebase-tools, que tem os novos comandos de migração e kit de funções.

Observação: todos os comandos da CLI neste guia incluem a flag --project <project-id> para especificar explicitamente o projeto de destino. Se você estiver trabalhando no projeto padrão configurado em .firebaserc, poderá omitir a flag --project.

Permissões e papéis necessários da conta

Dependendo do que precisa ser criado e configurado pela CLI Firebase durante a migração, a conta usada para autenticar com Firebase e Google Cloud precisa ter os seguintes papéis:

• roles/firebaseextensions.editor
• roles/cloudbuild.builds.editor
• roles/artifactregistry.writer
• roles/run.developer
• roles/iam.serviceAccountUser
• roles/iam.serviceAccountCreator
• roles/cloudfunctions.admin (se você precisar fazer setIamPermissions para endpoints públicos)
• roles/secretmanager.admin (se estiver usando secrets)
• roles/serviceusage.serviceUsageAdmin (se você precisar ativar novas APIs)

Recomendamos usar uma conta que já tenha instalado extensões e implantado funções, já que a maioria dessas permissões já terá sido concedida. Se a conta de migração precisar de mais papéis, siga as instruções do IAM Google Cloud para adicioná-los.

Escolher um fluxo de trabalho da CLI

Para migrar de uma instância de extensão para um kit de funções disponível no npm, escolha uma das seguintes opções:

• (Recomendado) Migre usando o comando da CLI ext:migrate. Esse comando implanta a substituição do kit de funções antes de desinstalar a extensão que ele substitui.
• Migre usando os comandos da CLI dos kits de funções. É possível usar comandos separados para atualizar a extensão, instalar um kit de funções, configurá-lo como a extensão, implantar o kit e desinstalar a extensão. Isso oferece mais flexibilidade para reordenar comandos ou realizar trabalhos adicionais entre as etapas.

Migrar usando o ext:migrate

Uma vez por instância de extensão, inicie uma migração executando:

firebase ext:migrate --project <project-id>

Este comando mostra como:

1. Selecionar uma extensão para migrar que tenha um kit de funções oficial de substituição disponível.
2. Selecionar uma instância específica dessa extensão.
3. Atualizar a extensão para a versão mais recente, se necessário.
4. Instalar o kit de funções e configurar uma instância da mesma forma que a instância de extensão.
5. Implantação do kit de funções.
6. Verificar se o kit de funções foi implantado com sucesso e se todos os hooks de ciclo de vida, se houver, foram executados.
7. Desinstale a instância da extensão.

Se você souber a extensão ou instância de extensão específica que quer migrar, especifique-a usando as seguintes flags de linha de comando:

firebase ext:migrate --extension firebase/firestore-bigquery-export --project <project-id>

# or

firebase ext:migrate --ext-instance firestore-bigquery-export-abcd --project <project-id>

Se você souber o pacote específico para o qual quer migrar, principalmente se não for um pacote de substituição oficial listado pelo Google, especifique-o usando a flag --package:

firebase ext:migrate --ext-instance firestore-bigquery-export-abcd --package @firebase-function-kits/firestore-bigquery-export --project <project-id>

Aviso: se você chamar ext:migrate com --force, a extensão será excluída imediatamente após a implantação da substituição sem nenhuma verificação. Isso pode resultar em um breve tempo de inatividade, mesmo em uma migração bem-sucedida, já que pode levar alguns minutos para que o Eventarc provisione totalmente e para que a substituição do kit processe eventos de qualquer extensão acionada por evento.

Verificar uma implantação do kit de funções

Para verificar se o firebase deploy do kit não teve erros, confira os registros de implantação para saber se algum hook de ciclo de vida foi acionado. Extensões populares, como Stream Cloud Firestore para BigQuery, usam hooks de ciclo de vida. Confira abaixo um exemplo de como um hook de ciclo de vida aparece quando é acionado:

i  functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔  functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/europe-west1/queues/kit-firestore-bigquery-export-initBigQuerySync.
i  functions: View logs for afterFirstDeploy at: https://console.cloud.google.com/logs/query;query=resource.type%3D%22cloud_run_revision%22%0Aresource.labels.service_name%3D%22kit-firestore-bigquery-export--initbigquerysync%22%0Aresource.labels.location%3D%22europe-west1%22;project=my-project

Essas mensagens de registro confirmam o seguinte:

• Um hook de ciclo de vida foi encontrado e executado.
• Uma tarefa foi enfileirada na fila de tarefas associada ao hook do ciclo de vida.
• Um link para o Cloud Logging foi fornecido para que você possa validar se a tarefa foi concluída sem erros.

Siga o link de registros até o console Google Cloud para validar se não há erros nos registros e se o evento da fila de tarefas foi processado corretamente. Se o evento de ciclo de vida não for executado corretamente, você poderá acioná-lo novamente executando:

firebase functions:lifecycle:run <hook-name> <codebase>

Se você estiver implantando uma instância do kit de funções pela primeira vez, execute:

firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>

Se, a qualquer momento durante a validação, você decidir interromper ou desfazer essa migração, desinstale o kit seguindo as instruções em Desinstalar a extensão.

Analisar o README do kit de funções

Alguns kits podem exigir mais trabalho do que o que é processado automaticamente pelos kits de função. Revise o README do kit que você está instalando e siga as instruções adicionais.

Migrar usando a CLI do Function Kits

Antes de começar, identifique e anote o ID da instância da extensão que você quer migrar para um kit e o nome do pacote npm do kit substituto. É possível encontrar os dois usando a saída de firebase ext:list. Consulte Determinar seu caminho de migração para um exemplo de uso de ext:list.

1. Fazer upgrade da instância de extensão para a versão mais recente

Você precisa atualizar a extensão para a versão mais recente para minimizar a diferença entre a instância da extensão e o kit de substituição. Se a extensão não for atualizada, poderá haver mudanças significativas e incompatíveis entre a instância da extensão e a substituição do kit. A configuração exportada pode não corresponder ao que o kit espera devido a mudanças de parâmetros em diferentes versões.

Use uma das seguintes opções para atualizar a extensão, dependendo de onde ela foi instalada:

• No console do Firebase
• Na CLI Firebase, use:
  • firebase ext:update <extension-instance-id> --project <project-id> firebase deploy --only extensions --project <project-id>

Se você pular esta etapa, a CLI vai pedir que você faça upgrade ao exportar a configuração se a extensão não estiver na versão mais recente.

2. Revise e instale a instância do kit de funções de substituição

É possível instalar o kit de funções usando o seguinte comando da CLI:

firebase functions:kits:install --template migration --no-configure --package <npm-package-name> --project <project-id>

Ao escolher um ID de instância para seu kit durante a instalação, anote-o para usar mais tarde nas instruções de migração.

Depois que o kit é instalado, um novo diretório é criado no projeto Firebase com um local como function-kits/<kit-name>/source que contém o pacote npm com o kit substituindo sua extensão e um arquivo index.ts básico que exporta essas funções para o Firebase implantar e definir a configuração personalizada.

Leia o README do kit e siga as instruções adicionais listadas nele.

Se você tiver várias instâncias do kit no mesmo projeto, repita esse comando para criar novas instâncias do mesmo kit. Também é possível implantar uma única instância do kit em dois projetos Firebase diferentes com configurações diferentes (por exemplo, um projeto de preparo e um de produção). Para saber mais sobre essas configurações avançadas, consulte Migrações avançadas.

Exemplo prático:

firebase functions:kits:install --template migration --no-configure --package @firebase-function-kits/firestore-bigquery-export --project my-project

3. Configure a instância do kit de funções de forma idêntica à extensão

É necessário personalizar essa instância do kit com uma configuração idêntica à extensão que ela está substituindo. É possível exportar a configuração da instância da extensão para um arquivo .env, que armazena dados de configuração de parâmetros, variáveis de ambiente e referências secretas para todos os Cloud Functions, incluindo kits. Para exportar diretamente para o arquivo de configuração do seu kit, execute:

firebase ext:export --mode functions --instance <extension-instance-id> --kit-instance <kit-instance-id> --project <project-id>

Ao final desta etapa, as informações de configuração da instância serão armazenadas em um arquivo .env específico do projeto no diretório de configuração da instância, como function-kits/<kit-name>/config-<instance-id>/.env.<project-id>

Observação: se você não tiver atualizado a extensão para a versão mais recente antes da exportação, o comando vai pedir que você faça isso.

4. Implantar e verificar a substituição do kit

Agora que o kit está instalado e disponível como um conjunto de funções, você pode fazer o deployment da substituição do kit. Os kits de funções funcionam como funções padrão, em que cada instância do kit atua como uma base de código separada para organizar suas funções. Você pode implantar todas as suas funções ou apenas uma instância de kit específica. Ao migrar uma única instância de extensão, implante apenas essa instância do kit.

Se o kit usar novos parâmetros que não estavam presentes na instância da extensão de que você migrou, a CLI Firebase vai pedir esses parâmetros no início do processo de implantação. Isso não é esperado neste exemplo prático de uma extensão firestore-bigquery-export atualizada, mas muitos kits solicitam um novo parâmetro para qualquer origem de acionamento de evento usada pelo kit. Como parte dessa migração, os kits atualizados usam funções de 2ª geração, enquanto as extensões usavam funções de 1ª geração. Na 2ª geração, as funções ficam perto das fontes de eventos e são adicionadas como um parâmetro extra. Em atualizações futuras, se novos parâmetros forem adicionados, a CLI vai pedir que você os inclua na próxima implantação.

Exemplo prático:

firebase deploy --only functions:firestore-bigquery-export --project my-project

Saída:

=== Deploying to 'my-project'...
i  deploying functions
i  functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project
i  functions: ensuring required API bigquery.googleapis.com is enabled...
i  functions: ensuring required API cloudtasks.googleapis.com is enabled...
✔  functions: required APIs are enabled
i  functions: granting declarative IAM roles to managed service account:
   - BigQuery Data Editor
   - BigQuery User
   - Cloud Datastore User
   - Eventarc Event Receiver
   - roles/run.invoker
✔  functions: successfully granted IAM roles
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-fsexportbigquery(us-central1)...
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-initBigQuerySync(us-central1)...
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-setupBigQuerySync(us-central1)...
✔  functions[kit-firestore-bigquery-export-fsexportbigquery(us-central1)] Successful create operation.
✔  functions[kit-firestore-bigquery-export-initBigQuerySync(us-central1)] Successful create operation.
✔  functions[kit-firestore-bigquery-export-setupBigQuerySync(us-central1)] Successful create operation.
i  functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔  functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/us-central1/queues/kit-firestore-bigquery-export-initBigQuerySync.
✔  Deploy complete!

Observação: pode levar alguns minutos para que o Eventarc faça o provisionamento completo e comece a aceitar eventos. Recomendamos aguardar alguns minutos antes de verificar o kit se ele for acionado por evento. Se você excluir a extensão imediatamente sem verificação, poderá haver um breve período de inatividade enquanto o provisionamento é concluído.

Para verificar se o firebase deploy do kit não teve erros, confira os registros de implantação para saber se algum hook de ciclo de vida foi acionado. Extensões populares, como Stream Cloud Firestore para BigQuery, usam hooks de ciclo de vida. Confira abaixo um exemplo de como um hook de ciclo de vida aparece quando é acionado:

i  functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔  functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/europe-west1/queues/kit-firestore-bigquery-export-initBigQuerySync.
i  functions: View logs for afterFirstDeploy at: https://console.cloud.google.com/logs/query;query=resource.type%3D%22cloud_run_revision%22%0Aresource.labels.service_name%3D%22kit-firestore-bigquery-export--initbigquerysync%22%0Aresource.labels.location%3D%22europe-west1%22;project=my-project

Essas mensagens de registro confirmam o seguinte:

• Um hook de ciclo de vida foi encontrado e executado.
• Uma tarefa foi enfileirada na fila de tarefas associada ao hook do ciclo de vida.
• Um link para o Cloud Logging foi fornecido para que você possa validar se a tarefa foi concluída sem erros.

Siga o link de registros até o console Google Cloud para validar se não há erros nos registros e se o evento da fila de tarefas foi processado corretamente. Se o evento de ciclo de vida não for executado corretamente, você poderá acioná-lo novamente executando:

firebase functions:lifecycle:run <hook-name> <codebase>

Se você estiver implantando uma instância do kit de funções pela primeira vez, execute:

firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>

Se, a qualquer momento durante a validação, você decidir interromper ou desfazer essa migração, desinstale o kit seguindo as instruções em Desinstalar a extensão.

5. Desinstalar a extensão

Depois de verificar o kit de funções implantado, desinstale a extensão para não duplicar o comportamento dela uma vez para o kit e outra para a extensão. É possível desinstalar todas as extensões da CLI Firebase independente de como elas foram instaladas se você transmitir a flag --immediate:

firebase ext:uninstall <extension-instance-id> --project <project-id> --immediate

Exemplo prático:

firebase ext:uninstall firestore-bigquery-export --project my-project --immediate

Saída:

i  extensions: uninstalling firestore-bigquery-export...
i  extensions: deleting extension instance resources in project my-project...
✔  extensions: successfully uninstalled firestore-bigquery-export

Migrações avançadas

Você pode ter extensões em vários projetos do Firebase que quer gerenciar com uma única base de código. Por exemplo, se você implantar a mesma infraestrutura em um ambiente testing e um ambiente production, cada um com uma instância documents Cloud Firestore que você exporta para BigQuery, é possível ter duas instâncias da extensão firestore-bigquery-export instaladas:

• export-documents-testing
• export-documents-production

Se você migrou essas duas instâncias de extensão para duas instâncias do kit de funções em uma única base de código ao trabalhar com a CLI Firebase e implantou usando firebase deploy --project testing e firebase deploy --project production, cada implantação criaria duas instâncias nos ambientes testing e production.

Em vez disso, substitua as duas instâncias de extensão por uma instância do kit de funções firestore-bigquery-export implantada em vários projetos, em que cada projeto tem a própria configuração. O diretório de configuração da instância deve ter esta aparência:

• config-export-documents/
  • .env.testing
  • .env.production

Cada implantação em testing e production cria uma instância do seu kit com a configuração correspondente. Os comandos da CLI atuais criam essa configuração desde que você transmita a flag --project em cada invocação de ext:migrate ou functions:kits:install.

Exemplo prático:

firebase functions:kits:install --package @firebase-function-kits/firestore-bigquery-export --project testing --no-configure --template migration

✔ What would you like to name this kit? firestore-bigquery-export
✔ What would you like to name this instance? export-documents
✔  Wrote function-kits/firestore-bigquery-export/source/package.json
✔  Wrote function-kits/firestore-bigquery-export/source/tsconfig.json
✔  Wrote function-kits/firestore-bigquery-export/source/.gitignore
✔  Wrote function-kits/firestore-bigquery-export/source/src/index.ts
i  functions: Running npm install
✔  Wrote configuration info to firebase.json
✔  functions: Function kit firestore-bigquery-export successfully installed.

# This creates the export-documents instance with an empty .env.testing file
# for the testing project. Now populate it via export:
firebase ext:export --mode functions --instance export-documents-testing \
  --kit-instance export-documents --project testing

# Repeat the export for production into the same kit instance to create
# .env.production from the export-documents-prod instance:
firebase ext:export --mode functions --instance export-documents-prod \
  --kit-instance export-documents --project production

Observação: parte da saída do console foi omitida para simplificar.

Agora você tem uma única instância do kit configurada para implantação nos projetos testing e production com as respectivas configurações. Se você criar uma instância no projeto testing e executar o comando functions:kits:install para o mesmo pacote no projeto production, vai aparecer a opção de reutilizar a instância configurada para testing ou instalar uma segunda instância.