Referência da Firebase CLI

A Firebase CLI (GitHub) oferece uma série de ferramentas de gerenciamento, visualização e implantação para projetos do Firebase.

Configurar

Antes de poder instalar a Firebase CLI, você precisará instalar o Node.js na sua máquina. Depois disso, use o NPM (o gerenciador de pacotes do Node) para instalar a CLI executando este comando:

npm install -g firebase-tools

Agora você tem um comando "firebase" global que pode ser executado em qualquer janela de terminal da sua máquina. Depois de instalar a Firebase CLI, faça login usando sua conta do Google:

firebase login

Com esse comando, você conecta a máquina local à sua conta do Firebase e tem acesso aos seus projetos. Para testar se a autenticação funcionou, execute firebase list para ver uma lista de todos os seus projetos. Ela precisa conter os mesmos projetos que aparecem no Console do Firebase.

Como ter a versão mais recente

Para verificar se a Firebase CLI está atualizada, execute novamente o comando de instalação:

npm install -g firebase-tools

Inicializar um projeto do Firebase

Para realizar várias tarefas comuns com a CLI, como implantação em um projeto do Firebase, é necessário um diretório de projeto. Para estabelecer um, use o comando firebase init. Geralmente, um diretório de projeto é o mesmo diretório da raiz de controle de origem. No entanto, depois de executar o firebase init, ele conterá 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 a configuração do diretório do seu projeto, incluindo a solicitação de seleção dos serviços escolhidos do Firebase e a configuração de arquivos específicos para os serviços selecionados. Se você quiser adicionar outros serviços do Firebase posteriormente, basta executar o comando firebase init novamente.

Durante o processo de inicialização, você também precisa escolher 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 teste e um de produção) ao mesmo diretório de 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 Firebase CLI, porque ele especifica quais configurações e arquivos do diretório do projeto são implantados no projeto do Firebase. Como algumas configurações podem ser definidas no diretório de projeto ou no Console do Firebase, resolva quaisquer conflitos de implantação em potencial.

É possível configurar a maioria das opções do Firebase Hosting diretamente no arquivo firebase.json. No entanto, no caso de outros serviços do Firebase que podem ser implantados com a Firebase CLI, o comando firebase init cria arquivos específicos em que você pode definir as configurações desses 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.

Veja abaixo um arquivo firebase.json de exemplo com as configurações padrão que serão aplicadas se você selecionar o Firebase Hosting, o Cloud Firestore e o Cloud Functions para Firebase 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"
    ]
  }
}

Disponibilizar e testar seu projeto do Firebase localmente

Você pode ver e testar 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 um sinalizador no comando firebase serve.

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 comando a seguir:

    firebase serve --only functions

Execute o seguinte comando no diretório do seu projeto caso você queira:

firebase serve --only hosting

Implantar em um projeto do Firebase

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

  • novas versões dos sites do Firebase Hosting;
  • Cloud Functions para Firebase novo, existente ou atualizado;
  • regras do Firebase Realtime Database;
  • regras do Cloud Storage para Firebase;
  • regras do Cloud Firestore;
  • índices do Cloud Firestore.

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

firebase deploy

Por padrão, o comando 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.

Para implantar recursos em um diretório do projeto, ele precisa ter um arquivo firebase.json. Esse arquivo foi criado automaticamente para você pelo comando firebase init.

Como alternativa, você pode adicionar um comentário a cada uma das suas implantações. Esse comentário será exibido com as outras informações de implantação na página do Firebase Hosting do seu projeto. Exemplo:

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

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

Para o Firebase Realtime Database, o Cloud Storage para Firebase e o Cloud Firestore, você pode definir regras de segurança no diretório de projeto local ou no Console do 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 suas operações de implantação do Firebase. Por exemplo, ao implantar muitas funções, você pode receber uma mensagem de erro HTTP 429 Quota. Resolva esses problemas usando a implantação parcial ou por meio da solicitação do aumento de cota para serviços específicos do Firebase. Por exemplo, a cota chamada Solicitações de gravação a cada cem segundos por usuário pode resolver o erro 429 do Cloud Functions citado acima.

Reverter uma implantação

Você pode fazer rollback de uma implantação na página do Firebase Hosting do seu projeto. Para isso, selecione a ação Fazer rollback na versão escolhida. No momento, não é possível reverter versões de regras de segurança para o Firebase Realtime Database, o Cloud Storage para Firebase ou o 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 do Firebase Hosting e as regras de segurança do Cloud Storage.

