Skip to content

Technical Overview

Jump to bottom
Michal Stanke edited this page Jan 1, 2023 · 30 revisions

System requirements for developers

  • Linux (macOS and WSL should also work)
  • Node.js (see the engines section in package.json for the exact version), or Podman/Docker
  • Make (optional, but highly recommended)

The add-on itself is of course platform independent and is available to all browser listed here.

Languages and frameworks

Tools

Building the add-on

The add-on can be built locally with Make and Node.js, or in a container with Make and Podman/Docker.

  • make/make all/make all_in_container re-installs all dependencies, runs all tests and builds the add-on.
    • Run this command the first time you clone this project, or when you suspect the project got broken.
  • make prepare/make prepare_in_container re-installs all dependencies.
    • Run this command whenever there are any updated dependencies.
  • make build/make build_in_container runs code style checks and builds the add-on into ./dist//web-ext folders.
    • Run to build the add-on.
  • make test/make test_in_container runs all tests.
    • Run to verify CI.
  • make watch/make watch_in_container re-builds the add-on source code every time it changes.
    • Use for development. In Firefox about:debugging, load the add-on by selecting dist/mozilla/src/manifest.json.

Without Make, there are equivalent npm run commands, except for make all.

For extreme cases

  • git clean -fdX cleans all extra files not tracked in the repository, including all dist artifacts and node_modules folders.

GitHub Actions (CI)

  • make build_in_container && make test_in_container is run for all PRs and also in the default repository branch. For tagged (release) commits artifacts are also uploaded to GitHub Releases.

Architecture overview

Pontoon Add-on uses WebExtension API. The general anatomy of WebExtensions is best described on MDN. In the Pontoon Add-on source code, individual files (and JavaScript classes) are organized into subfolders based on the related feature and context they run in.

WebExtension contexts

All contexts of a WebExtension are defined in central manifest.json. You can imagine each context like a HTML website with some CSS and JS included + some extra WebExtensions API available.

Background page

  • Scripts in the background page run the whole time Firefox is open and the add-on is installed and enabled. Registration of elements that are direct part of the browser UI (toolbar button, address bar button) or data updates are happening here.

Browser action

  • Browser action is the popup, that opens when you click the toolbar button. All scripts live only when the popup is opened. Closing it is like closing a tab with a regular website - all scripts are terminated.

Page action

  • Page action is the popup, that opens when you click the icon in the address bar. The lifespan is the same here as for the browser action.

Options page

  • The add-on options page is accessible from the toolbar button context menu or via add-ons manager.

Content scripts

  • Content scripts are injected into regular websites loaded in browser tabs, where they have the same access to the page as any JavaScript, that is part of it, but can also communicate via messages with the code running in the background context.
Clone this wiki locally