Material de consulta sobre a CLI do Firebase

A CLI do Firebase (GitHub) oferece várias ferramentas de gerenciamento, visualização e implantação para projetos do Firebase.

Antes de usar a CLI do Firebase, configure um projeto do Firebase.

Configurar ou atualizar a CLI

Instalar a CLI Firebase

É possível instalar a CLI do Firebase usando um método compatível com seu sistema operacional, nível de experiência e/ou caso de uso. Seja qual for o modo de instalação da CLI, você terá acesso às mesmas funcionalidades e ao comando firebase.

Windows macOS Linux

Windows

É possível instalar a CLI do Firebase para Windows com uma das seguintes opções:

macOS ou Linux

É possível instalar a CLI do Firebase para macOS ou Linux usando uma das seguintes opções:

Fazer login e testar a CLI do Firebase

Depois de instalar a CLI, será preciso fazer a autenticação. Em seguida, liste seus projetos do Firebase para confirmar a autenticação.

1. Faça login no Firebase com sua Conta do Google executando o seguinte comando:

   firebase login

   Esse comando conecta sua máquina local ao Firebase e concede acesso aos projetos do Firebase.

2. Para testar se a CLI está instalada corretamente e acessando sua conta, liste seus projetos do Firebase. Execute este comando:

   firebase projects:list

   A lista exibida precisa conter os mesmos projetos do Firebase exibidos no Console do Firebase.

Atualizar para a versão mais recente da CLI

Geralmente, você quer usar a versão mais atualizada da CLI do Firebase.

O método de atualização da versão da CLI depende do seu sistema operacional e da maneira que você a instalou.

Usar a CLI com sistemas de CI

A CLI do Firebase requer um navegador para concluir a autenticação, mas ela é totalmente compatível com CI e outros ambientes sem interface gráfica.

1. Em uma máquina com navegador, instale a CLI do Firebase.

2. Execute o seguinte comando para iniciar o processo de login:

   firebase login:ci

3. Acesse o URL fornecido e faça login usando uma Conta do Google.

4. Gere um novo token de atualização. A sessão atual da CLI não será afetada.

5. Armazene o token de saída de uma maneira segura, mas acessível, no sistema de CI.

6. Use esse token ao executar comandos do firebase. É possível escolher qualquer uma destas duas opções:

   • Opção 1: armazene o token como a variável de ambiente FIREBASE_TOKEN. Seu sistema usará o token automaticamente.

   • Opção 2: execute todos os comandos do firebase com a sinalização --token TOKEN no seu sistema de CI.
     Esta é a ordem de precedência para o carregamento do token: sinalização, variável de ambiente e projeto do Firebase desejado.

Inicializar um projeto do Firebase

A realização de várias tarefas comuns com a CLI, como a implantação em um projeto do Firebase, exige um diretório de projeto. Ele é criado usando o comando firebase init. Normalmente, um diretório de projeto é o mesmo diretório da raiz de controle de origem que, depois de executar o comando firebase init, incluirá um arquivo de configuração firebase.json.

Para inicializar um novo projeto do Firebase, execute o seguinte comando no diretório do seu aplicativo:

firebase init

O comando firebase init guia você pelas etapas de configuração do diretório do seu projeto e de alguns produtos do Firebase. Durante a inicialização do projeto, a CLI do Firebase solicita que você faça o seguinte:

• Selecione os produtos do Firebase que você quer configurar no seu projeto do Firebase.

  Essa etapa auxilia na definição de configurações de arquivos específicos dos produtos selecionados. Para mais detalhes sobre essas configurações, consulte a documentação do produto específico, como a do Hosting. Lembre-se de que é possível executar o comando firebase init mais tarde para configurar outros produtos do Firebase.

• Selecione um projeto padrão do Firebase.

  Essa etapa associa o diretório do projeto atual a um projeto do Firebase para que os comandos específicos dele, como firebase deploy, sejam executados no projeto apropriado do Firebase.

  Também é possível associar vários projetos do Firebase (como um de preparo e um de produção) ao mesmo diretório de projetos.

Ao final da inicialização, o Firebase cria automaticamente os dois arquivos a seguir na raiz do diretório local do app:

• Um arquivo de configuração firebase.json que exibe a configuração do seu projeto.

• Um arquivo .firebaserc que armazena aliases do seu projeto.

Arquivo firebase.json

O comando firebase init cria um arquivo de configuração firebase.json na raiz do diretório do seu projeto.

O arquivo firebase.json é necessário para implantar recursos com a CLI do Firebase porque ela especifica quais arquivos e configurações do diretório são implantados no projeto do Firebase. Como algumas configurações podem ser definidas tanto no diretório de projeto como no console do Firebase, resolva quaisquer conflitos de implantação possíveis.

