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

Um manifesto de extensões é uma lista de instâncias de extensão e suas configurações. Com o manifesto, você pode:

  • Compartilhe a configuração de suas extensões com outras pessoas
  • Copie a configuração das extensões entre projetos diferentes (como do projeto de teste para o projeto de produção)
  • Implante todas as suas extensões de uma só vez
  • Teste como suas extensões funcionam com seu aplicativo usando o Firebase Local Emulator Suite
  • Confirme a configuração de suas extensões para o controle de origem
  • Incluir extensões em seu pipeline de CI/CD

Um manifesto de extensões tem duas partes:

  • A seção extensions do seu firebase.json , que é um mapa do ID da instância 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ão, 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 o seguinte:

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

Crie um manifesto de extensões

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

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

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

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

Você pode executar a maioria dos comandos ext: do Firebase CLI com a opção --local para atualizar o manifesto de extensões sem realmente alterar a configuração atual do projeto.

Por exemplo:

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

A execução do comando acima solicitará que você configure a versão mais recente da extensão firebase/firestore-bigquery-export e salve a configuração no manifesto, mas não implantará a configuração em seu projeto.

Aqui estão 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 atual das extensões de um projeto no manifesto, faça o seguinte:

  1. Se ainda não tiver feito isso, configure a CLI do Firebase
  2. Em um prompt do shell, mude para o diretório do projeto. (O diretório do seu 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 contendo 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.

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

Depois de adicionar algumas instâncias de extensão ao manifesto de extensões, você poderá testá-las usando o Local Emulator Suite.

  1. Instale e configure o conjunto de emuladores locais .

  2. Inicie o conjunto de emuladores locais :

    • Para executar o Emulator Suite interativamente, execute: firebase emulators:start
    • Para executar o Emulator Suite e executar um script de teste, execute: firebase emulators:exec my-test.sh

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

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

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

Para implantar um manifesto de extensões:

  1. Em um prompt do shell, mude para o diretório que contém a configuração das extensões salvas. (Este é o diretório que contém firebase.json . Se você acabou de executar ext:export , já está no diretório correto.)
  2. Execute o comando deploy . Se você deseja 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ê deseja excluir quaisquer instâncias de extensão do projeto de destino que não estejam listadas em firebase.json e, em seguida, implantará todas as suas instâncias de extensão.

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

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

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

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

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