この翻訳は不完全です。英語から この記事を翻訳 してください。

web-ext は、機能拡張の開発プロセスの多くを加速するために設計されたコマンドラインツールであり、開発を速く簡単にします。この記事では web-ext をインストールして使用する方法を説明します。

インストール

web-ext は nodejs/npm ツールからインストールできる node ベースのアプリです。下記のコマンドで web-ext をインストールします:

npm install --global web-ext

web-ext は NodeJS の最新の LTS (long term support) バージョンを要求します。

インストールできたかどうかは、web-ext のバージョン番号を表示する下記コマンドを実行してテストできます:

web-ext --version

web-ext を使ってみる

いったんインストールできたら、 web-ext をテストできます。ここでは、簡単な機能拡張を試してみるのがいいでしょう — 自作のものがない場合、我々の webextensions-examples リポジトリをクローンできます。

機能拡張をテストする

Firefox で機能拡張をテストするには機能拡張のルートディレクトリに cd(移動) して、下記コマンドを入力します:

web-ext run

これで Firefox が起動して機能拡張が一時的にブラウザーに読み込まれます。これはabout:debugging のページでできるのと同じように。

利用できる全オプションについては run リファレンスガイドを見てください。

自動的な機能拡張リロード

run コマンドではソースファイルを監視して、編集・保存後に Firefox にリロードさせます。例えば、manifest.json ファイルの中の name プロパティを変更した場合、Firefox は新しい名前を表示します。これにより、新機能を試したり、その結果をすぐに見る事ができます。自動的なリロード機能は既定でオンになっていて、このように使えます:

web-ext run

web-ext ターミナルから r キーを押して、機能拡張を手動で読み込むようにもできます。

リロードした機能が期待していない振る舞いをしたら、バグを提出してください。次のようにリロードをオフにもできます:

web-ext run --no-reload

拡張機能のリロードは Firefox 49 以降のみでサポートされます。

色々なバージョンの Firefox でテストする

デフォルトバージョン以外の デスクトップ版 Firefoxで機能拡張を実行するには --firefox オプションでバイナリーファイルのフルパスを指定します。Mac OS の例はこちら:

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

Windows では、パスに firefox.exe の部分を入れる必要があります、例えば:

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

利用できる全オプションについては run リファレンスガイドを見てください。

Firefox 48 でテストする

Firefox 48 は WebExtension プラットホームに使う最初の安定版ですが、リモートで web-ext による機能拡張のインストールが許可されていません。Firefox で機能拡張を実行するには、別のインストールオプションを付けます:

web-ext run --pre-install

Android 版 Firefox でテストする

Android用Firefoxで拡張機能を実行するには、デバイスにFirefoxをインストールし、開発用デバイスを設定し、web-extを実行しているコンピュータに接続していることを確認します。

開始するには、この基本的なコマンドを実行します。

web-ext run --target=firefox-android

This will prompt you to select your Android device and it will provide a list of connected devices. If you don't see a list of devices, make sure you had set up the device for development as explained above.

Once you know the device ID, add it to the command:

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

If you have multiple versions of Firefox installed, you may need to choose a specific version. Example:

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

The first time you run this command, you may also need to grant Android permissions for the APK. Specifically, the command needs read / write access to device storage so that Firefox for Android can run on a temporary profile. The web-ext output will guide you in how to grant these permissions.

The web-ext command will not alter any of your existing Firefox for Android preferences or data. If you'd like to see more information about how web-ext is interacting with your device, run the command with --verbose.

See the run command reference for all available options.

Android 版 Firefox でデバッグする

While using web-ext run to test an extension on Firefox for Android, you'll notice a message like this in the console output:

You can connect to this Android device on TCP port 51499

This is a remote debugger port that you can connect to with Firefox's developer tools. In this case, you'd connect to host localhost on port 51499.

See this guide for more information about debugging an extension on Firefox for Android.

署名なしの機能拡張をテストする

web-ext run を実行するとき、 機能拡張は Firefox を閉じるまで一時的にインストールされます。これは署名についての制限に違反しません。この代わりに web-ext build で Firefox にインストールする zip ファイルを作る場合、アドオンが署名されていないエラーが出るでしょう。署名なしの機能拡張をインストールするには unbranded builddevelopment build を使います。

カスタムプロフィールを使う

規定では、run コマンドは一時的な Firefox プロファイルを作成します。--firefox-profile オプションを使うと特定のプロファイルにて実行できます、次のように:

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

このオプションはプロファイル名を含んだ文字列か、プロファイルディレクトリーの絶対パスを受け付けます。これは run コマンドでいつも使える設定を手動で調整したい場合に役立ちます。

プロフィールを変更したままにする

run コマンドは --firefox-profile で指定されたカスタムプロファイルへの変更は保存しません。変更を保存しておくには、次のオプションを追加します:

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

