Documentation de référence de la CLI Firebase

La CLI Firebase (GitHub) fournit divers outils pour gérer, afficher et déployer des projets Firebase.

Avant d'utiliser la CLI Firebase, configurez un projet Firebase.

Configurer ou mettre à jour la CLI

Installer la CLI Firebase

Vous pouvez installer la CLI Firebase à l'aide d'une méthode adaptée à votre système d'exploitation, à votre niveau d'expérience et/ou à votre cas d'utilisation. Quelle que soit la méthode d'installation CLI, vous avez accès à la même fonctionnalité et à la commande firebase.

Windows macOS Linux

Windows

Vous pouvez installer la CLI Firebase pour Windows à l'aide de l'une des options suivantes :

macOS ou Linux

Vous pouvez installer la CLI Firebase pour macOS ou Linux à l'aide de l'une des méthodes les options suivantes:

Se connecter et tester la CLI Firebase

Après avoir installé la CLI, vous devez vous authentifier. Vous pouvez ensuite confirmer l'authentification en listant vos projets Firebase.

1. Connectez-vous à Firebase avec votre compte Google en exécutant la commande suivante :

   firebase login

   Cette commande connecte votre ordinateur local à Firebase et vous permet d'accéder à vos projets Firebase.

2. Vérifiez que la CLI est correctement installée et qu'elle accède à votre compte en listant vos projets Firebase. Exécutez la commande suivante :

   firebase projects:list

   La liste affichée doit être identique aux projets Firebase listés dans la console Firebase.

Mettre à jour vers la dernière version de la CLI

En règle générale, il est préférable d'utiliser la version la plus récente de la CLI Firebase.

La façon dont vous mettez à jour la version de la CLI dépend de votre système d'exploitation et de la façon dont vous avez installé la CLI.

Utiliser la CLI avec les systèmes CI

La CLI Firebase nécessite un navigateur pour effectuer l'authentification, mais elle est entièrement compatible avec le CI et d'autres environnements headless.

1. Sur une machine avec un navigateur, Installez la CLI Firebase.

2. Lancez le processus de connexion en exécutant la commande suivante:

   firebase login:ci

3. Accédez à l'URL fournie, puis connectez-vous à l'aide d'un compte Google.

4. Imprimer une nouvelle jeton d'actualisation. La session CLI en cours ne sera pas affectée.

5. Stockez le jeton de sortie de manière sécurisée, mais accessible, dans votre système de CI.

6. Utilisez ce jeton lorsque vous exécutez des commandes firebase. Vous pouvez utiliser l'une des deux options suivantes :

   • Option 1 : Stockez le jeton en tant que variable d'environnement FIREBASE_TOKEN. Votre système utilisera automatiquement le jeton.

   • Option 2 : Exécutez toutes les commandes firebase avec l'option --token TOKEN dans votre système de CI.
     Il s'agit de l'ordre de priorité pour le chargement des jetons: option, environnement du projet Firebase souhaité.

Initialiser un projet Firebase

De nombreuses tâches courantes effectuées à l'aide de la CLI, comme le déploiement dans un projet Firebase, nécessitent un répertoire de projet. Vous établissez un répertoire de projet à l'aide de la commande firebase init. Un répertoire de projet est généralement le même que le répertoire racine de votre contrôle source. Après avoir exécuté firebase init, le répertoire contient un fichier de configuration firebase.json.

Pour initialiser un nouveau projet Firebase, exécutez la commande suivante depuis votre de votre application:

firebase init

La commande firebase init vous guide tout au long de la configuration de votre répertoire de projet et de certains produits Firebase. Lors de l'initialisation du projet, la CLI Firebase vous demande d'effectuer les tâches suivantes :

• Sélectionnez les produits Firebase que vous souhaitez configurer dans votre projet Firebase.

  Cette étape vous invite à définir des configurations pour des fichiers spécifiques pour les produits sélectionnés. Pour en savoir plus sur ces configurations, consultez la documentation du produit spécifique (par exemple, Hosting). Notez que vous pouvez toujours exécuter firebase init plus tard pour configurer d'autres produits Firebase.

• Sélectionnez un projet Firebase par défaut.

  Cette étape associe le répertoire de projet actuel à un projet Firebase afin que les commandes spécifiques au projet (comme firebase deploy) s'exécutent sur le projet Firebase approprié.

  Vous pouvez également associer plusieurs projets Firebase (tels qu'un projet de préproduction et un projet de production) au même répertoire de projet.

À la fin de l'initialisation, Firebase crée automatiquement les deux fichiers suivants à la racine de votre répertoire d'application local :

• Un fichier de configuration firebase.json qui répertorie la configuration de votre projet.

• Fichier .firebaserc qui stocke les alias de votre projet.

Le fichier firebase.json

La commande firebase init crée un firebase.json à la racine du répertoire de votre projet.

Le fichier firebase.json est nécessaire pour déployer des éléments avec la CLI Firebase, car elle spécifie les fichiers et les paramètres de votre répertoire de projet qui sont déployés projet Firebase. Certains paramètres pouvant être définis dans votre projet ou Firebase, veillez à résoudre tout problème conflits de déploiement.

Vous pouvez configurer la plupart des options Firebase Hosting directement dans le fichier firebase.json. Toutefois, pour d'autres Services Firebase pouvant être déployés avec la CLI Firebase, La commande firebase init crée des fichiers spécifiques dans lesquels vous pouvez définir des paramètres pour ces services, par exemple un fichier index.js pour Cloud Functions. Vous pouvez configurez également des hooks de prédéploiement ou de post-déploiement dans le fichier firebase.json.

Vous trouverez ci-dessous un exemple de fichier firebase.json avec les paramètres par défaut si vous sélectionnez Firebase Hosting, Cloud Firestore et Cloud Functions for Firebase (avec les options de source et de lint TypeScript sélectionnées) lors de l'initialisation.

{
  "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"
    ]
  }
}

Bien que firebase.json soit utilisé par défaut, vous pouvez transmettre la valeur l'option --config PATH pour spécifier une autre fichier de configuration.

Configuration pour plusieurs bases de données Cloud Firestore

Lorsque vous exécutez firebase init, votre fichier firebase.json contient un seul Clé firestore correspondant à la base de données par défaut de votre projet, comme indiqué ci-dessus.

Si votre projet contient plusieurs bases de données Cloud Firestore, modifiez votre fichier firebase.json pour associer d'autres Cloud Firestore Security Rules et d'index de base de données avec chaque base de données. Modifiez le fichier avec un tableau JSON, avec une entrée pour chaque base de données.

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

Cloud Functions fichiers à ignorer lors du déploiement

Au moment du déploiement de la fonction, la CLI spécifie automatiquement une liste des fichiers à ignorer dans le répertoire functions. Ce empêche le déploiement sur le backend de fichiers superflus pour augmenter la taille des données de votre déploiement.

Voici la liste des fichiers ignorés par défaut, au format JSON :

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

Si vous ajoutez vos propres valeurs personnalisées pour ignore dans firebase.json, veillez à conserver (ou à ajouter, si elle est manquante) la liste des fichiers indiquée ci-dessus.

Gérer les alias de projet

Vous pouvez associer plusieurs projets Firebase au même répertoire de projet. Par exemple, vous pouvez utiliser un projet Firebase pour la préproduction et un autre pour la production. En utilisant différents environnements de projet, vous pouvez vérifier les modifications avant de les déployer en production. La commande firebase use vous permet de basculer entre des alias et de créer des alias.

Ajouter un alias de projet

Si vous sélectionnez un projet Firebase pendant la gestion d'initialisation, le projet est automatiquement a attribué l'alias de default. Toutefois, pour autoriser l'exécution de commandes spécifiques à un projet sur un autre projet Firebase tout en utilisant le même répertoire de projet, exécutez la commande suivante à partir de votre répertoire de projet :

firebase use --add

Cette commande vous invite à sélectionner un autre projet Firebase et à l'attribuer en tant qu'alias. Les attributions d'alias sont écrites dans un fichier .firebaserc dans le répertoire de votre projet.

Utiliser des alias de projet

Pour utiliser les alias de projet Firebase attribués, exécutez l'une des commandes suivantes depuis le répertoire de votre projet.

Vous pouvez ignorer le projet actuellement actif en transmettant l'option --project par n'importe quelle commande CLI. Par exemple: vous pouvez définir votre CLI pour s'exécuter sur un projet Firebase auquel vous avez attribué le rôle staging un alias. Si vous souhaitez exécuter une commande unique sur le projet Firebase que vous avez attribué à l'alias prod, vous pouvez exécuter, par exemple, firebase deploy --project=prod

Contrôle des sources et alias de projet

En général, vous devez vérifier votre fichier .firebaserc dans le contrôle du code source pour permettent à votre équipe de partager des alias de projet. Toutefois, pour les projets Open Source ou les modèles de démarrage, vous ne devez généralement pas enregistrer votre fichier .firebaserc.

Si vous avez un projet de développement exclusivement destiné à votre usage, vous pouvez transmettre l'option --project avec chaque commande ou exécutez firebase use PROJECT_ID sans attribuer d'alias à le projet Firebase.

Diffuser et tester votre projet Firebase localement

Vous pouvez afficher et tester votre projet Firebase sur des URL hébergées localement avant le le déploiement en production. Si vous ne souhaitez tester que certaines fonctionnalités, vous pouvez utiliser une liste d'éléments séparés par une virgule dans un indicateur de la commande firebase serve.

