Before you start, you must complete the Clients repository setup instructions.
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
npm run build
Note: This module needs to be re-built if the native code has changed.
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.
npm run build -- --target x86_64-unknown-linux-musl # Replace with relevant target
Build and run:
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
in Visual Studio Code and then placing breakpoints in
Biometric Unlock (Native Messaging)
Instructions for configuring native messaging (communication between the desktop application and browser extension) are located in the Browser section.
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
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: