Gérer les configurations de projet avec le fichier manifeste des extensions

Un fichier manifeste d'extensions est une liste d'instances d'extension et de leurs configurations. Avec le fichier manifeste, vous pouvez :

• partager votre configuration d'extensions avec d'autres utilisateurs ;
• copier votre configuration d'extensions entre différents projets (par exemple, de votre projet de préproduction vers votre projet de production) ;
• déployer toutes vos extensions en même temps ;
• tester le fonctionnement de vos extensions avec votre application à l'aide de Firebase Local Emulator Suite
• valider votre configuration d'extensions dans le contrôle des sources ;
• inclure des extensions dans votre pipeline CI/CD.

Un fichier manifeste d'extensions comporte deux parties :

• La section extensions de votre fichier firebase.json, qui est une carte de l'ID d'instance vers la référence de la version de l'extension. Exemple :

  {
   "extensions": {
     "my-bigquery-extension": "firebase/firestore-bigquery-export@^0.1.18",
     "my-image-resizer": "firebase/storage-resize-images@^0.1.22",
   }
  }
  

• Les fichiers .env contenant la configuration de chacune de vos instances d'extension, dans le sous-répertoire extensions/ de votre répertoire de projet Firebase. Par exemple, une instance de storage-resize-images peut avoir un fichier .env comme suit :

  IMAGE_TYPE=jpeg
  LOCATION=us-central1
  IMG_BUCKET=${param:PROJECT_ID}.firebasestorage.app
  IMG_SIZES=100x100
  DELETE_ORIGINAL_FILE=false

Créer un fichier manifeste d'extensions

Il existe trois façons de créer un fichier manifeste d'extensions :

• Gérer votre fichier manifeste d'extensions avec la CLI Firebase
• Exporter la configuration d'extensions d'un projet
• Modifier manuellement les fichiers manifestes

Les deux premières méthodes sont expliquées ci-dessous.

Gérer votre fichier manifeste d'extensions avec la CLI Firebase

Vous pouvez exécuter la plupart des commandes ext: de la CLI Firebase avec l'option --local pour mettre à jour le fichier manifeste d'extensions sans modifier la configuration actuelle du projet.

Exemple :

firebase ext:install --local firebase/firestore-bigquery-export

L'exécution de la commande ci-dessus vous invite à configurer la dernière version de l'extension firebase/firestore-bigquery-export et à enregistrer la configuration dans le fichier manifeste, mais elle ne déploie pas la configuration dans votre projet.

Voici d'autres exemples de commandes qui modifient le fichier manifeste d'extensions :

# ext:configure changes the params for an extension instance in your extensions manifest
$ firebase ext:configure my-bigquery-extension --local

# ext:update --local updates an instance in your extensions manifest
# to the latest version of that extension
$ firebase ext:update my-bigquery-extension --local

# You can also specify a version if you don't want to update to the latest version
$ firebase ext:update my-bigquery-extension firebase/firestore-bigquery-export@0.1.10 --local 

# ext:uninstall --local removes an instance from your extensions manifest
$ firebase ext:uninstall my-bigquery-extension --local

Exporter la configuration d'extensions d'un projet

Pour enregistrer la configuration d'extensions actuelle d'un projet dans le fichier manifeste, procédez comme suit :

1. Si ce n'est pas déjà fait, configurez la CLI Firebase.
2. À partir d'une invite shell, accédez au répertoire du projet. (Votre répertoire de projet contient le fichier firebase.json).
3. Exécutez la commande ext:export :

   firebase ext:export

La commande ext:export ajoute une section extensions au fichier firebase.json. De plus, la commande ext:export crée un répertoire extensions contenant un fichier .env pour chaque instance d'extension que vous avez installée. Ces fichiers contiennent les paramètres de configuration de chaque instance.

Tester une configuration d'extensions avec la Firebase Local Emulator Suite

Une fois que vous avez ajouté des instances d'extension à votre fichier manifeste d'extensions, vous pouvez les tester à l'aide de la Local Emulator Suite.

1. Installez et configurez la Local Emulator Suite.

2. Démarrez le Local Emulator Suite :

   • Pour exécuter la suite d'émulateurs de manière interactive, exécutez la commande firebase emulators:start.
   • Pour exécuter la suite d'émulateurs et un script de test, exécutez la commande firebase emulators:exec my-test.sh.

Désormais, si des instances d'extension sont listées dans votre fichier manifeste, la Local Emulator Suite télécharge le code source de ces extensions dans ~/.cache/firebase/extensions. Une fois téléchargées, la Local Emulator Suite démarre et vous pouvez déclencher n'importe quelle fonction déclenchée en arrière-plan des extensions et connecter votre application à la suite d'émulateurs pour tester leur intégration à votre application.

Déployer une configuration d'extensions dans un projet

Une fois que vous avez ajouté des instances d'extension à votre fichier manifeste d'extensions, vous pouvez le déployer dans un projet à l'aide de la CLI Firebase. Lorsque vous effectuez un déploiement avec un fichier manifeste d'extensions, vous installez, mettez à jour et configurez toutes les instances d'extension du fichier manifeste dans un projet en même temps.

Pour déployer un fichier manifeste d'extensions :

1. À partir d'une invite shell, accédez au répertoire contenant la configuration d'extensions enregistrée. (Il s'agit du répertoire contenant firebase.json. Si vous venez d'exécuter ext:export, vous vous trouvez déjà dans le bon répertoire.)
2. Exécutez la commande deploy. Si vous souhaitez déployer les extensions dans un projet autre que celui en cours, spécifiez également --project= :

   firebase deploy --only extensions –-project=YOUR_PROJECT_ID

La commande deploy valide la configuration de chaque instance, vous demande si vous souhaitez supprimer des instances d'extension de votre projet de destination qui ne sont pas listées dans firebase.json, puis déploie toutes vos instances d'extension.

Configurations d'extensions spécifiques à un projet

Les configurations d'extensions enregistrées peuvent être utilisées pour effectuer un déploiement dans plusieurs projets différents : par exemple, un projet de préproduction et un projet de production. Dans ce cas, certaines valeurs de paramètres peuvent être différentes pour chaque projet. Les fichiers .env spécifiques à un projet permettent cela :

• Placez les valeurs de paramètres qui diffèrent entre les projets dans extensions/EXTENSION_INSTANCE_ID.env.YOUR_PROJECT_ID.
• Placez les valeurs de paramètres partagées dans extensions/EXTENSION_INSTANCE_ID.env.

Parfois, vous pouvez utiliser une autre valeur de paramètre lorsque vous émulez vos extensions : par exemple, vous pouvez fournir une clé API de test au lieu d'une clé de production. Placez ces paramètres dans un fichier .local :

• Placez les paramètres non secrets que vous souhaitez utiliser lors de l'émulation dans extensions/EXTENSION_INSTANCE_ID.env.local
• Placez les valeurs de paramètres secrets dans extensions/EXTENSION_INSTANCE_ID.secret.local.