Installation Guide

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• BUILDING.md
• package.json
• CONTRIBUTING.md
• doc/building.md
• doc/faq.md
• manifest_template.json
• tools/tsdown_config.ts

Ghostbird is a Thunderbird add-on that enables composing emails in an external text editor via the GhostText protocol. This guide provides comprehensive instructions for installing the Ghostbird add-on for regular use and for setting up a development environment to build the add-on from its source code.

The installation process varies depending on whether you are an end-user or a developer. End-users can install the pre-built add-on directly from the Thunderbird Add-ons Manager, while developers will need to set up a build environment to compile the extension from source.

Sources: README.md:11-15, doc/faq.md:5-8

System Requirements

Before installing Ghostbird, ensure your system meets the following requirements.

Component	Requirement
Email Client	Thunderbird 128+ (latest ESR is primarily supported).
Text Editor	A text editor with a running GhostText server add-on.
Development	Git, Node.js LTS (e.g., v22+), and Yarn (via corepack).

The text editor must have a compatible plugin to act as a GhostText server. Supported editors include VS Code, VSCodium, Sublime Text, Neovim, Vim, Emacs, and others.

Sources: README.md:19-32, CONTRIBUTING.md:19-25, doc/faq.md:17-19, manifest_template.json:11

User Installation

There are two primary methods for end-users to install the Ghostbird add-on.

Install within Thunderbird (Recommended)

This is the simplest method for installing Ghostbird.

1. In Thunderbird, navigate to the Add-ons Manager.
2. Use the search bar to find "Ghostbird".
3. Click the + Add to Thunderbird button to install the add-on.

Sources: README.md:43-46

Manual Installation from File

You can also download the add-on file (.xpi) and install it manually.

1. Download the latest release from the Thunderbird add-on website (AMO) or GitHub Releases.
2. In Thunderbird, go to Add-ons Manager.
3. Drag and drop the downloaded .xpi file into the Add-ons Manager window.

Alternatively, you can use the gear icon (⚙️) in the Add-ons Manager, select Install Add-on From File..., and choose the downloaded .xpi file.

Sources: README.md:48-57

Developer Installation (Building from Source)

Developers who wish to contribute or modify the add-on must build it from the source code. This involves setting up a development environment and using build scripts.

Environment Setup

1. Clone the repository: Fork the repository and clone it to your local machine.
2. Install Node.js: Ensure you have a compatible LTS version of Node.js installed.
3. Install Yarn: The project uses Yarn for package management. Install it via corepack:

   corepack install && corepack enable
   

4. Install Dependencies: Run yarn in the project root to install all required dependencies listed in package.json.

Sources: CONTRIBUTING.md:33-45, BUILDING.md:3-4

Build Process

The project uses tsdown as its bundler, configured via tools/tsdown_config.ts. The build process compiles TypeScript source files, generates the manifest, handles localization, and packages the final extension.

The following diagram illustrates the high-level build process.

This diagram shows how source files and templates are processed by build tools to generate the final packaged .xpi file.

Sources: doc/building.md:10-33, tools/tsdown_config.ts:1-20

Build Scripts

The package.json file contains several scripts to automate the build, test, and development workflow.

Script	Description
yarn build	Runs checks, tests, and then builds the .xpi package. This is the main build command.
yarn build-js	Runs tsdown to compile TypeScript and bundle assets into the dist/ext/ directory.
yarn build-xpi	Uses web-ext to package the contents of dist/ext/ into a .xpi file.
yarn watch	Runs build-js in watch mode, automatically rebuilding on file changes.
yarn start	Launches Thunderbird with the extension loaded temporarily for debugging.
yarn test	Executes the unit test suite using Vitest.
yarn check	Runs the type checker (tsc) and Biome linter.
yarn fix	Automatically fixes linting issues found by Biome.

To perform a full build, run yarn install followed by yarn build. The resulting .xpi file will be located in the dist/ directory.

Sources: package.json:23-55, CONTRIBUTING.md:52-54, doc/building.md:35-43

Build Configuration

The core build logic is defined in tools/tsdown_config.ts. This file configures tsdown with custom plugins for various tasks:

• barrelsby(): Generates index.ts barrel files for module exports.
• generateManifest(): Creates manifest.json from manifest_template.json, injecting version information.
• generateLocaleMessages(): Generates localization files from locales.toml.
• typecheckWithTsc(): Runs the TypeScript compiler for type checking during development builds.
• testSanity(): Runs basic sanity tests during development builds.

The build process distinguishes between development and release builds. Release builds are triggered when the CI environment variable is set or when ext/manifest.json exists. Release builds have slightly different outputs, such as using relative paths in source maps and removing console.log statements.

Sources: doc/building.md:45-77, tools/tsdown_config.ts:22-126