webext-buildtools-firefox-addons-builder

Introduction

webext-buildtools builder which allows you to deploy extension (packed to zip) to Firefox Addons, and sign xpi file (for offline distribution).

Installation

npm install webext-buildtools-firefox-addons-builder

Purpose

Builder uses Firefox Addons API to deploy your extension and/or get signed crx file for offline distribution (read "Signing and distributing your add-on" for details).

Builder doesn't allow to publish new extension, only update existing (deploy.extensionId in options) with new version.

Usage example

const FirefoxAddonsBuilder = require('webext-buildtools-firefox-addons-builder').default;
const fs = require('fs-extra');

const options = { ... }; // see description below
const logMethod = console.log;
const builder = new FirefoxAddonsBuilder(options, logMethod);

// Optional, can be extracted from zip
builder.setInputManifest(await fs.readJson('./ext_dir/package.json'));
builder.setInputZipBuffer(await fs.read('./packed.zip'));

builder.requireDeployedExt();
builder.requireSignedXpiFile();

const buildResult = await builder.build();

Options

Options object described in declarations/options.d.ts

See how to get logMethod for pretty output.

Api access

To set up API access you need to generate and specify jwtIssuer, jwtSecret in options.api. You can create them at https://addons.mozilla.org/en-US/developers/addon/api/key/

Inputs

🔸 extension zip archive; Required

Can be set using one of the following inputs:

1. setInputZipBuffer(buffer: Buffer)

Buffer with zipped extension dir.

2. setInputZipFilePath(filePath: string)

Buffer with zipped extension dir.

3. setInputUploadId(uploadId: string) Only for "Deployed extension" output

Id of existing upload. Can be used if uploading succeeded at the previous try, but polling failed by timeout and version hasn't been published.

🔹 setInputManifest(...) Only for "Signed xpi" output

Object with parsed extension's package.json. Will be extracted from zip if not specified.

🔹 sources archive

It's needed for admins for a review if your zipped extension contains minified code. Can be set using one of the following inputs:

1. setInputSourcesZipBuffer(buffer: Buffer)

Buffer with zipped dir containing source code of the extension.

2. setInputSourcesZipFilePath(filePath: string)

Path to zip containing source code of the extension.

You can use webext-buildtools-dir-reader-mw to generate needed inputs from extension directory.

Outputs

Deployed extension

Require to deploy extension to Firefox Addons

Required options: deploy.extensionId, api
Require methods: requireSignedXpiFile()
Assets:
const xpiFilePath = buildResult.getAssets().signedXpiFile.getValue()
const xpiBuffer = buildResult.getAssets().signedXpiBuffer.getValue()
const extId = buildResult.getAssets().signedExtStoreId.getValue()

Signed xpi file

Require to get signed xpi file. This output is independent of deployed extension. options.signXpi.extensionId should contain id of extension uploaded to Firefox Addons especially for offline distribution. If not specified, new extension will be added for every build (not recommended)

Required options: signXpi.extensionId (recommended), signXpi.xpiOutPath (if not temporary file required), apiAccess

Require methods: requirePublishedExt()
Assets: const extId = buildResult.getAssets().deployedExtStoreId.getValue()

Errors

Package exports the following error classes, which can be thrown:

• VersionAlreadyExistsError if you try to upload already existing version
• UnauthorizedError: For "Deployed extension" output. jwtIssuer, jwtSecret Options are invalid.
• ValidationError For "Deployed extension" output. Firefox Addons validation rejected your extension
• PollTimedOutError For "Deployed extension" output. Polling uploaded item status was timed out. Your extension will be probably published later.
• RequestThrottled API request were declined because you reached the request frequency limit.

All these custom errors have AddonsApiError base class that contain the following properties:

• version: string|undefined: extension version if known at the moment error occurred
• uploadId: string|undefined: id of upload if known at the moment error occurred

References

If you are interested in building CI/CD solution for Web Extension using GitHub Actions it's better to use the dedicated actions for it instead.

Please read the "Releasing WebExtension using GitHub Actions" article to learn the details.

If you need to deploy to other targets, take a look at webext-buildtools-integrated-builder repo.

To read what are webext-buildtools and builders go to webext-buildtools-builder-types repo.

sign-addon package is used for signing under the hood.