firebase deploy --only hosting,storage

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

Sintaxe de sinalização Serviço ou recurso implantado
--only hosting conteúdo do Firebase Hosting
--only database regras do Firebase Realtime Database
--only storage regras do Cloud Storage para Firebase
--only firestore regras e índices do Cloud Firestore
--only firestore:rules regras do Cloud Firestore
--only firestore:indexes índices Cloud Firestore
--only functions Cloud Functions para Firebase (é possível haver versões mais específicas dessa sinalização)

Implantar funções específicas

Você pode segmentar funções específicas ao fazer a implantação. 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 seu arquivo /functions/index.js. Com isso, você pode implantar várias funções usando um único comando.

Por exemplo, você pode gravar as seguintes funções para definir um groupA e um groupB:

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

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 outras funções que definem especificamente as funções em groupB:

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

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

Neste exemplo, você pode implantar todas as funções groupA executando o seguinte comando no diretório de projeto:

firebase deploy --only functions:groupA

Outra opção seria 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 Firebase CLI é compatível com os seguintes comandos e opções para excluir funções implantadas anteriormente:

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

    firebase functions:delete function1-name

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

    firebase functions:delete function1-name --region region-name

  • Para excluir mais de uma função:

    firebase functions:delete function1-name function2-name

  • Para excluir um grupo de funções especificado:

    firebase functions:delete group-name

  • Para ignorar o prompt de confirmação:

    firebase functions:delete function1-name --force

Configurar os hooks de pré e pós-implantação

Você pode conectar scripts de shell ao comando firebase deploy para realizar tarefas de pré ou pós-implantação. Por exemplo, um script de pré-implantação transcompila o código TypeScript em JavaScript, e um hook de pós-implantação notifica os administradores sobre a implantação do novo conteúdo do site para o Firebase Hosting.

Para configurar os hooks de pré ou pós-implantação, adicione scripts bash ao arquivo de configuração firebase.json. Você pode definir scripts breves diretamente no arquivo firebase.json ou fazer referência a outros arquivos que estão no diretório de projeto.

Por exemplo, o script a seguir é a expressão firebase.json para uma tarefa de pós-implantação que envia uma mensagem 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 que podem ser implantados. Ao executar firebase deploy, todas as tarefas de pré e pós-implantação definidas no arquivo firebase.json são acionadas. Para executar apenas as tarefas associadas a um serviço específico do Firebase, use comandos parciais de implantação.

Os hooks de predeploy e postdeploy imprimem o resultado padrão e os fluxos de erros dos scripts no terminal. Em casos de falha, observe que:

  • 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: o código do projeto ativo
  • $PROJECT_DIR: o diretório raiz que contém firebase.json
  • $RESOURCE_DIR: (somente para scripts de hosting e functions) o local do diretório que contém os recursos do Hosting ou do Cloud Functions a serem implantados

Gerenciar aliases de projeto

Você pode associar diversos projetos do Firebase ao mesmo diretório do projeto. Por exemplo, você pode usar um projeto para teste e outro para produção. Ao usar diferentes ambientes de projeto, você pode confirmar as alterações antes de implantá-las na produção. Com o comando firebase use, você pode alternar entre 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 dele é automaticamente denominado default. No entanto, para permitir que comandos específicos do projeto sejam executados em outro projeto do Firebase, mas use o mesmo diretório, execute este comando:

firebase use --add

Ele solicita que você selecione outro projeto do Firebase e atribua a ele um alias definido. As definições do alias são gravadas em um arquivo .firebaserc no seu diretório de projetos.

Usar aliases de projeto

Para usar os aliases de projeto definidos do Firebase, execute qualquer um dos seguintes comandos no diretório do projeto.

Comando Descrição
firebase use Exibe uma lista de aliases atualmente definidos para o diretório do seu projeto.
firebase use alias_or_project-id Alterna entre os aliases do diretório do seu projeto.
firebase use --clear Limpa o alias "usado" atualmente e direciona todos os comandos para o alias default.
firebase use --unalias alias Remove um alias do diretório do seu projeto.

