Web-ext est un outil en ligne de commande conçu pour accéder aux différentes parties du processus de développement d'extension Firefox, ce qui rend le développement plus rapide et plus facile. Cet article explique comment installer et utiliser Web-ext.

Installation

Web-ext est une application basée sur nodejs que vous pouvez installer via l'outil nodejs/npm. Installez la avec la commande suivante :

npm install --global web-ext

Ou sous forme raccourcie :

npm i -g web-ext

Vous pouvez tester votre installation en exécutant la commande qui donne le numéro de la version installée :

web-ext --version

Utilisation de web-ext

Une fois que vous l'avez installé, vous pouvez tester Web-ext. À ce stade, il est judicieux d'avoir un exemple d'extension pour l'essayer — si vous ne possédez pas vos propres extensions, vous pouvez cloner notre dépôt webextensions-examples.

Tester une extension

Vous pouvez tester une extension dans Firefox en vous rendant dans le répertoire racine de votre extension  (`cd …`) et en tapant la commande suivante :

web-ext run

Cela va démarrer Firefox et charger l'extension temporairement dans le navigateur, tout comme vous pouvez le voir sur la page about:debugging.

consultez le guide de référence pour connaître toutes les options disponibles.

Rechargement automatique de l'extension

La commande run surveillera vos fichiers sources et dira à Firefox de recharger l'extension après avoir édité et enregistré un fichier. Par exemple, si vous avez changé la propriété name dans votre fichier manifest.json, Firefox affichera le nouveau nom. Cela permet d'essayer facilement de nouvelles fonctionnalités et de les voir immédiatement. La fonction de rechargement automatique est active par défaut pour pouvoir l'utiliser comme suit :

web-ext run

Vous pouvez également appuyer sur la touche r du terminal web-ext pour recharger manuellement l'extension.

Si la fonction de rechargement se comporte de façon inattendue, merci de le signaler en déposant un bug. Vous pouvez également désactiver le rechargement automatique à l'aide de la commande suivante :

web-ext run --no-reload

Le rechargement d'extension est seulement suppporté à partir de Firefox 49 ou supérieur.

Tester dans différentes versions de Firefox

Pour exécuter votre extension dans une autre version de Firefox que la version courante, utilisez l'option --firefox pour spécifier un chemin d'accès complet au fichier binaire. Voici un exemple sur Mac OS :

web-ext run --firefox=/Applications/FirefoxNightly.app/Contents/MacOS/firefox-bin

Sur Windows, le chemin d'accès doit inclure la partie firefox.exe :

web-ext run --firefox="C:\Program Files\Mozilla Firefox\firefox.exe"

Tester avec la version Firefox 48

Firefox 48 a été la première version stable à utiliser la plate-forme WebExtension mais elle ne permet pas à Web-ext d'installer une extension à distance. Vous devez exécuter votre extension dans Firefox 48 avec une option d'installation différente :

web-ext run --pre-install

Tester des extensions non signées

Lorsque vous exécutez web-ext run, l'extension est installée temporairement jusqu'à ce que vous fermiez Firefox. Cela ne viole aucune restriction de signature. Si au lieu de cela vous créez un fichier zip avec une compilation Web-ext et essayez de l'installer dans Firefox, vous obtiendrez une erreur indiquant que l'extension n'est pas signé. Vous devrez utiliser une compilation sans marque ou utiliser une version de développement pour installer ces extensions non signées.

Utiliser un profil personnalisé

Par défaut, la commande run crée un profil Firefox temporaire. Vous pouvez exécuter votre extension avec un profil spécifique à l'aide de l'option --firefox-profile, comme ceci :

web-ext run --firefox-profile=your-custom-profile

Cette option accepte une chaine contenant le nom de votre profil ou un chemin absolu vers le répertoire de profil. Cela peut être utile si vous souhaitez configurer manuellement certains paramètres qui seront toujours disponibles pour la commande run.

Garder les changements de profil

La commande run n'empêche pas les modifications apportées au profil personnalisé spécifié par --firefox-profile.  Pour garder les modifications, ajoutez cette option :

web-ext run --keep-profile-changes --firefox-profile=your-custom-profile

Cela peut être utile si votre extension possède plusieurs états d'exécution différents.

Cette option rend le profil spécifié par --firefox-profile complètement insécurisé pour une utilisation quotidienne. Il désactive les mises à jour automatique et permet entre autres choses des connexions à distance silencieuses. Plus précisément, cela modifiera de manière destructive le profil requis pour que web-ext opère.

Packager votre extension

Une fois que vous avez testé votre extension et vérifié qu'elle fonctionnait, vous pouvez la transformer en un paquet pour la soumettre sur  addons.mozilla.org en utilisant la commande suivante :

web-ext build

