Referência da CLI do Firebase

A CLI do Firebase ( GitHub ) fornece diversas ferramentas para gerenciar, visualizar e implantar em projetos do Firebase.

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

Configurar ou atualizar a CLI

Instale a CLI do Firebase

Você pode instalar a CLI do Firebase usando um método que corresponda ao seu sistema operacional, nível de experiência e/ou caso de uso. Independentemente de como você instala a CLI, você tem acesso à mesma funcionalidade e ao comando firebase .

Windows macOS Linux

janelas

Você pode instalar a CLI do Firebase para Windows usando uma das seguintes opções:

macOS ou Linux

Você pode instalar a CLI do Firebase para macOS ou Linux usando uma das seguintes opções:

Faça login e teste a CLI do Firebase

Depois de instalar a CLI, você deve autenticar. Depois, você pode confirmar a autenticação listando seus projetos do Firebase.

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

   firebase login

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

2. Teste se a CLI está instalada corretamente e acessando sua conta listando seus projetos do Firebase. Execute o seguinte comando:

   firebase projects:list

   A lista exibida deve ser a mesma dos projetos do Firebase listados no console do Firebase .

Atualize para a versão CLI mais recente

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

A forma como você atualiza a versão da CLI depende do seu sistema operacional e de como você instalou a CLI.

Use a CLI com sistemas CI

A CLI do Firebase requer um navegador para concluir a autenticação, mas a CLI é totalmente compatível com CI e outros ambientes headless.

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

2. Inicie o processo de login executando o seguinte comando:

   firebase login:ci

3. Visite o URL fornecido e faça login usando uma conta do Google.

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

5. Armazene o token de saída de forma segura, mas acessível em seu sistema de CI.

6. Use este token ao executar comandos firebase . Você pode usar uma das duas opções a seguir:

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

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

Inicialize um projeto do Firebase

Muitas tarefas comuns executadas usando a CLI, como a implantação em um projeto do Firebase, exigem um diretório de projeto . Você estabelece um diretório de projeto usando o comando firebase init . Um diretório de projeto geralmente é o mesmo diretório que a raiz do controle de origem e, após executar firebase init , o diretório contém 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 orienta você na configuração do diretório do projeto e de alguns produtos do Firebase. Durante a inicialização do projeto, a CLI do Firebase solicita que você conclua as seguintes tarefas:

• Selecione os produtos Firebase desejados para configurar em seu projeto Firebase.

  Esta etapa solicita que você defina configurações para arquivos específicos dos produtos selecionados. Para mais detalhes sobre essas configurações, consulte a documentação específica do produto (por exemplo, Hosting ). Observe que você sempre pode executar firebase init posteriormente para configurar mais produtos Firebase.

• Selecione um projeto padrão do Firebase.

  Esta etapa associa o diretório do projeto atual a um projeto do Firebase para que comandos específicos do projeto (como firebase deploy ) sejam executados no projeto apropriado do Firebase.

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

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

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

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

O 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 especifica quais arquivos e configurações do diretório do projeto são implantados no projeto do Firebase. Como algumas configurações podem ser definidas no diretório do projeto ou no console do Firebase, resolva possíveis conflitos de implantação .

Você pode configurar a maioria das opções do Firebase Hosting diretamente no arquivo firebase.json . No entanto, para outros serviços do Firebase que podem ser implantados com a CLI do Firebase , o comando firebase init cria arquivos específicos onde você pode definir configurações para esses serviços, como um arquivo index.js para Cloud Functions. Você também pode configurar ganchos pré-implantados ou pós-implantados no arquivo firebase.json .

A seguir está um exemplo de arquivo firebase.json com configurações padrão se você selecionar Firebase Hosting, Cloud Firestore e Cloud Functions para Firebase (com opções de origem TypeScript e lint 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"
    ]
  }
}

Embora firebase.json seja usado por padrão, você pode passar o sinalizador --config PATH para especificar um arquivo de configuração alternativo.

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

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

