Práticas recomendadas pós-migração

Depois de migrar de Firebase Extensions para um kit de funções, você gerencia as instâncias do kit como Cloud Functions padrão de 2ª geração no seu projeto do Firebase. Neste guia, mostramos como instalar novos kits de funções diretamente do npm sem migrar uma extensão, atualizar parâmetros de kit e opções globais, fazer upgrade de versões de pacotes npm conforme os editores lançam atualizações e reverter uma migração, se necessário.

Como usar um kit de funções de um pacote npm sem migrar

Se você não estiver migrando de uma extensão, o uso de um kit de funções consiste em duas partes:

Como instalar o kit

Para instalar um kit de funções, use o seguinte comando da CLI:

firebase functions:kits:install --package <npm-package-name>

Exemplo prático:

firebase functions:kits:install --package @firebase-function-kits/firestore-bigquery-export --project my-project

✔ What would you like to name this kit? firestore-bigquery-export
✔ What would you like to name this instance? firestore-bigquery-export
i  function-kits/firestore-bigquery-export/source/package.json is unchanged
i  function-kits/firestore-bigquery-export/source/tsconfig.json is unchanged
i  function-kits/firestore-bigquery-export/source/.gitignore is unchanged
i  functions: Running npm install @firebase-function-kits/firestore-bigquery-export@next --save-prefix=^...
i  functions: Building TypeScript source...
✔  Wrote configuration info to firebase.json

i  functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project
Prompting for parameters for codebase firestore-bigquery-export:
✔ Enter a string value for FUNCTION_DEFAULT_REGION:
(Global default region where functions should be deployed. Can be overridden per-function.) us-east1

✔ Enter a string value for BigQuery Project ID:
(Override the default project for BigQuery instance. This can allow updates to be directed to a BigQuery
instance on another GCP project.) my-bigquery-project

