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

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

  • Partagez la configuration de vos extensions avec d'autres
  • Copiez la configuration de vos extensions entre différents projets (par exemple, de votre projet intermédiaire à votre projet de production)
  • Déployez toutes vos extensions en une seule fois
  • Testez le fonctionnement de vos extensions avec votre application à l'aide de la suite d'émulateurs locaux Firebase
  • Validez la configuration de vos extensions dans le contrôle de code source
  • Inclure des extensions dans votre pipeline CI/CD

Un fichier manifeste d'extensions comporte deux parties :

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

    {
     "extensions": {
       "my-bigquery-extension": "firebase/firestore-bigquery-export@^0.1.18",
       "my-image-resizer": "firebase/storage-resize-images@^0.1.22",
     }
    }
    
  • Fichiers .env contenant la configuration de chacune de vos instances d'extension, dans le sous-répertoire extensions/ du répertoire de votre projet Firebase. Par exemple, une instance de storage-resize-images peut avoir un fichier .env comme celui-ci :

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

Créer un manifeste d'extensions

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

  • Gérez le manifeste de vos extensions avec la CLI Firebase
  • Exporter la configuration des extensions d'un projet
  • Modifier les fichiers manifestes manuellement

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

Gérez le manifeste de vos 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 manifeste des extensions sans modifier réellement la configuration actuelle du projet.

Par exemple:

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

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

Voici d'autres exemples de commandes qui modifient le manifeste des 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 des extensions d'un projet

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

  1. Si vous ne l'avez pas déjà fait, configurez la CLI Firebase
  2. À partir d'une invite du 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 ajoutera une section extensions au fichier firebase.json . De plus, la commande ext:export crée un répertoire d' 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 Firebase Local Emulator Suite

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

  1. Installez et configurez la suite d'émulateurs locaux .

  2. Démarrez la suite d'émulateurs locaux :

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

Désormais, si vous avez des instances d'extension répertoriées dans votre manifeste, la suite d'émulateurs locaux téléchargera le code source de ces extensions dans ~/.cache/firebase/extensions . Une fois téléchargées, la suite d'émulateurs locaux démarrera et vous pourrez déclencher l'une des fonctions déclenchées en arrière-plan des extensions et connecter votre application à la suite d'émulateurs pour tester leur intégration avec votre application.

Déployer une configuration d'extensions dans un projet

Une fois que vous avez ajouté des instances d'extension à votre manifeste d'extension, vous pouvez le déployer dans un projet à l'aide de la CLI Firebase. Lorsque vous déployez avec un manifeste d'extensions, vous installez, mettez à jour et configurez simultanément toutes les instances d'extension du manifeste dans un projet.

Pour déployer un manifeste d'extensions :

  1. À partir d'une invite du shell, accédez au répertoire contenant la configuration des extensions enregistrées. (C'est le répertoire qui contient firebase.json . Si vous venez d'exécuter ext:export , vous êtes déjà dans le bon répertoire.)
  2. Exécutez la commande de deploy . Si vous souhaitez déployer les extensions sur un projet autre que celui en cours, spécifiez également --project= :
    firebase deploy --only extensions –-project=YOUR_PROJECT_ID

La commande de deploy validera chaque configuration d'instance, vous demandera si vous souhaitez supprimer toutes les instances d'extension de votre projet de destination qui ne sont pas répertoriées dans firebase.json , puis déploiera toutes vos instances d'extension.

Configurations d'extension spécifiques au projet

Les configurations d'extensions enregistrées peuvent être utilisées pour se déployer sur plusieurs projets différents : par exemple, un projet intermédiaire et un projet de production. Lors de cette opération, certaines valeurs de paramètres peuvent devoir être différentes pour chaque projet. Les fichiers .env spécifiques au projet rendent cela possible :

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

Parfois, vous souhaiterez peut-être utiliser une valeur de paramètre différente lors de l'émulation de vos extensions : par exemple, vous souhaiterez peut-être fournir une clé d'API de test au lieu d'une clé de production. Mettez ces paramètres dans un fichier .local :

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