Gerenciar configurações do projeto com o manifesto de extensões

Um manifesto de extensões é uma lista de instâncias de extensões e suas configurações. Com o manifesto, é possível realizar as seguintes ações:

  • Compartilhar a configuração de extensões com outras pessoas.
  • Copiar a configuração de extensões entre diferentes projetos, como a do projeto de preparo para o projeto de produção.
  • Implantar todas as extensões de uma só vez.
  • Teste como suas extensões funcionam com seu app usando a Firebase Local Emulator Suite
  • Confirmar a configuração de extensões no controle de origem.
  • Incluir extensões no pipeline de CI/CD.

Um manifesto de extensões tem duas partes:

  • A seção extensions do firebase.json, que é um mapa de ID de instâncias para a referência da versão da extensão. Por exemplo:

    {
 "extensions": {
   "my-bigquery-extension": "firebase/firestore-bigquery-export@^0.1.18",
   "my-image-resizer": "firebase/storage-resize-images@^0.1.22",
 }
}

  • Arquivos .env que contêm a configuração de cada uma das instâncias de extensões, no subdiretório extensions/ do diretório do projeto do Firebase. Por exemplo, uma instância de storage-resize-images pode ter um arquivo .env como este:

    IMAGE_TYPE=jpeg
LOCATION=us-central1
IMG_BUCKET=${param:PROJECT_ID}.appspot.com
IMG_SIZES=100x100
DELETE_ORIGINAL_FILE=false

Criar um manifesto de extensões

Há três maneiras de criar um manifesto de extensões:

  • Gerenciar seu manifesto de extensões com a CLI do Firebase
  • Exportar a configuração de extensões de um projeto
  • Editar os arquivos de manifesto manualmente

Os dois primeiros métodos são explicados abaixo.

Gerenciar seu manifesto de extensões com a CLI do Firebase

É possível executar a maioria dos comandos ext: da CLI do Firebase com a opção --local para atualizar o manifesto de extensões sem realmente mudar a configuração atual do projeto.

Por exemplo:

firebase ext:install --local firebase/firestore-bigquery-export

Com a execução do comando acima, você vai precisar configurar a versão mais recente da extensão firebase/firestore-bigquery-export e salvar a configuração no manifesto, mas a execução não implantará a configuração no projeto.

Veja mais alguns exemplos de comandos que modificam o manifesto de extensões:

# ext:configure changes the params for an extension instance in your extensions manifest
$ firebase ext:configure my-bigquery-extension --local

# ext:update --local updates an instance in your extensions manifest
# to the latest version of that extension
$ firebase ext:update my-bigquery-extension --local

# You can also specify a version if you don't want to update to the latest version
$ firebase ext:update my-bigquery-extension firebase/firestore-bigquery-export@0.1.10 --local 

# ext:uninstall --local removes an instance from your extensions manifest
$ firebase ext:uninstall my-bigquery-extension --local

Exportar a configuração de extensões de um projeto

Para salvar a configuração de extensões atual de um projeto no manifesto, faça as seguintes ações:

  1. Configure a CLI do Firebase caso ainda não tenha feito isso.
  2. Em um prompt do shell, mude para o diretório do projeto. O diretório do projeto contém o arquivo firebase.json.
  3. Execute o comando ext:export: 
    firebase ext:export

O comando ext:export adicionará uma seção extensions ao arquivo firebase.json. Além disso, o comando ext:export cria um diretório extensions que contém um arquivo .env para cada instância de extensão instalada. Esses arquivos contêm os parâmetros de configuração de cada instância.

Testar uma configuração de extensões com o Firebase Local Emulator Suite

Depois de adicionar algumas instâncias de extensão ao manifesto, teste-as usando o Local Emulator Suite.

  1. Instale e configure o Local Emulator Suite.

  2. Comece o Local Emulator Suite:

    • Para executar o Pacote de emuladores de maneira interativa, execute: firebase emulators:start
    • Para executar o pacote de emuladores e um script de teste, use: firebase emulators:exec my-test.sh

Agora, se você tiver instâncias de extensão listadas no manifesto, o Local Emulator Suite fará o download do código-fonte dessas extensões para ~/.cache/firebase/extensions. Após o download, o Local Emulator Suite será iniciado e você poderá acionar qualquer uma das funções acionadas por extensões em segundo plano e conectar seu app ao Pacote de emuladores para testar a integração com seu app.

Implantar uma configuração de extensões em um projeto

Depois de adicionar algumas instâncias de extensão ao manifesto, implante-a em um projeto usando a CLI do Firebase. Ao implantar usando um manifesto de extensões, você instala, atualiza e configura todas as instâncias de extensão no manifesto de uma só vez em um projeto.

Para implantar um manifesto de extensões, siga as etapas a seguir:

  1. Em um prompt do shell, mude para o diretório que contém a configuração de extensões salva, ou seja, o diretório que contém firebase.json. Se você acabou de executar ext:export, já está no diretório certo.
  2. Execute o comando deploy. Se você quer implantar as extensões em um projeto diferente do atual, especifique também --project=: 
    firebase deploy --only extensions –-project=YOUR_PROJECT_ID

O comando deploy validará cada configuração de instância, perguntará se você quer excluir todas as instâncias da extensão do projeto de destino que não estão listadas em firebase.json e, em seguida, implantará todas as instâncias de extensão.

Configurações de extensões específicas do projeto

As configurações de extensões salvas podem ser usadas para implantação em vários projetos diferentes, como em um projeto de preparo e outro de produção. Ao fazer isso, alguns valores de parâmetro podem precisar ser diferentes para cada projeto. Os arquivos .env específicos do projeto tornam isso possível.

  • Coloque valores de parâmetro que diferem entre projetos em extensions/EXTENSION_INSTANCE_ID.env.YOUR_PROJECT_ID.
  • Coloque os valores de parâmetros compartilhados em extensions/EXTENSION_INSTANCE_ID.env.

Às vezes, você pode querer usar um valor de parâmetro diferente para emular suas extensões. Por exemplo, talvez você queira fornecer uma chave de API de teste, em vez de uma chave de produção. Coloque esses parâmetros em um arquivo .local:

  • Coloque parâmetros não secretos que você quer usar durante a emulação em extensions/EXTENSION_INSTANCE_ID.env.local.
  • Coloque valores de parâmetro secretos em extensions/EXTENSION_INSTANCE_ID.secret.local