Revision 1081120 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. You must use <code>npm</code> greater than 3.0.0 to install <code>web-ext</code>. Run the command <code>npm --version</code> to check what you have and upgrade it by running this in your terminal:</p>

<pre>
<code>npm install --global npm</code></pre>

<div class="note">
<p>If you're on Windows, you'll need to <a href="https://github.com/npm/npm/wiki/Troubleshooting#upgrading-on-windows">follow these instructions</a> to complete the npm upgrade.</p>
</div>

<p>Next, 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 out in the default Firefox version/profile on your machine 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>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 in Firefox immediately. If you run into trouble 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>

<h3>Testing in different versions of Firefox</h3>

<p>The <code>run</code> command starts up your default version of Firefox. To run a different version, pass the full path to the binary file in the <code>--firefox-binary</code> option. 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>Using a custom profile</h3>

<p>By default, the <code>run</code> command will create a temporary profile. You can run Firefox 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.</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. It is designed to automatically ignore files that are commonly unwanted in packages, such as <code>.git</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 about all options.</p>

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

<p>You can also self-host your ZIP 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</code></pre>

<p>The above however isn't enough. You also need to provide two options:</p>

<ul>
 <li><code>--api-key</code>: Required to provide 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>: Required to provide 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>For example:</p>

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

<div class="note">
<p><strong>Note</strong>: You can also specify the signing API URL prefix needed to sign the extension using the <code>--api-url-prefix</code> option, if you need to use a different one. If not specified, this will default to&nbsp;<code>https://addons.mozilla.org/api/v3</code>.</p>

<p><strong>About XPIs</strong>: XPIs are simply ZIP files signed by Mozilla's Add-ons signing API. They can be installed in Firefox without signing errors.</p>
</div>

<h3 id="--api-url-prefix">--api-url-prefix</h3>

<p>When using <code>web-ext sign</code>, this option provides the signing API URL prefix needed to sign the extension. If not specified, this will default to&nbsp;<code>https://addons.mozilla.org/api/v3</code>. This should always be a string.</p>

<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 --artifacts-dir=zips --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>