Se o seu projeto contiver vários bancos de dados do Cloud Firestore, edite o arquivo firebase.json para associar diferentes regras de segurança do Cloud Firestore e arquivos de origem de índice de 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 do Cloud Functions a serem ignorados na implantação

No momento da implementação da função, a CLI especifica automaticamente uma lista de arquivos no diretório functions a serem ignorados. Isso evita a implantação no back-end de arquivos estranhos que poderiam aumentar o tamanho dos dados da sua implantação.

A lista de arquivos ignorados por padrão, mostrada 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 (ou adicione, se estiver faltando) a lista de arquivos mostrada acima.

Gerenciar aliases de projeto

Você pode associar vários projetos do Firebase ao mesmo diretório de projeto. Por exemplo, você pode querer usar um projeto do Firebase para preparação e outro para produção. Ao usar diferentes ambientes de projeto, você pode verificar as alterações antes de implantar na produção. O comando firebase use permite alternar entre aliases, bem como criar novos aliases.

Adicione um alias de projeto

Quando você seleciona um projeto do Firebase durante a inicialização do projeto , o projeto recebe automaticamente o alias default . No entanto, para permitir que comandos específicos do projeto sejam executados em um projeto diferente do Firebase, mas ainda usem o mesmo diretório do projeto, execute o seguinte comando no diretório do projeto:

firebase use --add

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

Usar aliases de projeto

Para usar aliases de projeto atribuídos do Firebase, execute qualquer um dos comandos a seguir no diretório do projeto.

Você pode substituir o que está sendo usado como projeto atualmente ativo, passando o sinalizador --project com qualquer comando CLI. Por exemplo: você pode configurar sua CLI para ser executada em um projeto do Firebase ao qual você atribuiu o alias staging . Se quiser executar um único comando no projeto do Firebase ao qual você atribuiu o alias prod , poderá executar, por exemplo, firebase deploy --project=prod .

Controle de origem e aliases de projeto

Em geral, você deve verificar seu arquivo .firebaserc no controle de origem para permitir que sua equipe compartilhe aliases de projeto. No entanto, para projetos de código aberto ou modelos iniciais, geralmente você não deve fazer check-in do arquivo .firebaserc .

Se você tiver um projeto de desenvolvimento apenas para seu uso, poderá passar o sinalizador --project com cada comando ou executar firebase use PROJECT_ID sem atribuir um alias ao projeto Firebase.

Veicule e teste seu projeto do Firebase localmente

Você pode visualizar e testar seu projeto do Firebase em URLs hospedados localmente antes de implantá-lo na produção. Se quiser apenas testar recursos selecionados, você pode usar uma lista separada por vírgulas em um sinalizador no comando firebase serve .

Execute o seguinte comando na raiz do diretório local do projeto se desejar executar uma das seguintes tarefas:

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

firebase serve --only hosting

Emule seu projeto usando funções HTTP locais

Execute qualquer um dos comandos a seguir no diretório do projeto para emular seu projeto usando funções HTTP locais .

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

  firebase serve

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

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

  firebase serve --only functions

Teste de outros dispositivos locais

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

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

Implantar em um projeto do Firebase

A CLI do Firebase gerencia a implantação de código e recursos em seu projeto do Firebase, incluindo:

• Novos lançamentos dos seus sites do Firebase Hosting
• Cloud Functions para Firebase novas, atualizadas ou existentes
• Regras para Firebase Realtime Database
• Regras para armazenamento em nuvem para Firebase
• Regras para Cloud Firestore
• Índices para Cloud Firestore

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

firebase deploy

Opcionalmente, você pode adicionar um comentário a cada uma de suas implantações. Este comentário 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 de um diretório de projeto, o diretório do projeto deve ter um arquivo firebase.json . Este arquivo é criado automaticamente para você pelo comando firebase init .

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

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

