web-ext TypeScript template

A template for creating Web Extensions using TypeScript

What's included

• TypeScript (obviously) with @types/firefox-webext-browser for typings.
• Rollup for bundling.
• web-ext for running, building and signing.
• Vitest with jsdom for testing.
• ESLint, typescript-eslint, Prettier and lint-staged for linting.
• A continuous integration workflow that runs linting and tests.
• A workflow for publishing to addons.mozilla.org (AMO).
• A Renovate config for keeping dependencies up-to-date.

Getting started

1. Create a repository from this template.
2. Clone your copy of the repository.
3. If you have mise, run mise install. If not, install Node.js and pnpm.
4. Install the dependencies:

   pnpm install   

5. If you are planning on supporting Chromium-based browsers, now is a good time to install webextension-polyfill and @types/webextension-polyfill.
6. Update manifest.json and rollup.config.js according to your needs.
7. Happy coding!

Developing

Running in a browser with live-reload

The dev script (executed with pnpm dev) watches for code changes and automatically re-compiles and reloads the extension. To specify a profile, a specific version of Firefox or to debug on Android, follow the documentation on web-ext run.

Building

Tip

If you have mise installed, executing mise run build will run every task described bellow.

Warning

Keep in mind that if you plan on publishing your web extension to addons.mozilla.org (AMO), you will be asked to provide source code and instructions to reproduce the build!

1. Install dependencies:

   pnpm install --frozen-lockfile

2. Compile the TypeScript files and bundle them:

   pnpm bundle

3. Build the extension using web-ext:

   pnpm build

Running tests

pnpm test

Publishing on addons.mozilla.org

This template comes with a GitHub Action workflow for publishing on addons.mozilla.org (AMO). It also automatically creates a GitHub release based on information from manifest.json and metadata.json.

Important

Make sure that you add an extension ID in manifest.json, especially when publishing an update: otherwise AMO will reject it.

Beforehand, you must create API keys and add them as GitHub Action environment variables: AMO_API_KEY for the JWT issuer, and AMO_API_SECRET for the JWT secret.

Then, publishing takes the following steps:

1. Update the version number in manifest.json.
2. Update metadata.json following the documentation. In the case of add-on updates, the only required fields are the ones already present in the base template, plus version.release_notes.

   [!IMPORTANT] By default, the workflow is expecting a key for "en-GB" under version.release_notes to fill the GitHub release. Make sure to update the workflow step "Get release notes" accordingly.

3. Once set, manually run the workflow.