A "Hello World" Extension Tutorial
All the information you need to get your first Thunderbird extension up and running.
In the first part of this tutorial, we will create a very simple extension, which adds a "Hello World" button to Thunderbird's main toolbar and a click on it will show a
First, we create an empty
hello-worldproject folder for our extension and navigate to it.
Extensions require a
manifest.jsonfile that tells Thunderbird a few basic information about the add-on. Let's place the following
manifest.jsonfile directly in the
"name": "Hello World Example",
"description": "A basic Hello World example extension!",
"author": "Thunderbird Team",
"id": "[email protected]",
"default_title": "Hello World",
You can grab the icons we use for this example from the example repository. Make sure to create an
imagesdirectory in the
hello-worldproject folder for them.
The above manifest includes the definition for a
browser_action. That is the button we want to add to Thunderbird's main toolbar. The reference to a browser in its name is inherited from the Firefox Browser.
The allowed keys for the
browser_actionbutton are described in our API documentation. We define a popup HTML page, which should be loaded if the button is clicked, a title and an icon.
The location of the HTML file loaded by the popup of our
browser_actionis defined in the
browser_action.default_popupkey. Let's create a
mainPopupdirectory in the
hello-worldproject folder for everything related to that popup and start with the following
<link rel="stylesheet" type="text/css" media="screen" href="popup.css">
<script type="module" src="popup.js"></script>
<script>tags and inline event handlers like
scripttag to include
type="module", which loads the script as a top level ES6 module. This enables the script to use the await keyword in file scope code and to load other ES6 modules.
We will not use these features in this step of the tutorial, but we still use the modern ES6 module approach here to introduce it as a standard programming practice.
We're going to create the following file called
popup.jsand place it in the same folder as the
// Below is what we'll log to the console.
console.log('Hello, World! - from popup.js');
What our little script does is sending a message to the console each time we click on our "Hello World" toolbar button. We'll take a look at that in a moment when we try out our add-on. The first line is just a comment, so we can remember what our code is doing.
Now we want to create the CSS file referenced in our HTML file. We'll call it
popup.css. This is just for decoration of the page, we'll put it in the same folder as the
font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
To install the add-on we created, we are going to load it temporarily. Let's start by opening the Add-ons Manager:
This will open up the Add-ons Manager, make sure "Extensions" is selected on the left-hand side and click the gear to select "Debug Add-ons".
Click on the "Load Temporary Add-on..." button:
manifest.jsonfile from within our
This should install the add-on for this session only:
Our extension will print messages to the error console using
console.log(), so we need to open the error console first, in order to see those log entries. Hit the "Inspect" button under the add-on's listing (pictured above), this will bring up the Developer Tools tab.
Make sure the "Console" tab is selected in the Developer Tools. Click the "Persist Logs" checkbox in the top right-hand corner of the Developer Tools so that we can see the output from the add-on after we've interacted with it (otherwise it only shows output as it is happening).
Now we can give our new add-on a whirl. Head to the home tab and find the new "Hello World" button in the main toolbar in the top right-hand corner. Click on it to see a popup with the
Now, if you look at the Developer Tools, you should see something like the following in the console:
Once the add-on is ready for release or if you want to share it with others, you need to create a single add-on file. Simply zip the content of the add-on's project folder and use the
xpifile extension. That file can be installed from the gear menu in the Thunderbird Add-ons Manager.