Exécutez la commande suivante à partir de la racine de votre répertoire de projet local si vous souhaitez effectuer l'une des tâches suivantes :

• Afficher le contenu statique de votre application hébergée sur Firebase
• Vous utilisez Cloud Functions pour générer du contenu dynamique pour Firebase Hosting et vous souhaitez utiliser vos fonctions HTTP de production (déployées) pour émuler Hosting sur une URL locale.

firebase serve --only hosting

Émuler votre projet à l'aide de fonctions HTTP locales

Exécutez l'une des commandes suivantes à partir du répertoire de votre projet pour émuler votre projet à l'aide de fonctions HTTP locales.

• Pour émuler les fonctions et l'hébergement HTTP à des fins de test sur des URL locales, utilisez l'une des commandes suivantes :

  firebase serve

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

• Pour émuler uniquement les fonctions HTTP, utilisez la commande suivante :

  firebase serve --only functions

Tester depuis d'autres appareils locaux

Par défaut, firebase serve ne répond qu'aux requêtes provenant de localhost. Ce signifie que vous pouvez accéder à votre contenu hébergé depuis le navigateur Web de votre ordinateur dans votre navigateur, mais pas à partir d'autres appareils de votre réseau. Si vous souhaitez effectuer des tests à partir d'autres appareils locaux, utilisez l'indicateur --host, comme suit :

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

Déployer dans un projet Firebase

La CLI Firebase gère le déploiement de code et d'éléments dans votre projet Firebase, y compris :

• Nouvelles versions de vos sites Firebase Hosting
• Cloud Functions for Firebase nouvelle, mise à jour ou existante
• Nouveaux schémas et connecteurs pour Firebase Data Connect
• Règles pour Firebase Realtime Database
• Règles pour Cloud Storage for Firebase
• Règles pour Cloud Firestore
• Index pour Cloud Firestore

Pour déployer dans un projet Firebase, exécutez la commande suivante à partir du répertoire de votre projet :

firebase deploy

Vous pouvez éventuellement ajouter un commentaire à chacun de vos déploiements. Ce commentaire va s'affiche avec les autres informations de déploiement de l'espace de noms Firebase Hosting . Exemple :

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

Lorsque vous utilisez la commande firebase deploy, gardez à l'esprit ce qui suit :

• Pour déployer des ressources à partir d'un répertoire de projet, le répertoire du projet doit avoir un fichier firebase.json. Ce fichier est créé automatiquement par la commande firebase init.

• Par défaut, firebase deploy crée une version pour toutes les ressources déployables dans le répertoire de votre projet. Pour déployer des services ou fonctionnalités Firebase spécifiques, Utiliser un déploiement partiel.

Conflits de déploiement pour les règles de sécurité

Pour Firebase Realtime Database, Cloud Storage for Firebase et Cloud Firestore : vous pouvez définir des règles de sécurité dans le répertoire de votre projet local Console Firebase

Pour éviter les conflits de déploiement, vous pouvez également utiliser un déploiement partiel et ne définir que des règles dans la console Firebase.

Quotas de déploiement

Il est possible (mais peu probable) que vous dépassiez un quota limitant le taux ou le volume de vos opérations de déploiement Firebase. Par exemple, lorsque déployant un très grand nombre de fonctions, vous pouvez recevoir une réponse HTTP 429 Quota s'affiche. Pour résoudre ces problèmes, essayez à l'aide d'un déploiement partiel.

Effectuer un rollback d'un déploiement

Vous pouvez annuler un déploiement Firebase Hosting depuis la page Firebase Hosting de votre projet en sélectionnant l'action Rollback (Annuler) pour la version souhaitée.

Il n'est actuellement pas possible d'effectuer un rollback des versions des règles de sécurité pour Firebase Realtime Database, Cloud Storage for Firebase ou Cloud Firestore

Déployer des services Firebase spécifiques

Si vous ne souhaitez déployer que des services ou fonctionnalités Firebase spécifiques, vous pouvez utiliser un d'une liste d'éléments séparés par une virgule dans une option de la commande firebase deploy. Par exemple, la commande suivante déploie le contenu Firebase Hosting et les règles de sécurité Cloud Storage.

firebase deploy --only hosting,storage

Le tableau suivant répertorie les services et fonctionnalités disponibles pour le déploiement partiel. Les noms des indicateurs correspondent aux clés de votre fichier de configuration firebase.json.

Déployer des fonctions spécifiques

Lorsque vous déployez des fonctions, vous pouvez cibler des fonctions spécifiques. Exemple :

firebase deploy --only functions:function1

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

Une autre option consiste à regrouper les fonctions en groupes d'exportation dans votre /functions/index.js. Le regroupement de fonctions vous permet de déployer plusieurs fonctions à l'aide d'une seule commande.