É possível configurar a maioria das opções de Firebase Hosting diretamente no arquivo firebase.json. Porém, no caso de outros serviços que podem ser implantados com a CLI do Firebase, o comando firebase init cria arquivos específicos em que é possível definir configurações para esses serviços, como um arquivo index.js para o Cloud Functions. Também é possível configurar hooks de pré ou pós-implantação no arquivo firebase.json.

Confira abaixo um exemplo de arquivo firebase.json com as configurações padrão que serão aplicadas se você selecionar Firebase Hosting, Cloud Firestore e Cloud Functions for Firebase (com as opções de origem e lint do TypeScript selecionadas) durante a inicialização.

{
  "hosting": {
    "public": "public",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ]
  },
  "firestore": {
      "rules": "firestore.rules",
      "indexes": "firestore.indexes.json"
  },
  "functions": {
    "predeploy": [
      "npm --prefix \"$RESOURCE_DIR\" run lint",
      "npm --prefix \"$RESOURCE_DIR\" run build"
    ]
  }
}

Enquanto firebase.json é usado por padrão, é possível transmitir a sinalização --config PATH para especificar um arquivo de configuração alternativo.

Configuração para vários bancos de dados Cloud Firestore

Quando você executar firebase init, o arquivo firebase.json conterá uma única chave firestore correspondente ao banco de dados padrão do projeto, conforme mostrado acima.

Se o projeto contiver vários bancos de dados Cloud Firestore, edite o arquivo firebase.json para associar diferentes Cloud Firestore Security Rules e arquivos de origem do índice do banco de dados a cada banco de dados. Modifique o arquivo com uma matriz JSON, com uma entrada para cada banco de dados.

      "firestore": [
        {
          "database": "(default)",
          "rules": "firestore.default.rules",
          "indexes": "firestore.default.indexes.json"
        },
        {
          "database": "ecommerce",
          "rules": "firestore.ecommerce.rules",
          "indexes": "firestore.ecommerce.indexes.json"
        }
      ],

Arquivos Cloud Functions a serem ignorados na implantação

No momento da implantação da função, a CLI define automaticamente uma lista de arquivos no diretório functions que vão ser ignorados. Isso impede que a implantação use os arquivos de back-end irrelevantes que aumentariam o tamanho dos dados da implantação.

Veja a lista de arquivos ignorados por padrão no formato JSON:

"ignore": [
  ".git",
  ".runtimeconfig.json",
  "firebase-debug.log",
  "firebase-debug.*.log",
  "node_modules"
]

Se você adicionar seus próprios valores personalizados para ignore em firebase.json, mantenha a lista de arquivos mostrados acima (ou adicione se estiver faltando).

Gerenciar aliases de projeto

É possível associar diversos projetos do Firebase ao mesmo diretório do projeto. Você pode usar um projeto para preparo e outro para produção, por exemplo. Ao usar diferentes ambientes de projeto, é possível confirmar as alterações antes de implantá-las na produção. Com o comando firebase use, dá para alternar os aliases e criar novos.

Adicionar um alias de projeto

Quando você seleciona um projeto do Firebase durante a inicialização do projeto, o alias de default é atribuído automaticamente ao projeto. No entanto, para permitir que comandos específicos do projeto sejam executados em outro projeto do Firebase, e ainda poder usar o mesmo diretório do projeto, execute o seguinte comando no diretório do projeto:

firebase use --add

Esse comando solicita que você selecione outro projeto do Firebase e o atribua como alias. As atribuições de aliases são gravadas em um arquivo .firebaserc dentro do diretório do projeto.

Usar aliases de projeto

Para usar aliases atribuídos de projetos do Firebase, execute qualquer um dos seguintes comandos no diretório do projeto:

É possível modificar o que está sendo usado como o projeto ativo atual ao transmitir a sinalização --project com um comando da CLI. Veja um exemplo: dá para configurar a CLI para ser executada em um projeto do Firebase em que o alias de staging foi atribuído. Se quiser executar apenas um comando no projeto do Firebase em que o alias de prod foi atribuído, você pode executar firebase deploy --project=prod, por exemplo.

Controle de origem e aliases do projeto

De modo geral, é necessário incluir o arquivo .firebaserc no controle de origem para que sua equipe possa compartilhar aliases do projeto. Normalmente, no entanto, não é necessário incluir o arquivo .firebaserc para projetos de código aberto ou modelos iniciais.

Caso você tenha um projeto de desenvolvimento somente para uso pessoal, transmita a sinalização --project a cada comando ou execute firebase use PROJECT_ID sem atribuir um alias para o projeto do Firebase.

Disponibilizar e testar seu projeto do Firebase localmente

Veja e teste seu projeto do Firebase em URLs hospedados localmente antes de implantá-lo na produção. Se você quiser testar somente determinados recursos, use uma lista separada por vírgulas em uma sinalização no comando firebase serve.