Durante o uso de um alias, todos os comandos específicos do projeto, como firebase deploy ou firebase data:get, serão executados no projeto atual. Se apenas um alias tiver sido definido no diretório de projeto, todos os comandos específicos serão executados automaticamente nesse alias.

Aliases de controle de origem e de projeto do Firebase

Normalmente, é necessário incluir o arquivo .firebaserc no controle de origem para que sua equipe compartilhe aliases de projetos comuns. No entanto, para projetos de código aberto ou modelos iniciais, geralmente não é necessário incluí-los no arquivo .firebaserc.

Caso você tenha um projeto de desenvolvimento para uso pessoal, envie o sinalizador --project para cada comando ou execute firebase use project-id sem definir um alias para o projeto do Firebase.

Como gerenciar várias instâncias do Firebase Realtime Database

Se um único projeto tiver várias instâncias do Realtime Database, use a opção --instance instance-name para interagir com a instância de banco de dados que não é padrão, instance-name.firebaseio.com.

Os seguintes comandos aceitam a opção --instance:

Comando
database:profile
database:remove
database:push
database:set
database:update
database:get

Referência de comandos

Comandos administrativos

Comando Descrição
login Autentica a conta do Firebase. Exige acesso a um navegador da Web.
logout Sai da Firebase CLI.
login:ci Gera um token de autenticação para uso em ambientes não interativos.
list Imprime uma lista de todos os seus projetos do Firebase.
use Define o projeto do Firebase ativo e gerencia aliases do projeto.
open Abre rapidamente um navegador para recursos relevantes do projeto.
init Configura um novo projeto do Firebase no diretório atual. Esse comando criará um arquivo de configuração firebase.json no diretório atual.
help Exibe informações de ajuda sobre a CLI ou comandos específicos.

Implantação e desenvolvimento local

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

Comando Descrição
deploy Implanta o código e os recursos do diretório no seu projeto do Firebase. No caso do Firebase Hosting, é necessário um arquivo de configuração firebase.json.
serve Inicia um servidor da Web local com a configuração do Firebase Hosting. No caso do Firebase Hosting, é necessário um arquivo de configuração firebase.json.

Comandos de banco de dados

Comando Descrição
database:get Carrega dados no banco de dados do projeto atual e exibe-os como JSON. É compatível com consultas em dados indexados.
database:set Substitui todos os dados em um local específico no banco de dados do projeto atual. Usa como entrada o arquivo STDIN ou o argumento de linha de comando.
database:update Executa uma atualização parcial em um local específico no banco de dados do projeto atual. Usa como entrada o arquivo STDIN ou o argumento de linha de comando.
database:push Envia novos dados para uma lista em um local específico no banco de dados do projeto atual. Usa como entrada o arquivo STDIN ou o argumento de linha de comando.
database:remove Exclui todos os dados de um local específico no banco de dados do projeto atual.
database:profile Cria um perfil de operações no banco de dados do seu projeto. Consulte Perfil do Realtime Database para ver informações mais detalhadas sobre as operações.

Comandos do Hosting

Comando Descrição
hosting:disable Interrompe o atendimento ao tráfego do Firebase Hosting para o projeto ativo. Após a execução desse comando, a mensagem "Site não encontrado" aparece no URL do Hosting de seus projetos.

Comandos do Cloud Firestore

Comando Descrição
firestore:delete Exclui documentos no Cloud Firestore. Com a Firebase CLI, você pode usar exclusões recursivas para excluir todos os documentos em uma coleção.

Comandos do Cloud Functions

Comando Descrição
functions:log Lê os registros das funções implantadas no Cloud Functions.
functions:config:set Armazena os valores de configuração do tempo de execução para as funções do Cloud Functions do projeto atual.
functions:config:get Recupera os valores de configuração existentes para as funções do Cloud Functions do projeto atual.
functions:config:unset Remove os valores de configuração do tempo de execução do projeto atual.
functions:config:clone Copia a configuração do tempo de execução de um ambiente de projeto para outro.

Para mais informações, consulte Configuração do ambiente.

Comandos de gerenciamento de usuários

Comando Descrição
auth:import Importa contas de usuário de um arquivo para o projeto ativo. Consulte a página auth:import e auth:export para ver mais detalhes.
auth:export Exporta as contas de usuário do projeto ativo para um arquivo JSON ou CSV. Consulte a página auth:import e auth:export para ver mais detalhes.

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.