Par exemple, vous pouvez écrire les fonctions suivantes pour définir un groupA et un groupB :

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

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

Dans cet exemple, un fichier functions/groupB.js distinct contient des fonctions supplémentaires qui définissent spécifiquement les fonctions dans groupB. Exemple :

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

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

Dans cet exemple, vous pouvez déployer toutes les fonctions groupA en exécutant la commande à partir du répertoire de votre projet:

firebase deploy --only functions:groupA

Vous pouvez également cibler une fonction spécifique dans un groupe en exécutant la commande suivante : commande:

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

Supprimer des fonctions

La CLI Firebase accepte les commandes et options suivantes pour supprimer les fonctions précédemment déployées :

• Supprime toutes les fonctions correspondant au nom spécifié dans toutes les régions:

  firebase functions:delete FUNCTION-1_NAME

• Supprime une fonction spécifiée s'exécutant dans une région autre que celle par défaut:

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

• Supprime plusieurs fonctions :

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

• Supprime un groupe de fonctions spécifié :

  firebase functions:delete GROUP_NAME

• Ignore l'invite de confirmation :

  firebase functions:delete FUNCTION-1_NAME --force

Configurer des tâches de prédéploiement et de postdéploiement

Vous pouvez connecter des scripts shell à la commande firebase deploy pour effectuer de prédéploiement ou de post-déploiement. Par exemple, un script de prédéploiement peut transcompiler le code TypeScript en JavaScript, et un hook postdéploiement peut avertir les administrateurs des nouveaux déploiements de contenu de site sur Firebase Hosting.

Pour configurer des hooks de prédéploiement ou de post-déploiement, ajoutez des scripts bash à votre firebase.json. Vous pouvez définir de courts scripts directement dans le fichier firebase.json, ou vous pouvez faire référence à d'autres qui se trouvent dans le répertoire de votre projet.

Par exemple, le script suivant est l'expression firebase.json d'une tâche post-déploiement qui envoie un message Slack après un déploiement réussi sur Firebase Hosting.

"hosting": {
  // ...

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

Le fichier de script messageSlack.sh se trouve dans le répertoire du projet et se présente comme suit :

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

Vous pouvez configurer des hooks predeploy et postdeploy pour n'importe quel éléments que vous pouvez déployer. Notez que l'exécution de firebase deploy déclenche toutes les tâches de prédéploiement et de postdéploiement définies dans votre fichier firebase.json. Pour n'exécuter que les tâches associées à un service Firebase spécifique, utilisez des commandes de déploiement partiel.

Les hooks predeploy et postdeploy impriment la sortie standard et les flux d'erreur des scripts dans le terminal. En cas d'échec, veuillez noter les points suivants:

• Si un hook de prédéploiement ne se termine pas comme prévu, le déploiement est annulé.
• Si le déploiement échoue pour une raison quelconque, les hooks post-déploiement ne sont pas déclenchés.

Variables d'environnement

Dans les scripts exécutés dans les hooks de prédéploiement et de postdéploiement, les variables d'environnement suivantes sont disponibles :

• $GCLOUD_PROJECT : ID du projet actif
• $PROJECT_DIR: répertoire racine contenant le fichier firebase.json
• $RESOURCE_DIR : (pour les scripts hosting et functions uniquement) : emplacement du répertoire contenant le Hosting ou Cloud Functions ressources à déployer

Gérer plusieurs instances Realtime Database

Un projet Firebase peut contenir plusieurs instances Firebase Realtime Database. Par les commandes CLI interagissent avec votre instance de base de données default.

Toutefois, vous pouvez interagir avec une instance de base de données non par défaut à l'aide de l'option --instance DATABASE_NAME. Les commandes suivantes acceptent l'option --instance :

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

Documentation de référence sur les commandes

Commandes administratives de la CLI

Commandes de gestion de projet

Déploiement et développement local

Ces commandes vous permettent de déployer votre site Firebase Hosting et d'interagir avec celui-ci.

Commandes App Distribution

Commandes App Hosting

Commandes Authentication (gestion des utilisateurs)

Commandes Cloud Firestore

Commandes Cloud Functions for Firebase

Pour en savoir plus, consultez la page Environnement documentation de configuration.

Commandes Crashlytics

Commandes Data Connect

Ces commandes et leurs cas d'utilisation sont décrits plus en détail dans le guide de référence de la CLI Data Connect.

Commandes Extensions

Commandes Extensions pour les éditeurs

Commandes Hosting

Commandes Realtime Database

Notez que vous pouvez créer votre instance Realtime Database initiale par défaut dans le Firebase ou à l'aide de la commande firebase init générale le workflow de ML firebase init database.

Une fois les instances créées, vous pouvez les gérer comme indiqué dans Gérez plusieurs instances Realtime Database.

Commandes Remote Config