Para Firebase Realtime Database, Cloud Storage for Firebase e Cloud Firestore, você pode definir regras de segurança no diretório local do projeto ou no console do Firebase .

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

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. Por exemplo, ao implementar um grande número de funções, você poderá receber uma mensagem de erro HTTP 429 Quota . Para resolver esses problemas, tente usar implantação parcial .

Reverter uma implantação

Você pode reverter uma implantação do Firebase Hosting na página do Firebase Hosting do seu projeto selecionando a ação Rollback para a versão desejada.

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

Implantar serviços específicos do Firebase

Se quiser implantar apenas serviços ou recursos específicos do Firebase, você pode usar uma lista separada por vírgulas em um sinalizador no comando firebase deploy . Por exemplo, o comando a seguir implanta conteúdo do Firebase Hosting e 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 nos sinalizadores correspondem às chaves no arquivo de configuração firebase.json .

Implantar funções específicas

Ao implantar funções, você pode direcionar funções específicas. Por exemplo:

firebase deploy --only functions:function1

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

Outra opção é agrupar funções em grupos de exportação em seu arquivo /functions/index.js . O agrupamento de funções permite implantar diversas funções usando um único comando.

Por exemplo, você pode escrever 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 funções adicionais que definem especificamente as funções em groupB . Por exemplo:

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 do projeto:

firebase deploy --only functions:groupA

Ou você pode direcionar uma função específica dentro de um grupo executando o seguinte comando:

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

Excluir funções

A CLI do Firebase oferece suporte aos seguintes comandos e opções para exclusão de 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 em execução em uma região não 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 com script pré-implantação e pós-implantação

Você pode conectar scripts de shell ao comando firebase deploy para executar tarefas de pré-implantação ou pós-implantação. Por exemplo, um script pré-implantação pode transpilar o código TypeScript em JavaScript, e um gancho pós-implantação pode notificar os administradores sobre a implantação de novos conteúdos do site no Firebase Hosting.

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

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

"hosting": {
  // ...

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

O arquivo de script messageSlack.sh reside 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

Você pode configurar ganchos predeploy e postdeploy para qualquer um dos ativos que puder implantar . Observe que a execução firebase deploy aciona todas as tarefas de pré-implantação e pós-implantação definidas no arquivo firebase.json . Para executar apenas as tarefas associadas a um serviço específico do Firebase, use comandos de implantação parcial .

Os ganchos predeploy e postdeploy imprimem a saída padrão e os fluxos de erro dos scripts no terminal. Para casos de falha, observe o seguinte:

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

Variáveis ​​ambientais

Nos scripts em execução nos ganchos pré-implantação e pós-implantação, as seguintes variáveis ​​de ambiente estão disponíveis:

• $GCLOUD_PROJECT : 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 de hospedagem ou Cloud Functions a serem implantados

Gerenciar diversas instâncias do Realtime Database

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

No entanto, você pode interagir com uma instância de banco de dados não padrão usando o comando --instance DATABASE_NAME . Os seguintes comandos suportam o sinalizador --instance :

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

Referência de comando

Comandos administrativos CLI

Comandos de gerenciamento de projetos

Implantação e desenvolvimento local

Esses comandos permitem implantar e interagir com seu site do Firebase Hosting.

Comandos de distribuição de aplicativos

Comandos de autenticação (gerenciamento de usuários)

Comandos do Cloud Firestore

Comandos do Cloud Functions para Firebase

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

Comandos do Crashlytics

Comandos de extensões

Comandos do editor de extensões

Comandos de hospedagem

Comandos de banco de dados em tempo real

Observe que você pode criar sua instância inicial e padrão de banco de dados em tempo real no console do Firebase ou usando o fluxo de trabalho firebase init Geral ou o fluxo firebase init database .

Depois que as instâncias forem criadas, você pode gerenciá -las conforme discutido no gerenciamento de várias instâncias de banco de dados em tempo real .

Comandos de configuração remota