Web-ext est un outil en ligne de commande conçu pour accélérer différentes parties du processus de développement d'extensions Firefox, rendant 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 Node.js 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 suivante, qui affiche le numéro de la version installée :

web-ext --version

Utilisation de web-ext

Avant de commencer à utiliser web-ext, choisissez une extension à utiliser comme exemple. Si vous n’en avez pas, utilisez une des extensions du 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 (en utilisant 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 faire sur la page about:debugging.

consultez le guide de référence de run pour en savoir plus.

Rechargement automatique de l’extension

La commande run surveille vos fichiers sources et dit à Firefox de recharger l'extension quand vous éditez et enregistrez un fichier. Par exemple, si vous changez la propriété name dans votre fichier manifest.json, Firefox affichera le nouveau nom. Cela permet d'essayer facilement de nouvelles fonctionnalités, car vous pouvez voir immédiatement leur effet. La fonction de rechargement automatique est active par défaut, vous pouvez 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 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 dans Firefox pour Android

Pour lancer votre extension dans Firefox pour Android, suivez ces instructions pour configurer votre ordinateur et votre appareil.

Une fois votre appareil connecté à votre ordinateur de développement, exécutez :

web-ext run --target=firefox-android

Cette commande affiche l’ID d’appareil pour votre ou vos appareils connecté(s). Si vous ne voyez pas de liste d’ID d’appareils, assurez-vous que vous avez correctement configuré l’appareil pour le développement.

À présent, ajoutez l’ID d’appareil à la commande :

web-ext run --target=firefox-android --android-device=<ID appareil>

Si vous avez plusieurs versions de Firefox installées, vous pouvez avoir besoin de choisir une version spécifique. Par exemple :

web-ext run --target=firefox-android ... --firefox-apk=org.mozilla.firefox

La première fois que vous exécutez cette commande, vous pourriez avoir besoin d’accorder les permissions Android pour l’APK. La raison en est que la commande nécessite un accès en lecture et écriture au stockage de l’appareil, de sorte que Firefox pour Android puisse se lancer sur un profil temporaire. Les informations affichées par web-ext vous donnent des indications sur la manière d’accorder ces permissions.

La commande web-ext ne modifie aucune de vos préférences ou données de Firefox pour Android. Pour voir plus d’informations sur comment web-ext interagit avec votre appareil, exécutez la commande avec --verbose.

Déboguer avec Firefox pour Android

Quand vous utilisez web-ext run pour tester une extension sur Firefox pour Android, vous pouvez remarquer un message comme ceci dans la console de débogage :

You can connect to this Android device on TCP port 51499

C’est un port de débogage à distance auquel vous pouvez vous connecter avec les outils de développement de Firefox. Dans le cas présent, vous vous connecteriez à l’hôte localhost sur le port 51499.

Voir ce guide pour plus d’informations sur le débogage d’extensions sur Firefox pour Android.

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 web-ext buid et essayez de l'installer dans Firefox, vous obtiendrez une erreur indiquant que l'extension n'est pas signée. 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.

Conserver les changements de profil

La commande run ne sauvegarde pas les modifications apportées au profil personnalisé spécifié par --firefox-profile. Pour conserver 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 automatiques et permet, entre autres choses, des connexions à distance silencieuses. Plus précisément, cela apportera au profil des changements destructifs nécessaires pour que web-ext opère.

Empaqueter votre extension

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

web-ext build

Cette commande affiche le chemin complet du 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 d'extension.

La commande web-ext build est conçue pour ignorer les fichiers communément non désirés dans les paquets, tels que les fichiers .git, node_modules, et autres artefacts.

Consultez le guide de référence de build pour en apprendre plus.

Signer votre extension pour distribution

En alternative à la publication de votre extension sur addons.mozilla.org, vous pouvez vous-même héberger le fichier empaqueté, mais il doit d'abord être signé par Mozilla. La commande suivante empaquète et signe un fichier zip, puis le renvoie sous la forme d’un un fichier xpi signé apte à la 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 devant signer l'extension. C’est une chaîne qui ressemble à ceci : user:12345:67.
  • --api-secret : Le secret d’API (JWT secret) d'addons.mozilla.org devant signer l'extension. C’est une chaîne qui ressemble à ceci : 634f34bee43611d2f3c0fd8c06220ac780cff681a578092001183ab62c04e009.

Consultez le guide de référence de sign pour en savoir plus.

Signer des extensions sans ID spécifique

web-ext prend en charge la signature d'extensions ne déclarant 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 un identifiant et web-ext l’enregistrera dans .web-extension-id dans le répertoire de travail. Vous devriez enregistrer le fichier d’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}"

Signer en 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'option --api-proxy pour en savoir plus.

Les domaines suivants sont utilisés pour signer et télécharger des fichiers :

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

Vérifier le code avec lint

Avant d'essayer votre extension avec la commande run ou de soumettre votre paquetage à 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épertoire 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.

Options par défaut

Vous pouvez spécifier --config=my-config.js pour définir des valeurs par défaut pour toute option. Voici un extemple avec la commande build :

web-ext --config=my-config.js build

Le fichier doit être un module CommonJS tel que compris par Node.js et doit exporter chaque valeur de configuration. Voici comment configurer la valeur par défaut de --verbose à true :

modude.exports = {
  verbose: true,
};

Si vous souhaitez définir des options qui doivent s’appliquer seulement à une commande spécifique, imbriquez la configuration sous le nom de la commande. Voici un exemple qui ajoute une configuration pour --overwrite-dest s’appliquant seulement à la command build, ainsi que pour --firefox s’appliquant seulement à la commande run :

module.exports = {
  // Global options:
  verbose: true,
  // Command options:
  build: {
    overwriteDest: true,
  },
  run: {
    firefox: 'nightly',
  },
};

Pour créer une clé de configuration pour une option de ligne de commande, retirez les tirets initiaux et convertissez le nom en camel case. Comme vous pouvez le voir dans cet exemple, --overwrive-dest a été converti en overwriteDest.

Si une option peut être spécifiée plusieurs fois sur la ligne de commande, écrivez-la sous la forme d’un tableau. Par exemple, voici coment spécifier plusieurs motifs --ignore-files :

module.exports = {
  ignoreFiles: [
    'package-lock.json',
    'yarn.lock',
  ],
};

web-ext tentera également de charger ses options de configuration à partir d'une propriété "webExt" incluse dans le fichier package.json du répertoire courant :

{
  "name": "an-extension-src-dir-with-a-package-json",
  "version": "1.0.0",
  ...
  "webExt": {
    "sourceDir": "dist/extension/"
  }
}

Découverte automatique des fichiers de configuration

<web-ext charge les fichiers de configuration existants dans l’ordre suivant :

  • Un fichier de configuration nommé .web-ext-config.js dans votre dossier personnel, par exemple :
    • sous Windows : C:\Users\<username>\.web-ext-config.js
    • sous MacOS : /Users/<username>/.web-ext-config.js
    • sous Linux : /home/<username>/.web-ext-config.js
  • Une propriété de configuration nommée "webExt" incluse dans un fichier package.json dans le répertoire courant.
  • Un fichier de configuration nommé web-ext-config.js dans le répertoire courant.

Si une configuration du dossier personnel et une configuration de dossier local définissent la même option, c’est la valeur du dossier local qui sera utilisée.

Pour désactiver le chargement automatique de fichiers de configuration, passez cette option :

web-ext --no-config-discovery run

Pour diagnostiquer un problème lié aux fichiers de configuration, relancez votre commande avec --verbose. Cela vous dira quel fichier de configuration a défini quelle valeur d’option.

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

Les commandes ci-dessus utilisent toutes les répertoires par défaut pour les sources de l’extension et la création d’artefacts (par exemple, les fichiers .zip construits). Les répertoires par défaut sont :

  • Source : le répertoire dans lequel vous vous trouvez actuellement.
  • Artefacts : un répertoire appelé ./web-ext-artifacts, créé dans le répertoire courant.

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, ajoutez l'option --verbose (ou l'alias -v). Par exemple :

web-ext build --verbose

Afficher toutes les commandes et 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

Détecter une installation temporaire

Votre extension peut détecter si elle a été installée au moyen de web-ext run, plutôt que comme une extension construite et signée téléchargée depuis addons.mozilla.org. Écoutez l'événement runtime.onInstalled, et vérifiez la valeur de details.temporary.

Utiliser web-ext depuis un script

Vous pouvez utiliser web-ext comme un module Node.js. Voici plus d’informations ainsi qu’un exemple de code.

Voir aussi

Étiquettes et contributeurs liés au document

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