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

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​

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

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