Skip to main content

Desktop

Requirements​

Before you start, you must complete the Clients repository setup instructions.

These are available as additional dependencies in the Visual Studio Installer.

  • Visual C++ Build tools
  • Rust
Nx commands are preferred.

We now recommend using Nx commands for building projects. For desktop:

# Build and serve (including the native module)
npx nx serve desktop

For complete Nx documentation and all available commands, see Using Nx to Build Projects.

Build native module​

The desktop application relies on a native module written in rust, which needs to be compiled separately. This is baked in to the build process for npm run electron, but you can also compile it manually.

cd apps/desktop/desktop_native/napi
npm run build

Note: This module needs to be re-built if the native code has changed.

Cross compile​

Windows on ARM​

If you're building in Windows on ARM, you might need to run build.js with the cross-platform argument to build both arm64 and x64 native binaries:

node desktop_native/build.js cross-platform

Linux & others​

In certain environments such as WSL (Windows Subsystem for Linux), it might be necessary to cross-compile the native module. To do this, first make sure you have installed the relevant rust target. See rustup documentation for more information.

# Ensure cargo env file is sourced.
source "$HOME/.cargo/env"

cd apps/desktop/desktop_native
export PKG_CONFIG_ALL_STATIC=1
export PKG_CONFIG_ALLOW_CROSS=1
npm run build -- --target x86_64-unknown-linux-musl # Replace with relevant target

Targeting Windows Appx from macOS​

The Windows Appx can be built from macOS1. This can be helpful if you have a macOS development machine and an underpowered Windows test machine, like a VM or test laptop.

(Note: If you are using a Windows VM on macOS with Apple Silicon, we recommend using UTM with a Windows 11 arm64 build for the best performance.)

Prerequisites​
  • PowerShell 7.x: Build scripts
  • makemsix from microsoft/msix-packaging: Packages the file in an Appx
  • osslsigncode: Produces signatures in the Appx format using OpenSSL.
  • cargo-xwin: Used to cross-compile native binaries for the Windows MSVC target.

You can install these with the following script:

brew install powershell iinuwa/msix-packaging-tap/msix-packaging osslsigncode
cargo install --version 0.20.2 --locked cargo-xwin

Our build scripts will also automatically attempt to install these utilities when cross-compiling to Windows from macOS.

Before building the first time, you must generate a signing certificate and set up your test machine to trust it. See the setup instructions in the Microsoft Store docs for more information.

After that, you can build the Appx from macOS using the steps below.

Cross-compiling Appx​
cd apps/desktop
export CERTIFICATE_PASSWORD="<password>"
./scripts/appx-cross-build.ps1 -Architecture arm64 -CertificatePath "<path to signing cert>.pfx"

Once complete, you can copy the Appx file from apps/desktop/dist/Bitwarden-<version>.appx to your Windows test machine and install it there.

Use PowerShell's help system to get more information about the script arguments:

Get-Help ./scripts/appx-cross-build.ps1 -Full

Build instructions​

Build and run:

cd apps/desktop
npm run electron

Debugging and testing​

Electron apps have a renderer process, which runs in the Electron window, and the main process, which runs in the background.

The renderer process can be inspected using the Chromium debugger. It should open automatically when the Desktop app opens, or you can open it from the “View” menu.

The main process can be debugged by running the app from a Javascript Debug Terminal in Visual Studio Code and then placing breakpoints in build/main.js.

Biometric unlock (Native Messaging)​

Instructions for configuring native messaging (communication between the desktop application and browser extension) are located in the Browser section.

Troubleshooting​

Trouble building​

If you see an error like this:

[Main] Error: Cannot find module '@bitwarden/desktop-native-darwin-arm64'

You likely haven't built the native module, refer to Build Native Module.

Desktop electron app window doesn't open​

If running npm run electron throws an error similar to this:

[Main] npm ERR! Error: Missing script: "build-native"

or the electron window doesn't render, you may need to update node and/or npm. Upgrading from older versions to these solved this issue:

  • Node: 16.18.1
  • npm: 8.19.2

Windows build installation fails​

When installing standard/beta builds (not portable) for the Windows platform from build artifacts, there are additional steps required. Without following the steps, the following failure occurs:

nsis error

Steps:

  1. Download the standard / beta Windows build (the .exe from figure below)
  2. Download the corresponding .nsis.7z file (also seen in figure below)
  3. Place the .nsis.7z file in the same directory as the installer (this might require decompressing the download)

nsis build files

The final directory state before starting the install should look like this:

nsis and exe directory

Footnotes​

  1. Linux is not currently supported for cross-compilation of the Appx. It could work by using the same instructions as for macOS listed above, but we are not aware of a packaged version of msix-packaging tools required for building the Appx.

    Contributions to the documentation on how to build this package for Linux are welcome. Alternatively, you can consider contributing to the third party Homebrew tap to add Linux support at iinuwa/msix-packaging-tap/msix-packaging.

    ↩