{"id":14040973,"url":"https://github.com/thunderbird/webext-experiments","last_synced_at":"2025-06-14T06:05:31.991Z","repository":{"id":38391935,"uuid":"146595551","full_name":"thunderbird/webext-experiments","owner":"thunderbird","description":"WebExtension Experiments for Thunderbird","archived":false,"fork":false,"pushed_at":"2025-04-13T13:55:48.000Z","size":146,"stargazers_count":31,"open_issues_count":13,"forks_count":15,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-06-08T21:11:34.494Z","etag":null,"topics":["thunderbird","webextension-experiment","webextensions"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thunderbird.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-08-29T12:19:56.000Z","updated_at":"2025-04-13T13:55:52.000Z","dependencies_parsed_at":"2025-04-13T14:30:59.743Z","dependency_job_id":"bdc4f1b1-da65-41b8-8df6-f151cdb3a80d","html_url":"https://github.com/thunderbird/webext-experiments","commit_stats":null,"previous_names":["thunderbird/tb-web-ext-experiments","thunderbird/webext-experiments"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/thunderbird/webext-experiments","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thunderbird%2Fwebext-experiments","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thunderbird%2Fwebext-experiments/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thunderbird%2Fwebext-experiments/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thunderbird%2Fwebext-experiments/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thunderbird","download_url":"https://codeload.github.com/thunderbird/webext-experiments/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thunderbird%2Fwebext-experiments/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259768605,"owners_count":22908229,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["thunderbird","webextension-experiment","webextensions"],"created_at":"2024-08-12T06:01:46.470Z","updated_at":"2025-06-14T06:05:31.969Z","avatar_url":"https://github.com/thunderbird.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"Thunderbird WebExtension Experiments\n====================================\nThunderbird is providing APIs similar to Firefox's WebExtensions. There is overlapping API for commonly\nused elements like windows and tabs, but there also have to be Thunderbird-specific APIs, for example\nto provide access to E-Mails or Calendar. These APIs are sometimes referred to as *MailExtension APIs*.\nThere is an ongoing effort to integrate more such APIs into Thunderbird.\n\nExperiment APIs are WebExtension APIs whose implementation is part of the add-on, enabling features\nwhich are not yet provided by Thunderbird's own APIs. This repository provides Experiments which\ncould be useful to add-on developers. These Experiments also serve as examples for add-on developers\nwanting to create their own APIs.\n\nFurthermore, this repository tracks progress of Experiments, which aim to be added to Thunderbird.\n\nAPI Experiments\n---------------\nThe following WebExtension Experiments are available in this repository.\n\n| Name                                  | Author                                      | Description\n| ------------------------------------- | ------------------------------------------- | --------------\n| [calendar](./calendar/)               | [@kewisch](https://github.com/kewisch/)     | Draft for calendar-related APIs in Thunderbird\n| [NotificationBox](./NotificationBox/) | [@jobisoft](https://github.com/jobisoft/)   | Draft for an API to show notifications inside Thunderbird\n\n\nContributions Welcome!\n----------------------\nWe would like to encourage add-on developers to contribute their APIs, so they can be discussed to\nbecome part of core Thunderbird.\n\nWhen creating a new API, please start with [the documentation on WebExtension\nExperiments](https://developer.thunderbird.net/add-ons/mailextensions/experiments). You can also read\nthe code of already implemented [Thunderbird\nWebExtension APIs](https://searchfox.org/comm-central/source/mail/components/extensions/), which will\nprovide further examples.\n\nIf you have an idea for an API that you think would be worthwhile, please file an issue on this\nrepository. We are open to general ideas, but if you have a suggestion for specific API methods and\nevents we would also enjoy your input. Please make sure to read the design principles when filing a\nnew issue.\n\n### Design Principles\nWebExtension APIs are meant to provide a stable API for add-on developers to use, while at the same\ntime hiding the details and allowing the Thunderbird team to clean up and change the underlying\ncode. The following principles should be kept in mind when devising new APIs:\n\n* The APIs should not expose Thunderbird features that are too specific, or subject to change.\n  Providing WebExtension APIs is a long term commitment.\n\n* The APIs should be very high level. We are looking for \"access to address books and cards\", not\n  \"access to the xpcom address book service and its technical properties\".\n\n* APIs should not rely on technical implementation details of the underlying XPCOM components. There\n  should be no magic numbers (use constant ls and enums), and try to anticipate how future additions\n  would be least disruptive to the existing API.\n\n* The UI exposed to WebExtensions should be limited to properties we can support long term, and are,\n  if possible, easy to separate. A sidebar or toolbar button is perfect, adding arbitrary content to\n  the message header not so much.\n\n* To extend the previous point, we'd like to be careful when replacing built-in UI. A button in the\n  quick search toolbar is great, but replacing the whole quick search bar with custom UI would need\n  a special mechanism (like `chrome_settings_override`) and it should be evaluated if there isn't a\n  better way to achieve the same result.\n\n### Submitting a Pull Request\nGenerally it is a good idea to file an issue to discuss your API first. If you've already done so or\nwould like to submit your API experiment for inclusion in this repository, please make sure you have\ncompleted the following:\n\n* The API follows the design principles laid out in this README.\n* The API code must be made available under the terms of the\n  [Mozilla Public License 2.0](https://www.mozilla.org/en-US/MPL/2.0/).\n* The API code is contained in a sub directory and passes the linters.\n* There is a reference to the API in this README file, along with a short description.\n\nTo run the linters, follow these steps\n```bash\nnpm install\nnpm run lint\n\n# To add arguments to eslint you need to double the -- to separate arguments\n# This command will fix any eslint issues that can be fixed automatically\nnpm run lint -- --fix\n```\n\nEach experiment should also contain this table to summarize common information. Not everything needs\nto be filled in from the start, but it will help over the course of the experiment.\n\n| Item          | Value\n| ------------- | --------\n| Description   | API providing access to the address book\n| Status        | Draft\n| Compatibility | Thunderbird 63\n| Tracking      | [issue #1](https://github.com/thunderbird/webext-experiments/issues/1) / [bug 1396172](https://bugzilla.mozilla.org/show_bug.cgi?id=1396172)\n\nValid status values are:\n* `Draft`: Initial commit, discussing design in linked github issue. Depending on the nature of the Experiment, it may not get past this state.\n* `Accepted`: API Experiment accepted for Thunderbird Core, bug is filed to integrate into comm-central.\n* `Nightly`: API Experiment landed in nightly builds, compatibility field should be \"Since Thunderbird NN\".\n* `Release`: API Experiment is available in release builds, compatibility field should be \"Since Thunderbird NN\".\n\nThe compatibility field shows what versions the API Experiment was designed for. If you are working\non it in nightly, please be sure to set/update the respective nightly version. If you are sure it\nalso works for a range of nightlies, you can also add a range.\n\n### Getting in touch\nIf you have questions about WebExtension Experiments in Thunderbird, you can reach us through our\nofficial [communication channels](https://developer.thunderbird.net/add-ons/community). We are happy\nto tell you more about how they work, and engage in some ad-hoc discussion on how to design WebExtension\nAPIs.\n\nUsing Experiments in your Add-ons\n---------------------------------\n\nThe repository layout is conveniently written so you can collect the experiments in a subdirectory of your add-on.\n\n```\nmkdir -p my_addon_directory/experiments\ncp -R webext-experiments/calendar/experiments/ my_addon_directory/experiments\n```\n\nNow copy the respective `experiment_apis` entries in e.g. `calendar/manifest.json` to your add-on's manifest.json.\n\n\nMigrating from Legacy Add-ons\n-----------------------------\nIf you are migrating your legacy add-on to WebExtensions, you may need to rethink how your UI is\npresented, possibly in a way that seems less integrated. It may also mean that certain features will\nnot be possible in the future. While this is unfortunate, we need to strike a balance between\nexposing all of the features the Mozilla Platform has to offer and making the APIs simple to\nmaintain.\n\nWe are not doing this to limit creativity, but to ensure Thunderbird can thrive and add-ons are\nresilient to changes in Thunderbird and the Mozilla Platform. The goal is to keep WebExtension compatible\nwith future versions of Thunderbird despite far-reaching internal changes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthunderbird%2Fwebext-experiments","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthunderbird%2Fwebext-experiments","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthunderbird%2Fwebext-experiments/lists"}