拡張機能がいくつもの実行ステータスを持つ場合に役立ちます。

このオプションは --firefox-profile で指定されたプロファイルを、日常使用するには完全に危険なものにします。自動更新を切って、とりわけ、黙ってリモート接続を許可します。厳密には、 web-ext の操作で要求されるとプロファイルに破壊的変更を行います。

機能拡張をパックする

拡張機能のテストが完了して動作が検出されたら addons.mozilla.org に提出するために次のコマンドでパッケージに変換します:

web-ext build

これは生成された .zip ファイルのフルパスを出力し、それをブラウザーに読み込みます。

生成された .zip ファイルは署名またはapplications.gecko.id キーを manifest.json. に追加しないと Firefox で動作しません。より詳しい情報はWebExtensions and the Add-on ID ページを参照してください。

web-ext build はパッケージにふさわしくないファイル、例えば .git, node_modules,その他の中間ファイルを自動的に無視するよう設計されています。

もっと学ぶには ビルドリファレンスガイドを見てください。

配布のために機能拡張に署名する

addons.mozilla.org で拡張機能を配布ふるのと別の手として、自身でパッケージファイルをホストできますが、まず Mozilla に署名してもらう必要があります。次のコマンドで ZIP ファイルのパッケージと署名ができて、配布用の署名付き XPI ファイルが返ります:

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

addons.mozilla.org の秘密情報指定するのに API オプションが要求されます

  • --api-key: addons.mozilla.org API キー (JWT issuer) が拡張機能の署名に必要です。これは user:12345:67 のような文字列です。
  • --api-secret: addons.mozilla.org API シークレット (JWT secret)が拡張機能の署名に必要です。これは次のような文字列です。 634f34bee43611d2f3c0fd8c06220ac780cff681a578092001183ab62c04e009

利用できる全オプションについては sign リファレンスガイドを見てください。

明示的な ID なしに機能拡張に署名する

web-ext はマニフェストに applications.gecko.id プロパティを宣言していない拡張機能の署名をフルサポートします。明示的な ID なしに拡張機能に初めて署名するとき、addons.mozilla.org は ID を自動生成し、web-ext は現在の作業ディレクトリーの .web-extension-id にそれを保存します。同じ拡張機能の将来のバージョンに署名するには、この ID を保存しておきます。ID ファイルをなくしたら、将来のバージョンに署名するには applications.gecko.id プロパティをつけるか、--id オプションを使わねばなりません。例えば:

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

限定環境にて署名する

あるドメインにアクセスするのに限定された環境で作業している場合、署名するのにプロキシーを使ってみます:

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

詳しく学ぶには --api-proxy を見てください。

下記のドメインがファイルの署名とダウンロード用に使われます:

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

コードの "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.

Setting option defaults in a configuration file

You can specify --config=my-config.js to set default values for any option. Here is an example with the build command:

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

The file should be a CommonJS module as understood by NodeJS and must export each configuration value. Here is how you would set the default value of --verbose to true:

module.exports = {
  verbose: true,
};

If you want to specify options that only apply to a specific command, you would nest the configuration under the command name. Here is an example of adding configuration for --overwrite-dest which only applies to the build command as well as --firefox which only applies to the run command:

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

To create a configuration key for a command line option, you remove the preceding dashes and convert the name to camel case. As you can see from this example, --overwrite-dest was converted to overwriteDest.

If an option can be specified multiple times on the command line then you can define it as an array. For example, here is how to specify multiple --ignore-files patterns:

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

Automatic discovery of configuration files

For convenience, web-ext will load existing configuration files in the following order:

  • A config file named exactly .web-ext-config.js in your home directory
    • Example on Windows: C:\Users\<username>\.web-ext-config.js
    • Example on macOS: /Users/<username>/.web-ext-config.js
    • Example on Linux: /home/<username>/.web-ext-config.js
  • A config file named exactly web-ext-config.js in the current directory

If both a home directory config and a local directory config define the same option, the value from the latter file will be used.

To disable automatic loading of configuration files, set this option:

web-ext --no-config-discovery run

To diagnose an issue related to config files, re-run your command with --verbose. This will tell you which config file affected which option value.

色々なソース・ディストネーションディレクトリーを指定する

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

冗長なメッセージを出力する

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

全てのコマンドオプションを見る

You can list all commands and options like this:

web-ext --help

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

web-ext --help run

一時的なインストールを検出する

Your extension can detect whether it was installed using "web-ext run" rather than as a built and signed extension downloaded from addons.mozilla.org. Listen for the runtime.onInstalled event, and check the value of details.temporary.

スクリプトから web-ext を使用する

You can use web-ext as a NodeJS module. Here is more information with example code.

関連情報

ドキュメントのタグと貢献者

このページの貢献者: silverskyvicto, Uemmra3, kyokutyo
最終更新者: silverskyvicto,