✔ Enter a string value for Firestore Instance ID:
(The Firestore database to use. Use "(default)" for the default database. You can view your available
Firestore databases at https://console.cloud.google.com/firestore/databases.) eu-testing

# Omitting many more parameters for brevity

✔  Wrote configuration info to firebase.json
✔  functions: Function kit firestore-bigquery-export successfully installed.

i  functions: At the first deploy, the following functions will be created in your project:
- kit-firestore-bigquery-export-fsexportbigquery
- kit-firestore-bigquery-export-initBigQuerySync
- kit-firestore-bigquery-export-setupBigQuerySync
i  functions: At the first deploy, the following Task Queues will be created in your project:
- kit-firestore-bigquery-export-initBigQuerySync
- kit-firestore-bigquery-export-setupBigQuerySync
i  functions: At the first deploy, the following APIs will be enabled in your project:
- bigquery.googleapis.com
- cloudtasks.googleapis.com
i  functions: At the first deploy, the following roles will be granted to the kit service account:
- BigQuery Data Editor
- BigQuery User
- Cloud Datastore User
- Eventarc Event Receiver
- roles/run.invoker
⚠  functions: Please review the changes above. If you do not want them applied to your project, uninstall this kit before running firebase deploy.

Como mudar as opções globais padrão

Para configurar as opções globais da instância do kit, modifique o arquivo index.ts localizado em function-kits/<your-kit-id>/source/src/index.ts.

Se você quiser que os padrões sejam compartilhados em todas as instâncias do kit, defina-os diretamente em index.ts. Caso contrário, crie parâmetros definidos por instância, seguindo os exemplos e as instruções documentados em index.ts.

Como implantar o kit

Para implantar o kit de funções, execute:

firebase deploy --only functions:<kit-instance-id>

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!

A instalação e a implantação do kit realizam as seguintes ações:

  • Cria function-kits/firestore-bigquery-export/source, que contém a origem do kit, incluindo um arquivo index.ts básico que importa e exporta o pacote do kit ao configurar um parâmetro que permite escolher um local diferente para cada instância do kit.
  • Cria function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.<project-id> e o preenche com os dados de configuração inseridos para a função. Se atualizações futuras adicionarem novos parâmetros, você vai receber uma solicitação na próxima implantação.
  • Cria os recursos necessários do Google Cloud para executar esse kit, incluindo uma conta de serviço com papéis específicos do IAM, funções, gatilhos do Eventarc e filas de tarefas do Cloud Tasks.

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

Como desinstalar um kit

Para remover o kit e todas as instâncias dele, execute:

firebase functions:kits:uninstall --kit <kit-id>

Isso exclui todas as instâncias e as configurações delas e remove a origem do kit do disco.

Para remover apenas uma instância do kit, execute:

firebase functions:kits:uninstall --instance <kit-instance-id>

Se você tiver apenas uma instância do kit, isso vai desinstalar o kit inteiro.

Como atualizar a configuração de um kit

Durante a instalação ou a primeira implantação, você precisa configurar todos os parâmetros do kit, a menos que tenha migrado uma configuração de uma extensão. Esses parâmetros são armazenados no arquivo .env no diretório de configuração da instância do kit. Por exemplo, se você tiver uma instância de kit chamada firestore-bigquery-export no projeto my-project, o arquivo .env vai estar localizado em function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project.

Ele é semelhante a este:

DATASET_LOCATION=us
BIGQUERY_PROJECT_ID=my-project
DATABASE=eu-testing
DATABASE_REGION=eur3
COLLECTION_PATH=posts
WILDCARD_IDS=false
DATASET_ID=firestore_export
TABLE_ID=posts
TABLE_PARTITIONING=NONE
TIME_PARTITIONING_FIELD=
TIME_PARTITIONING_FIRESTORE_FIELD=
TIME_PARTITIONING_FIELD_TYPE=omit
CLUSTERING=
MAX_DISPATCHES_PER_SECOND=100
VIEW_TYPE=view
MAX_STALENESS=
REFRESH_INTERVAL_MINUTES=
BACKUP_COLLECTION=
TRANSFORM_FUNCTION=
USE_NEW_SNAPSHOT_QUERY_SYNTAX=no
EXCLUDE_OLD_DATA=no
KMS_KEY_NAME=
MAX_ENQUEUE_ATTEMPTS=3
LOG_LEVEL=info
FUNCTION_DEFAULT_REGION=us-west1

Se você souber o valor de configuração que quer mudar, edite-o diretamente no arquivo .env. Se você preferir usar o prompt interativo que é executado durante a instalação e a implantação, remova os parâmetros que quer alterar do arquivo .env e reimplante a instância do kit. Será solicitado que você insira esses parâmetros durante a implantação.

Por exemplo, se você excluir a linha COLLECTION_PATH=posts e implantar, será solicitado que você a insira durante a implantação:

i functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export-d9cd/.env.my-project
Prompting for parameters for codebase firestore-bigquery-export:

Collection path: What is the path of the collection that you would like to export? You may use {wildcard} notation to match a subcollection of all documents in a collection (for example: chatrooms/{chatid}/posts). Parent Firestore Document IDs from {wildcards} can be returned in path_params as a JSON formatted string.
? Enter a string value for Collection path: (posts)

Manutenção e upgrade de um kit de funções

Os editores podem atualizar os pacotes npm ao longo do tempo para corrigir bugs, adicionar recursos, atualizar dependências ou resolver vulnerabilidades de segurança. Recomendamos que você fique por dentro dessas versões e instale as atualizações, especialmente aquelas que corrigem vulnerabilidades de segurança.

O comando functions:kits:install cria uma base de código que instala um kit como um pacote npm e exporta todas as funções dele para cada instância do kit. Para fazer upgrade de um kit, atualize a versão do pacote e reimplante cada instância do kit para aplicar as mudanças.

Como determinar se um kit tem atualizações

Acesse o diretório source do kit em function-kits/<your-kit-id>/source. Nesse diretório source, execute o comando a seguir para receber um relatório sobre todos os pacotes npm desatualizados, incluindo o kit de funções e o SDK Cloud Functions:

npm outdated

Se você já usa uma ferramenta para identificar dependências que precisam ser atualizadas, como o Dependabot para GitHub, recomendamos integrar o diretório do kit a esse fluxo de trabalho.

Como atualizar um kit

Para atualizar o kit e as dependências dele para a versão mais recente sem alterações interruptivas (excluindo atualizações de versões principais que podem conter alterações interruptivas), execute:

npm update --save

Se você quiser atualizar apenas o pacote do kit de funções e nenhum outro, transmita o nome do pacote para npm update:

npm update <package-name> --save

Para fazer upgrade de um pacote para a versão principal mais recente (que pode introduzir alterações interruptivas), execute:

npm update --save <npm-package-name>@latest

Leia a documentação do pacote e as notas da versão para saber o que mudou e se você precisa seguir outras etapas antes ou depois da implantação para evitar alterações interruptivas.

Como implantar instâncias atualizadas

A execução de npm update atualiza apenas o código-fonte local. Para atualizar as funções em execução na nuvem, implante-as novamente. É possível reimplantar todas as funções no seu projeto, incluindo todos os kits de funções, executando:

firebase deploy --only functions

Como desfazer uma migração

Para desfazer uma migração, reinstale a extensão primeiro. Use o arquivo .env do kit para encontrar os valores de configuração necessários durante a instalação.

Depois que a extensão for implantada, desinstale a instância do kit (isso vai desinstalar o kit inteiro se for a última instância restante):

firebase functions:kits:uninstall --instance <kit-instance-id> --project <project-id>

Salvar configurações de extensão para uma migração futura

Após 31 de março de 2027, não será possível buscar uma configuração de extensão atual. Se não for possível migrar antes de 31 de março de 2027, recomendamos salvar sua extensão caso decida migrar após essa data.

  1. Receba uma lista dos IDs de instância da extensão:

    Use o comando da CLI ext:list para ver uma lista de todas as instâncias de extensão no seu projeto do Firebase:

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

    Exemplo prático:

    firebase ext:list --project my-project

    » firebase ext:list
i  extensions: ensuring 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.3   │ 2026-09-06 22:31:04 │ @firebase-function-kits/firestore-bigquery-export │
├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤
│ firebase/firestore-bigquery-export │ firebase  │ firestore-bigquery-export      │ ACTIVE │ 0.3.2   │ 2026-06-03 17:41:24 │ @firebase-function-kits/firestore-bigquery-export │
└────────────────────────────────────┴───────────┴────────────────────────────────┴────────┴─────────┴─────────────────────┴───────────────────────────────────────────────────┘
⚠ Notice: Firebase Extensions will shut down on March 31, 2027. Learn more: https://firebase.google.com/docs/extensions/faq-and-troubleshooting

    O comando ext:list também tem um formato de saída JSON. Se você tiver o utilitário jq instalado, poderá usá-lo para receber uma lista de todos os IDs de instância de um projeto:

    firebase ext:list --json --project <project-id> | jq -r '.result[].instanceId'

    Exemplo prático:

    firebase ext:list --json --project my-project | jq -r '.result[].instanceId'

    Saída:

    firestore-bigquery-export-zbrp
firestore-bigquery-export

  2. Exporte a configuração de cada instância:

    Para cada instância, é possível salvar a configuração no disco executando o seguinte comando de exportação:

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

    Exemplo prático:

    firebase ext:export --mode functions --project my-project --instance firestore-bigquery-export

    Saída:

    i  extensions: ensuring required API firebaseextensions.googleapis.com is enabled...
i  functions: Saving exported extensions config as a Function Kits .env file
i  functions: Created new local file firestore-bigquery-export/.env.testing to store param values. We suggest explicitly adding or excluding this file from version control.
i  functions: Loaded environment variables from firestore-bigquery-export/.env.testing
i  functions: Loaded environment variables from firestore-bigquery-export/.env.testing
i  functions: Writing new parameter values to disk: firestore-bigquery-export/.env.testing

    No disco, você vai encontrar uma exportação dessa instância de extensão em um local como <instance-id>/.env.<project-id>. Neste exemplo, ele está localizado em firestore-bigquery-export/.env.my-project.

    É possível repetir esse processo uma vez por instância, o que cria um conjunto de arquivos .env com todas as configurações de instância de extensão que podem ser reutilizadas posteriormente como parte de uma migração.

  3. Mova os arquivos .env exportados para um local melhor:

    Os arquivos .env exportados das suas extensões foram colocados diretamente no seu projeto do Firebase, mas não são necessários no dia a dia se você não migrou para os kits de funções. É possível movê-los do projeto para qualquer outro local de armazenamento apropriado até que você precise deles no futuro ou decida excluí-los.