Testar apps da Web localmente com o emulador do Firebase App Hosting

É possível realizar testes locais do app antes da implantação do App Hosting usando o emulador App Hosting, que faz parte do Pacote de emuladores locais do Firebase.

Antes de usar o emulador App Hosting, entenda o fluxo de trabalho geral do Local Emulator Suite do Firebase e instale e configure o Local Emulator Suite e revise os comandos da CLI.

Neste tópico, pressupomos que você já conhece o App Hosting. Se necessário, leia a introdução ao App Hosting e outros materiais para entender como o App Hosting funciona.

O que posso fazer com o emulador de App Hosting?

O emulador App Hosting permite testar e refinar seus aplicativos da Web localmente. Isso pode simplificar seu processo de desenvolvimento e melhorar a qualidade dos apps da Web criados com o Firebase e implantados no App Hosting.

O emulador App Hosting:

1. Permite executar o app da Web localmente, com variáveis de ambiente e segredos definidos em arquivos de configuração apphosting.yaml.
2. Pode substituir variáveis de ambiente e secrets para uso no emulador com o arquivo apphosting.emulator.yaml.
3. Pode ser usado com outros emuladores do Firebase. Se você estiver usando o Firestore, o Auth ou qualquer outro emulador, o Local Emulator Suite garante que esses emuladores sejam iniciados antes do emulador App Hosting.

Configurar o emulador

Para começar, instale e inicialize o Local Emulator Suite conforme descrito em Instalar, configurar e integrar o Pacote de emuladores locais. Além de outros emuladores do Firebase que você quer configurar, selecione App Hosting Emulator. A CLI solicita alguns valores do emulador App Hosting, incluindo:

• O diretório raiz do app em relação ao projeto. Isso é importante se você estiver usando monorepos com App Hosting.
• Se você quer substituir valores para o desenvolvimento local.
• Se você quer conceder acesso a segredos para desenvolvimento local aos membros da equipe.

firebase init emulators
=== Emulators Setup
? Which Firebase emulators do you want to set up? Press Space to select emulators, then Enter to confirm your choices. (Press
<space> to select, <a> to toggle all, <i> to invert selection, and <enter> to proceed)
❯◯ App Hosting Emulator
 ◯ Firestore Emulator
 ◯ Database Emulator
 ◯ Hosting Emulator
 ◯ Pub/Sub Emulator
 ◯ Storage Emulator
 ◯ Eventarc Emulator
(Move up and down to reveal more choices)

? Specify your app's root directory relative to your project (./)

? The App Hosting emulator uses a file called apphosting.emulator.yaml to
override values in apphosting.yaml for local testing. This codebase does not
have one, would you like to create it? (Y/n)

? Which environment variables would you like to override? (Press <space> to
select, <a> to toggle all, <i> to invert selection, and <enter> to proceed)
❯◯ MEMCACHE_ADDR
 ◯ API_KEY

? What new value would you like for plaintext MEMCACHE_ADDR?

? What would you like to name the secret reference for API_KEY? (test-api-key)

? What new value would you like for secret TESTKEY [input is hidden]? [input is hidden]

? Your config has secret values. Please provide a comma-separated list of users
or groups who should have access to secrets for local development:

✔  Successfully set IAM bindings on secret test-api-key.

Todos os valores fornecidos neste fluxo de configuração são usados para atualizar a configuração do emulador App Hosting em firebase.json. Também é possível configurar o emulador do App Hosting atualizando firebase.json diretamente. O esquema do emulador do App Hosting é:

{
  ...
  "emulators": {
    "apphosting": {
      "startCommand": <command> [optional]
      "rootDirectory": <path> [optional]
      }
    }
  }

• O startCommand é gerado e definido automaticamente quando o emulador é inicializado. Se não for fornecido, o emulador vai detectar e executar o comando de desenvolvimento do gerenciador de pacotes.
• rootDirectory é usado para oferecer suporte a configurações de projetos monorepo. Se o app da Web estiver em um subdiretório, você precisará fornecer o caminho desse diretório relativo à raiz (o local de firebase.json).

Gerenciar emulação

A inicialização do emulador cria um arquivo apphosting.emulator.yaml no diretório raiz do app. Esse arquivo de configuração tem o mesmo esquema do arquivo apphosting.yaml usado na produção, mas é destinado exclusivamente ao desenvolvimento local. Por padrão, o emulador lê a configuração do arquivo apphosting.yaml, mas se um arquivo apphosting.emulator.yaml estiver presente, as configurações nesse arquivo serão priorizadas e terão precedência.

O arquivo apphosting.emulator.yaml foi criado para ser seguro para confirmação e compartilhamento com colegas. Para garantir que você não cometa um erro e armazene dados sensíveis em repositórios de origem, qualquer variável de ambiente que seja um segredo em apphosting.yaml também precisa ser um segredo em apphosting.emulator.yaml. Se um secret não precisar mudar entre a produção e o desenvolvimento local (por exemplo, uma chave de API Gemini), ele não precisará ser adicionado a apphosting.emulator.yaml. Em vez disso, conceda à sua equipe acesso ao secret.

Se o aplicativo usar muitos segredos (por exemplo, chaves de API para três serviços diferentes, com valores diferentes para cada um de produção, ambiente de estágio e desenvolvimento local), você poderá exceder o nível sem custo financeiro do Cloud Secret Manager e pagar US$ 0,06 por segredo adicional por mês. Se você preferir gerenciar a configuração local fora do controle de origem para evitar essa taxa, use o arquivo apphosting.local.yaml legado. Ao contrário do apphosting.emulator.yaml, esse arquivo pode fornecer valores em texto simples para variáveis de ambiente que são valores secretos em apphosting.yaml.

Conceder acesso a segredos a usuários ou grupos

Os segredos armazenados em apphosting.emulator.yaml são lidos quando o emulador é iniciado. Isso significa que a equipe de desenvolvimento precisa ter acesso ao segredo. É possível usar o comando apphosting:secrets:grantaccess para conceder acesso a um segredo a um usuário ou grupo por e-mail.

firebase apphosting:secrets:grantaccess test-api-key --emails my-team@my-company.com

Quando aplicável, use chaves somente para teste em apphosting.emulator.yaml que não tenham acesso a dados de produção, não possam ter efeitos colaterais globais (envio de e-mails, cobrança de cartões de crédito) e/ou tenham cotas mais baixas. Isso ajuda a garantir que o código não revisado tenha menos consequências no mundo real.

Considere usar os Grupos do Google para gerenciar o acesso a secrets em vez de conceder acesso a usuários individuais. Isso simplifica a integração de novos membros à sua equipe de desenvolvedores, porque a adição deles ao grupo concede acesso a todos os segredos necessários. Talvez você já tenha um grupo adequado em que os desenvolvedores se comunicam. O controle de acesso pelos Grupos do Google também ajuda a garantir que os desenvolvedores que saem da equipe percam o acesso a todos os segredos quando são removidos do grupo de e-mails. Se o segredo tiver acesso a dados de produção ou efeitos colaterais reais, ainda será apropriado girar a chave e dar um novo valor a ela com firebase apphosting:secrets:set.

Executar o emulador

firebase emulators:start

Isso vai iniciar todos os emuladores definidos no arquivo firebase.json, incluindo o emulador App Hosting.