Cette commande produit un chemin d'accès complet au fichier .zip généré qui peut être chargé dans un navigateur.

Le fichier .zip généré ne fonctionne pas sur Firefox sans le signer ou en ajoutant la clé applications.gecko.id au manifest.json. Pour plus d'informations, veuillez consulter la page WebExtensions et l'ID de l'extension.

La compilation web-ext est conçue pour ignorer automatiquement les fichiers communément soustraits des paquets, tels que les fichiers .git, node_modules, et autres artéfacts.

Consulter le guide signé de références pour en apprendre plus.

Signer l'extension pour distribution

En alternative à la publication de votre extension sur addons.mozilla.org, vous pouvez vous-même héberger le fichier packagé mais il doit d'abord être signé par Mozilla. La commande suivante forge et signe un fichier ZIP, puis le renvoie comme un fichier XPI signé bon pour distribution :

web-ext sign --api-key=$AMO_JWT_ISSUER --api-secret=$AMO_JWT_SECRET 

Les options de l'API sont nécessaires pour spécifier vos informations d'identification addons.mozilla.org.

  • --api-key: La clé API (JWT issuer) d'addons.mozilla.org devait signer l'extension. Cela devrait toujours être une chaîne.
  • --api-secret: L'API secret (JWT secret) d'addons.mozilla.org doit signer l'extension. Cela devrait toujours être une chaîne.

Consuter le guide de références pour connaitre toutes les options disponibles.

Signature des extensions sans ID spécifique

web-ext prend entièrement en charde la signature d'extensions qui ne déclarent pas la propriété applications.gecko.id dans leur manifest. La première fois que vous signez une extension sans ID explicite,  addons.mozilla.org générera automatiquement un identifiant et web-ext  enregistrera .web-extension-id dans le répertoire courrant de travail. Vous devez enregistrer le fichier ID afin que vous puissiez signer les versions futures de la même extension. Si vous perdez le fichier ID, vous devrez ajouter la propriété applications.gecko.id ou utiliser l'option  --id lors de la signature des versions futures, par exemple :

web-ext sign --api-key=... --api-secret=... --id="{c23c69a7-f889-447c-9d6b-7694be8035bc}"

S'inscrire dans un environnement restreint

Si vous travaillez dans un environnement qui restreint l'accès à certains domaines, vous pouvez essayer d'utiliser un proxy lors de la signature:

web-ext sign --api-key=... --api-secret=... --api-proxy=https://yourproxy:6000

Voir l'--api-proxy pour en savoir plus.

Si vous devez simplement autoriser les domaines utilisés pour la signature et le téléchargement de fichiers, permettez ceci:

  • addons.mozilla.org
  • addons.cdn.mozilla.net

Vérification du code "lint"

Avant d'essayer votre extension avec la commande run ou de soumettre votre package à addons.mozilla.org, vous pouvez utiliser la commande lint pour vous assurer que votre manifest et les autres fichiers sources ne contiennent aucune erreur. Exemple :

web-ext lint

Cela utilise la librairie addons-linter pour parcourir votre répartoire de code source et signaler toutes les erreurs, comme la déclaration d'une permission inconnue.

Consultez le guide de référence de lint pour en savoir plus sur toutes les options disponibles.

Spécification des différents répertoires source et destination

Les commandes ci-dessus utilisent tous les répertoires par défaut pour la source d'extension et la création artifact (par exemple, les fichiers .zip construits). Les valeurs par défaut sont :

  • Source : Le répertoire dans lequel vous vous trouvez actuellement.
  • Artifacts: Un répertoire appelé ./web-ext-artifacts, créé dans le répertoire courrant.

Vous pouvez spécifier différents répertoires source et destination en utilisant les options --source-dir (ou l'alias -s) et --artifacts-dir (ou l'alias -a) lors de l'exécution de vos commandes. Leurs valeurs peuvent être des chemins relatifs ou absolus, mais doivent toujours être spécifiées comme des chaînes. Voici un exemple de spécification des deux options en même temps lors de la construction d'une extension :

web-ext build --source-dir=webextension-examples/notify-link-clicks-i18n --artifacts-dir=zips

Afficher les messages verbeux

Si vous voulez voir exactement ce que fait web-ext lorsque vous exécutez une commande, vous ajoutez l'option --verbose (ou l'alias -v). Par exemple :

web-ext build --verbose

Afficher toutes les commandes options

Vous pouvez lister toutes les commandes et options comme ceci :

web-ext --help

Note: Vous pouvez également utiliser l'alias -h.

Vous pouvez lister les options d'une commande spécifique en l'ajoutant comme argument :

web-ext --help run

Voir aussi

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : Bat41, PhilippePerret, hellosct1, jmh
 Dernière mise à jour par : Bat41,