Execute o comando a seguir na raiz do diretório local do seu projeto se quiser realizar alguma destas tarefas:

• Visualizar o conteúdo estático do seu app hospedado no Firebase.
• Usar Cloud Functions para gerar conteúdo dinâmico para Firebase Hosting e usar suas funções HTTP de produção (implantadas) para emular Hosting em um URL local.

firebase serve --only hosting

Emular seu projeto usando as funções HTTP locais

Execute qualquer um dos seguintes comandos no diretório do seu projeto para emular esse projeto usando funções HTTP locais:

• Para emular funções HTTP e hospedagem para testes em URLs locais, use um dos comandos a seguir:

  firebase serve

  firebase serve --only functions,hosting // uses a flag

• Para emular somente funções HTTP, use o seguinte comando:

  firebase serve --only functions

Testar usando outros dispositivos locais

Por padrão, firebase serve apenas responde às solicitações de localhost. Isso significa que você poderá acessar seu conteúdo hospedado na Web a partir do navegador no seu computador, mas não em outros dispositivos na rede. Se quiser testar usando outros dispositivos locais, use a sinalização --host, como:

firebase serve --host 0.0.0.0  // accepts requests to any host

Implantar em um projeto do Firebase

Com a CLI do Firebase, você gerencia a implantação de código e recursos no projeto do Firebase, incluindo:

• Lançamentos de sites Firebase Hosting
• Cloud Functions for Firebase novo, atualizado ou existente
• Esquemas e conectores novos ou atualizados para Firebase Data Connect
• Regras de Firebase Realtime Database
• Regras de Cloud Storage for Firebase
• Regras de Cloud Firestore
• Índices de Cloud Firestore

Para implantar em um projeto do Firebase, execute o seguinte comando no diretório do seu projeto:

firebase deploy

Como alternativa, é possível adicionar um comentário a cada uma das implantações. Ele será exibido com as outras informações de implantação na página do Firebase Hosting do seu projeto. Por exemplo:

firebase deploy -m "Deploying the best new feature ever."

Ao usar o comando firebase deploy, esteja ciente do seguinte:

• Para implantar recursos a partir de um diretório de projeto, é necessário que ele tenha um arquivo firebase.json. Esse arquivo é criado automaticamente com o comando firebase init.

• Por padrão, firebase deploy cria uma versão para todos os recursos implantáveis no diretório do projeto. Para implantar serviços ou recursos específicos do Firebase, use a implantação parcial.

Conflitos de implantação nas regras de segurança

Para Firebase Realtime Database, Cloud Storage for Firebase e Cloud Firestore, é possível definir regras de segurança no diretório de projeto local ou no console Firebase.

Outra opção para evitar conflitos de implantação é usar a implantação parcial e definir regras apenas no Console do Firebase.

Cotas de implantação

É possível, embora improvável, que você exceda uma cota que limita a taxa ou o volume das operações de implantação do Firebase. Ao implantar muitas funções, por exemplo, talvez você receba uma mensagem de erro HTTP 429 Quota. Para resolver esses problemas, use a implantação parcial.

Reverter uma implantação

É possível reverter uma implantação do Firebase Hosting na página Firebase Hosting do seu projeto selecionando a ação Reverter para a versão desejada.

No momento, não é possível reverter versões de regras de segurança para Firebase Realtime Database, Cloud Storage for Firebase ou Cloud Firestore.

Implantar serviços específicos do Firebase

Se você quiser implantar apenas serviços ou recursos específicos do Firebase, use uma lista separada por vírgulas em uma sinalização no comando firebase deploy. Por exemplo, o comando a seguir implanta o conteúdo Firebase Hosting e as regras de segurança Cloud Storage.

firebase deploy --only hosting,storage

A tabela a seguir exibe os serviços e recursos disponíveis para implantação parcial. Os nomes nas sinalizações correspondem às chaves no seu arquivo de configuração firebase.json.

Implantar funções específicas

É possível visar funções específicas ao fazer a implantação. Por exemplo:

firebase deploy --only functions:function1

firebase deploy --only functions:function1,functions:function2

Outra opção é juntar funções em grupos de exportação no arquivo /functions/index.js. Assim, dá para implantar várias funções usando um único comando.

Por exemplo, é possível gravar as seguintes funções para definir um groupA e um groupB:

var functions = require('firebase-functions/v1');

exports.groupA = {
  function1: functions.https.onRequest(...),
  function2: functions.database.ref('\path').onWrite(...)
}
exports.groupB = require('./groupB');

Neste exemplo, um arquivo functions/groupB.js separado contém funções adicionais que definem especificamente as funções no groupB. Por exemplo:

var functions = require('firebase-functions/v1');

exports.function3 = functions.storage.object().onChange(...);
exports.function4 = functions.analytics.event('in_app_purchase').onLog(...);

