Démarrer avec Web-ext

Cette traduction est incomplète. Aidez à traduire cet article depuis l'anglais.

Web-ext est un outil de ligne de commande conçu pour accélérer aux différentes parties du processus de développement d'extension, 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

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 out. À ce stade, il est judicieux d'avoir un exemple d'extension pour l'essayer— si vous ne possédez pas l'un de vos propres éléments, vous pouvez cloner notre dépôt webextensions-examples.

Test d'une extension

Vous pouvez tester une extension dans Firefox par cd'ing dans le répertoire racine de votre extension et entrer la commande suivante :

web-ext run

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

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

Récupération d'extension automatique

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 afficherait 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 déclencher manuellement une extension de rechargement.

Si vous rencontrez un comportement inattendu avec la fonction de rechargement, veuillez déposer un bug. Vous pouvez également désactiver le rechargement comme ceci :

web-ext run --no-reload

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

Test dans différentes versions de Firefox

Pour exécuter votre extension dans une autre version de Firefox que la valeur par défaut, 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"

Testing in Firefox 48

Firefox 48 was the first stable version to use the WebExtension platform but it doesn't allow web-ext to install an extension remotely. You need to run your extension in Firefox 48 with a different installation option:

web-ext run --pre-install

Testing unsigned extensions

When you execute web-ext run, the extension gets installed temporarily until you close Firefox. This does not violate any signing restrictions. If instead you create a zip file with web-ext build and try to install it into Firefox, you will see an error telling you that the add-on is not signed. You will need to use an unbranded build or use a development build to install unsigned extensions.

Using a custom profile

By default, the run command will create a temporary Firefox profile. You can run your extension with a specific profile using the --firefox-profile option, like this:

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

This option accepts a string containing the name of your profile or an absolute path to the profile directory. This may be helpful if you want to manually configure some settings that will always available to the run command.

Keeping profile changes

The run command will not save any changes made to the custom profile specified by --firefox-profile. To keep changes, add this option:

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

This may be helpful if your extension has many different run states.

This option makes the profile specified by --firefox-profile completely insecure for daily usage. It turns off auto-updates and allows silent remote connections, among other things. Specifically, it will make destructive changes to the profile that are required for web-ext to operate.

Packaging your extension

Once you've tested your extension and verified that it's working, you can turn it into a package for submitting to addons.mozilla.org using the following command:

web-ext build

This will output a full path to the generated .zip file that can be loaded into a browser.

The generated .zip file doesn't work on Firefox without signing it, or adding applications.gecko.id key into manifest.json. For more information, please refer WebExtensions and the Add-on ID page.

web-ext build is designed to automatically ignore files that are commonly unwanted in packages, such as .git, node_modules, and other artifacts.

See the build reference guide to learn more.

Signing your extension for distribution

As an alternative to publishing your extension on addons.mozilla.org, you can self-host your package file but it needs to be signed by Mozilla first. The following command packages and signs a ZIP file, then returns it as a signed XPI file for distribution:

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

The API options are required to specify your addons.mozilla.org credentials.

  • --api-key: the API key (JWT issuer) from addons.mozilla.org needed to sign the extension. This should always be a string.
  • --api-secret: the API secret (JWT secret) from addons.mozilla.org needed to sign the extension. This should always be a string.

See the sign reference guide to learn about all available options.

Signing extensions without an explicit ID

web-ext fully supports signing extensions that do not declare the applications.gecko.id property in their manifest. The first time you sign an extension without an explicit ID, addons.mozilla.org will auto-generate an ID and web-ext will save it to .web-extension-id in the current working directory. You should save the ID file so that you can sign future versions of the same extension. If you lose the ID file, you will have to add back the applications.gecko.id property or use the --id option when signing future versions, for example:

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

Signing in a restricted environment

If you are working in an environment that restricts access to certain domains, you can try using a proxy when signing:

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

Read more about --api-proxy for details.

If you simply need to allow the domains used for signing and downloading files, allow these:

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

Checking for code "lint"

Before trying out your extension with the run command or submitting your package to addons.mozilla.org, you can use the lint command to make sure your manifest and other source files do not contain any errors. Example:

web-ext lint

This uses the addons-linter library to walk through your source code directory and report any errors, such as the declaration of an unknown permission.

See the lint reference guide to learn about all available options.

Specifying different source and destination directories

The above commands all use default directories for the extension source and artifact creation (e.g. built .zip files). The defaults are:

  • Source: The directory you are currently inside.
  • Artifacts: A directory called ./web-ext-artifacts, created inside the current directory.

You can specify different source and destination directories using the --source-dir (or -s alias) and --artifacts-dir (or -a alias) options when running your commands. Their values can be relative or absolute paths, but must always be specified as strings. Here is an example of specifying both options at the same time when building an extension:

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

Outputting verbose messages

If you want to see exactly what web-ext is doing when you run a command, you can include the --verbose option (or the -v alias). For example:

web-ext build --verbose

Viewing all commands and options

You can list all commands and options like this:

web-ext --help

Note: You can also use the -h alias.

You can list options for a specific command by adding it as an argument:

web-ext --help run

See also

Étiquettes et contributeurs liés au document

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