---

Threema for Desktop

A standalone Threema client for the desktop (Windows/macOS/Linux).

Table of Contents

• Policies
  • Bug Reports / Feature Requests / Security Issues
  • Contributions
  • Source Code Release Policy
• Building
  • Requirements
  • Install Dependencies
  • Set Up Fonts
  • Build libthreema
  • Build and Package
• Development
  • Dev Container
  • Development Outside Dev Container
  • Starting a Dev Build
• License

Policies

Bug Reports / Feature Requests / Security Issues

To report bugs and request new features, please contact the Threema support team through threema.ch/support.

If you discover a security issue in Threema, please adhere to the coordinated vulnerability disclosure model. To be eligible for a bug bounty, please file a report on GObugfree (where all the details, including the bounty levels, are listed). If you’re not interested in the bug bounty program, you can contact us via Threema or by email; for contact details, see threema.ch/contact (section “Security”).

Contributions

Contributing to Threema for desktop can be done over GitHub pull requests. See CONTRIBUTING.md for details.

Source Code Release Policy

This source code repository will be updated for every public release. The full commit history since the last release will be published.

Building

Requirements

• NodeJS / npm (we recommend using something like nvm for version management)
• Python3 with distutils (for node-gyp, e.g. python and python-setuptools on Arch)
• C/C++ compiler toolchain (e.g. build-essential on Debian or base-devel on Arch)
• Rust compiler and Cargo through rustup
• For building libthreema: wasm-bindgen and wasm-opt (part of the binaryen package)

It is highly recommended to use a Linux- or macOS-based system for building and developing Threema Desktop! Building on Windows 10+ should mostly work, but not everything may work as smoothly and we cannot provide any support.

macOS

On macOS you might need to manually install and configure the C compiler toolchain in order to use node-gyp. Usually that can be done by installing the required "Command Line Tools" with the command xcode-select --install. Alternatively, you can install Xcode (note that it might take more than 1h between download and installation!) and then select a "Command Line Tools" version in Preferences > Locations. For a detailed guide and diagnostics, please refer to the "Installation notes for macOS" from the node-gyp project itself.

Windows

When building on Windows, it is important to clone the repository with symlink support. For this, you first need to enable Developer Mode. Then, run the following command to enable git support for symlinks globally:

git config --global core.symlinks true

Afterwards clone the repository as usual. (Alternatively, clone with git clone -c core.symlinks=true ... if you don't want to enable this option globally.)

Install Dependencies

First, make sure that you're using the correct NodeJS version (check out the .nvmrc file). If you have nvm installed, you can simply type nvm use.

Next, install dependencies:

npm install

Note that this requires a C/C++ compiler toolchain due to native dependencies, as mentioned above.

Build libthreema

We provide a script in to build libthreema. To that end, install wasm-bindgen and wasm-opt and run npm run libthreema:build. The generated files and bindings can be found in wasm/web.

Build and Package

To create a package target, run:

npm run package <target> [params]

Possible targets:

• source: A source archive (.tar.gz and .7z)
• binary: An archive containing a raw binary build for the current architecture
• dmg: An unsigned macOS DMG
• dmgSigned: A signed macOS DMG
• msix: An unsigned Windows MSIX package
• msixSigned: A signed Windows MSIX package
• flatpak: A Linux Flatpak in a local repository

For example, to build Threema for your current platform, run:

npm run package binary consumer-live

Now you can find the application bundle at build/out/.

Development

Below we'll provide a couple of hints and rules for working on this project.

More developer docs can be found under docs/.

Dev Container

Note: Only works on Linux!

When developing, you should use the dev container environment to run appropriate commands inside of an isolated environment considering that any npm dependency can run arbitrary code and we have a ton of development dependencies. You'll need jq and a compatible shell, then run:

source ./.devcontainer/env.sh
node --version

You can exit this environment and stop the running container by running deactivate. If you have closed your shell, you can still stop the container by calling docker ps to list and docker rm to stop the environment.

Moreover, this dev container can also be used in VS Code by using VS Code Dev Container Note that this currently requires Visual Studio Code (not Code OSS).

> Dev Containers: Reopen in Container

You will have to rebuild the Dev Container every time the dev environment script rebuilds the image. VS Code will prompt you in that case but you can also force a rebuild manually.

> Dev Containers: Rebuild Container

Limitations:

• Cannot run npm run dev:* commands because it cannot spawn an Electron GUI, nor can it access the Threema Desktop profile directory.
• Cannot run npm run generate-screenshots command because it cannot spawn an Electron GUI.
• Cannot run npm run test:karma command because Chromium and Firefox are not provided by the dev environment. Let this be run by the CI after pushing a branch.
• Cannot run npm run test:playwright:* command because it cannot spawn an Electron GUI.
• Cannot run npm run package dmg command because it needs native MacOS tools.
• Cannot run npm run assets:generate:icons:macos command because it needs native MacOS tools.
• Cannot run npm run assets:generate:icons:windows command because it needs native tools (this script can be run on a macOS machine).
• To run npm run protobuf:generate the threema-protocols repository needs to be cloned inside the project working directory or inside of the container.
• To run npm run structbuf:generate the structbuf-typescript project needs to be installed inside the project working directory or inside of the container.
• If you need to add environment variables, just use enter, define the environment variables and run it from there.

It is accepted to run above commands outside of the dev environment. For convenience, above commands that cannot run will be automatically omitted from running inside the dev environment when using source ./.devcontainer/env.sh.

Development Outside Dev Container

This is discouraged but unfortunately necessary on platforms other than Linux.

The project provides an .nvmrc file in case the default NodeJS installation on your device is being rejected by npm install.

nvm use
nvm install

Starting a Dev Build

To start a dev build of Threema with hot code reloading, run npm run dev:<flavor> in the terminal, e.g. npm run dev:consumer-live.

License

Threema for Desktop is licensed under the GNU Affero General Public License v3.

Copyright (c) Threema GmbH

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License, version 3,
as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.

The full license text can be found in LICENSE.txt.

If you have questions about the use of self-compiled apps or the license in general, feel free to contact us. We are publishing the source code in good faith, with transparency being the main goal. By having users pay for the development of the app, we can ensure that our goals sustainably align with the goals of our users: Great privacy and security, no ads, no collection of user data!