Neste exemplo, é possível implantar todas as funções groupA ao executar o seguinte comando no diretório do projeto:

firebase deploy --only functions:groupA

Ou você pode direcionar uma função específica dentro de um grupo. Para isso, execute o seguinte comando:

firebase deploy --only functions:groupA.function1,groupB.function4

Excluir funções

A CLI do Firebase é compatível com os comandos e opções a seguir para excluir funções implantadas anteriormente:

• Exclui todas as funções que correspondem ao nome especificado em todas as regiões:

  firebase functions:delete FUNCTION-1_NAME

• Exclui uma função especificada executada em uma região que não seja padrão:

  firebase functions:delete FUNCTION-1_NAME --region REGION_NAME

• Exclui mais de uma função:

  firebase functions:delete FUNCTION-1_NAME FUNCTION-2_NAME

• Exclui um grupo de funções especificado:

  firebase functions:delete GROUP_NAME

• Ignora o prompt de confirmação:

  firebase functions:delete FUNCTION-1_NAME --force

Configurar tarefas de pré e pós-implantação com script

É possível conectar scripts de shell ao comando firebase deploy para desempenhar tarefas de pré ou pós-implantação. Por exemplo, um script de pré-implantação poderia transcompilar o código TypeScript em JavaScript, e um hook de pós-implantação poderia notificar os administradores sobre o novo conteúdo do site implantado no Firebase Hosting.

Para configurar hooks de pré ou pós-implantação, adicione scripts bash no arquivo de configuração firebase.json. É possível definir scripts curtos diretamente no arquivo firebase.json ou usar outros arquivos que estão no diretório do projeto.

Por exemplo, o script a seguir é a expressão firebase.json para uma tarefa de pós-implantação que envia uma mensagem do Slack após uma implantação bem-sucedida no Firebase Hosting.

"hosting": {
  // ...

  "postdeploy": "./messageSlack.sh 'Just deployed to Firebase Hosting'",
  "public": "public"
}

O arquivo de script messageSlack.sh fica no diretório do projeto e tem esta aparência:

curl -X POST -H 'Content-type: application/json' --data '{"text":"$1"}'
     \https://SLACK_WEBHOOK_URL

É possível configurar hooks de predeploy e postdeploy para qualquer um dos recursos a serem implantados. Observe que executar o comando firebase deploy funciona como gatilho para todas as tarefas de pré e pós-implantação definidas no arquivo firebase.json. Para executar somente aquelas associadas a um serviço específico do Firebase, use comandos de implantação parcial.

Os hooks predeploy e postdeploy imprimem a resposta padrão e os streams de erro dos scripts no terminal. Em casos de falha, observe o seguinte:

• Se um hook de pré-implantação não for concluído conforme o esperado, a implantação será cancelada.
• Se ocorrer falhas na implantação por qualquer motivo, os hooks de pós-implantação não serão acionados.

Variáveis de ambiente

As variáveis de ambiente a seguir estão disponíveis nos scripts em execução nos hooks de pré e pós-implantação:

• $GCLOUD_PROJECT: a ID do projeto ativo.
• $PROJECT_DIR: o diretório raiz que contém o arquivo firebase.json.
• $RESOURCE_DIR: (somente para scripts hosting e functions). O local do diretório que contém os recursos Hosting ou Cloud Functions a serem implantados.

Gerenciar várias instâncias Realtime Database

Um projeto do Firebase pode ter várias instâncias Firebase Realtime Database. Por padrão, os comandos da CLI interagem com a instância padrão do banco de dados.

No entanto, é possível interagir com uma instância de banco de dados que não seja padrão usando a sinalização --instance DATABASE_NAME. Os comandos a seguir aceitam a sinalização --instance:

• firebase database:get
• firebase database:profile
• firebase database:push
• firebase database:remove
• firebase database:set
• firebase database:update

Referência de comandos

Comandos administrativos da CLI

Comandos de gerenciamento de projetos

Implantação e desenvolvimento local

Com esses comandos, você faz a implantação e interage com o site Firebase Hosting.

App Distribution commands

App Hosting commands

Comandos de gerenciamento de usuários Authentication

Cloud Firestore commands

Cloud Functions for Firebase commands

Para mais informações, consulte a documentação de configuração do ambiente.

Crashlytics commands

Data Connect commands

Esses comandos e os casos de uso deles são abordados em mais detalhes no guia de referência da CLI Data Connect.

Extensions commands

Comandos do editor Extensions

Hosting commands

Realtime Database commands

É possível criar sua instância inicial padrão do Realtime Database no console Firebase ou usando o fluxo de trabalho geral firebase init ou o fluxo firebase init database específico.

Depois de criar as instâncias, é possível gerenciá-las conforme discutido em Gerenciar várias instâncias do Realtime Database.

Remote Config commands