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 sua configuração de extensões com outras pessoas
  • Copie sua configuração de extensões entre projetos diferentes (como do projeto de teste para o projeto de produção)
  • Implante todas as suas extensões de uma vez
  • Teste como suas extensões funcionam com seu aplicativo usando o Firebase Local Emulator Suite
  • Confirme a configuração de suas extensões no controle do código-fonte
  • Incluir extensões em seu pipeline de CI/CD

Um manifesto de extensões tem duas partes:

  • A seção de 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",
     }
    }
    
  • .env contendo a configuração de cada uma de suas instâncias de extensão, no subdiretório extensions/ do diretório de 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

Criar um manifesto de extensões

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

  • Gerencie seu manifesto de extensões com a Firebase CLI
  • 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 Firebase CLI

Você pode executar a maioria dos comandos ext: da 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 de extensões atual de um projeto no manifesto, faça o seguinte:

  1. Caso ainda não tenha feito isso, configure a Firebase CLI
  2. A partir de um prompt de 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 de extensions ao arquivo firebase.json . Além disso, o comando ext:export cria um diretório de extensions contendo um arquivo .env para cada instância de extensão que você instalou. Esses arquivos contêm os parâmetros de configuração para 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ê pode testá-las usando o Local Emulator Suite.

  1. Instale e configure o Local Emulator Suite .

  2. Inicie o pacote de emulador local :

    • 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á o download do código-fonte dessas extensões para ~/.cache/firebase/extensions . Depois de baixados, o Local Emulator Suite será iniciado e você poderá acionar qualquer uma das funções acionadas em segundo plano das extensões e conectar seu aplicativo ao Emulator Suite 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ê pode implantá-lo em um projeto usando a Firebase CLI. 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. A partir de um prompt de 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 certo.)
  2. Execute o comando deploy . Se você deseja implantar as extensões em um projeto diferente do atual, especifique também --project --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 implantar em vários projetos diferentes: por exemplo, um projeto de teste e um projeto de produção. Ao fazer isso, alguns valores de parâmetro podem precisar ser diferentes para cada projeto. 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 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 de produção. Coloque estes parâmetros em um arquivo .local :

  • Coloque 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