TinyWebEx

The TinyWebEx modules are a collection of ES6 JavaScript modules for WebExtensions, also called add-ons in the Mozilla world. They make common tasks you need to do in your add-on simpler without requiring you to ship with a lot of dependencies (that's why we call them tiny). This is also made possible, because we do not support older browsers. They are also well-tested with unit tests and in real world.

Usually, you can also use all modules independently of each other, but sometimes they have to depend on each other for obvious reasons.

A full JSDOC documentation and human-readable overview documentation is also available for each add-on.

Overview

• CommonCss – Some common CSS files for styles throughout the add-on and other modules.
• AddonSettings – Retrieve and save your add-on settings easier, providing default values and managed options.
• AutomaticSettings – Define all your settings for your options in HTML and they are automatically loaded and saved on each change. Supports everything which AddonSettings supports, too. (default options, managed options)
• BrowserCommunication – module for showing messages of all sort, supports pre-defined or custom message types.
• Localizer – Easily translate the whole HTML of your browser extension.
• Logger – A custom console.log replacement (overwrite possible) to add more details etc.
• MessageHandler – module for showing messages of all sort, supports pre-defined or custom message types.
• RandomTips – module for showing an unobtrusive random tip to the user, depends on MessageHandler.

Special repos

There are also these special repos:

• this repo here – containing common files for add-ons or the TinyWebEx project.
• AddonTemplate – a template for a new add-on to quickly get started
• TinyWebEx-UnitTests – a collection (git submodules) of all modules to easily unit-test all of them
• TestHelper – small scripts (helpers) only used for/in unit tests

Third-party dependencies

Also, we sometimes depend on lodash. However, really, only rarely, and only some hand-picked modules that are also recommend to be included manually (the few modules it needs, not all of lodash).

You can usually always use the master branch of lodash. Unfortunately, these modules need to be copied by hand. (TODO: maybe make an own repo with all needed ones)

What lodash modules may be used is documented with JSDoc

Getting started

If you want to create a new add-on, there is a whole template for it: AddonTemplate

If you want to include them in your add-on, best is to create a dir (I use common/modules.), where you can clone all repositories into. Then, your directory structure in there e.g. looks like this:

.
├── AddonSettings
│   ├── AddonSettings.js
│   ├── CONTRIBUTORS
│   ├── LICENSE.md
│   └── README.md
├── data
│   ├── ...
│   └── DefaultSettings.js
...

We actually recommend to use git submodules. See the paragraph below on why you need to do so.

Each module defines in their Readme, how to include and use it.

What you need to know

Due to the way we use static ES6 modules, there are some inconveniences I have to make you aware of:

• Many modules depend on each other, and you need to manually clone them into the right location. (It's easy, as it is) We recommend to use git submodules.
• Likewise, many modules depend on some data you add as a developer. This is also always documented in the corresponding module, but you usually just drop a JS file in the https://github.com/TinyWebEx/data dir (seen from the module).
• We use the standardized APIs, as supported by Firefox. Possibly you need to use this polyfill to support other browsers.
• Similarly (especially for CSS), we follow the Firefox guides, e.g. the Firefox photon design guide.
• Usually, we require at least Firefox 60. (but each repo contains a manifest.json that lists all requirements, including permissions and minimum Firefox version.
• We sometimes depend on/require lodash, see the section on “third-party dependencies”.

Users

These modules are used in production by several add-ons.

Most notably:

• Offline QR Code Generator
• Awesome Emoji Picker
• Mastodon Simplified Federation
• Dark Mode Website Switcher

As such, I re-use things like the CONTRIBUTING.md in their, respectively link to it.