Revision 1084283 of Getting started with web-ext

<div>{{AddonSidebar}}</div>

<p class="summary">web-ext is a command line tool designed to speed up various parts of the WebExtension development process, making development faster and easier. This article explains how to install and use web-ext.</p>

<h2 id="Installation">Installation</h2>

<p>web-ext is a node-based application that you can install with the <a href="https://nodejs.org/">nodejs/npm</a> tool. Install web-ext using the following command:</p>

<pre class="brush: bash">
<code>npm install --global web-ext</code></pre>

<p>You can test whether your installation worked by running the following command, which lists the installed web-ext version number:</p>

<pre class="brush: bash">
<code>web-ext --version</code></pre>

<h2 id="Using_web-ext">Using web-ext</h2>

<p>Once you've installed it, you can test web-ext out. At this point, it is a good idea to have a sample WebExtension to try it out on — if you don't have one of your own, you can clone our <a href="https://github.com/mdn/webextensions-examples">webextensions-examples</a> repo.</p>

<h3 id="Testing_out_an_extension">Testing out an extension</h3>

<p>You can test an extension in Firefox by <code>cd</code>'ing into your extension's root directory and entering the following command:</p>

<pre class="brush: bash">
<code>web-ext run</code></pre>

<p>This will start up Firefox and load the extension temporarily in the browser, just like you could on the <a href="/en-US/docs/Tools/about:debugging#Add-ons">about:debugging page</a>.</p>

<p>See the <a href="/en-US/Add-ons/WebExtensions/web-ext_command_reference#web-ext_run">run reference guide</a> to learn about all available options.</p>

<h3 id="Automatic_extension_reloading">Automatic extension reloading</h3>

<p>The <code>run</code> command will watch your source files and tell Firefox to reload the extension after you edit and save a file. For example, if you changed the <code>name</code> property in your <code>manifest.json</code> file, Firefox would display the new name. This makes it easy to try out new features and see them immediately. If you run into unexpected behavior with the reloading feature, please <a href="https://github.com/mozilla/web-ext/issues">file a bug</a>. You can also disable reloading like this:</p>

<pre class="brush: bash">
<code>web-ext run --no-reload</code></pre>

<div class="note">
<p>Extension reloading is only supported in Firefox 49 or higher.</p>
</div>

<h3 id="Testing_in_different_versions_of_Firefox">Testing in different versions of Firefox</h3>

<p>To run your extension in a version of Firefox other than the default, use the <code>--firefox-binary</code> option to specify a full path to the binary file. Here is an example on Mac OS:</p>

<pre class="brush: bash">
web-ext run --firefox-binary=/Applications/FirefoxNightly.app/Contents/MacOS/firefox-bin</pre>

<p>On Windows, the path needs to include the <code>firefox.exe</code> part, for example:</p>

<pre class="brush: bash">
web-ext run --firefox-binary="C:\Program Files\Mozilla Firefox\firefox.exe"</pre>

<h3 id="Testing_in_Firefox_48">Testing in Firefox 48</h3>

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

<pre class="brush: bash">
web-ext run --pre-install</pre>

<h3 id="Using_a_custom_profile">Using a custom profile</h3>

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

<pre class="brush: bash">
web-ext run --firefox-profile=chris-work-profile</pre>

<p>This option accepts a string containing the name of your profile or an absolute path to the profile directory.</p>

<div class="note">
<p>When using a custom profile, <code>web-ext</code> first copies the profile. The custom profile will not be altered.</p>
</div>

<h3 id="Packaging_your_extension">Packaging your extension</h3>

<p>Once you've tested your extension and verified that it's working, you can turn it into a package for submitting to <a href="https://addons.mozilla.org">addons.mozilla.org</a> using the following command:</p>

<pre class="brush: bash">
<code>web-ext build</code></pre>

<p>This will output a full path to the generated <code>.zip</code> file that can be loaded into a browser. It is designed to automatically ignore files that are commonly unwanted in packages, such as <code>.git</code>, <code>node_modules</code>, and other artifacts.</p>

<p>See the <a href="/en-US/Add-ons/WebExtensions/web-ext_command_reference#web-ext_build">build reference guide</a> to learn more.</p>

<h3 id="Distributing_your_own_WebExtension">Distributing your own WebExtension</h3>

<p>You can also self-host your package file for distribution but it needs to be <a href="https://developer.mozilla.org/Add-ons/Distribution" target="_blank">signed by Mozilla</a> first. The following command packages and signs a ZIP file, then returns it as a signed XPI file for distribution:</p>

<pre class="brush: bash">
<code>web-ext sign --api-key=yourapikey --api-secret=yourapisecret </code></pre>

<p>The API options are required to specify your <a href="https://addons.mozilla.org/en-US/developers/addon/api/key/">addons.mozilla.org credentials</a>.</p>

<ul>
 <li><code>--api-key</code>: the API key (JWT issuer) from <code>addons.mozilla.org</code> needed to sign the extension. This should always be a string.</li>
 <li><code>--api-secret</code>: the API secret (JWT secret) from <code>addons.mozilla.org</code> needed to sign the extension. This should always be a string.</li>
</ul>

<p>See the <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/web-ext_command_reference#web-ext_sign">sign reference guide</a> to learn about all available options.</p>

<h3 id="Signing_extensions_without_an_explicit_ID">Signing extensions without an explicit ID</h3>

<p><code>web-ext</code> fully supports signing extensions that do not declare the <a href="/en-US/Add-ons/WebExtensions/manifest.json/applications">applications.gecko.id</a> property in their manifest. The first time you sign an extension without an explicit ID, <a href="https://addons.mozilla.org/">addons.mozilla.org</a> will auto-generate an ID and <code>web-ext</code> will save it to <code>.web-extension-id</code> 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 <code>applications.gecko.id</code> property or use the <code>--id</code> option when signing future versions, for example:</p>

<pre class="brush: bash">
<code>web-ext sign --api-key=... --api-secret=... --id="</code>{c23c69a7-f889-447c-9d6b-7694be8035bc}<code>"</code></pre>

<h3 id="Specifying_different_source_and_destination_directories">Specifying different source and destination directories</h3>

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

<ul>
 <li>Source: The directory you are currently inside.</li>
 <li>Artifacts: A directory called <code>./web-ext-artifacts</code>, created inside the current directory.</li>
</ul>

<p>You can specify different source and destination directories using the <code>--source-dir</code> (or <code>-s</code> alias) and <code>--artifacts-dir</code> (or <code>-a</code> 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&nbsp; building an extension:</p>

<pre class="brush: bash">
<code>web-ext build --source-dir=webextension-examples/notify-link-clicks-i18n --artifacts-dir=zips</code></pre>

<h3 id="Outputting_verbose_messages">Outputting verbose messages</h3>

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

<pre class="brush: bash">
<code>web-ext build --verbose</code></pre>

<h3 id="Viewing_all_commands_and_options">Viewing all commands and options</h3>

<p>You can list all commands and options like this:</p>

<pre class="brush: bash">
<code>web-ext --help</code></pre>

<div class="note">
<p><strong>Note</strong>: You can also use the <code>-h</code> alias.</p>
</div>

<p>You can list options for a specific command by adding it as an argument:</p>

<pre class="brush: bash">
<code>web-ext --help run</code></pre>

<h2 id="See_also">See also</h2>

<ul>
 <li><a class="external external-icon" href="https://github.com/mozilla/web-ext">web-ext repo</a></li>
 <li>
  <p><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/web-ext_command_reference">web-ext command reference</a></p>
 </li>
</ul>