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
dofirebase.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órioextensions/
do diretório do projeto do Firebase. Por exemplo, uma instância destorage-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:
- Configure a CLI do Firebase caso ainda não tenha feito isso.
- Em um prompt do shell, mude para o diretório do projeto. O diretório do projeto
contém o arquivo
firebase.json
. - 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.
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
- Para executar o Pacote de emuladores de maneira interativa, execute:
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:
- 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 executarext:export
, já está no diretório certo. - 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