Installation This guide walks you through cloning the Bitwarden Clients repository and installing all necessary dependencies.
Prerequisites Before starting, ensure you have the required software installed:
Clone the repository
Choose your clone method
Clone via HTTPS or SSH based on your GitHub authentication preference: git clone https://github.com/bitwarden/clients.git cd clients
Verify repository structure
Check that the repository cloned successfully: You should see: apps/ # Client applications libs/ # Shared libraries bitwarden_license/ # Commercial features package.json # Root package configuration nx.json # Nx workspace configuration tsconfig.base.json # TypeScript configuration
Install dependencies The repository uses npm workspaces to manage dependencies across all applications and libraries.
Root installation Always run npm install from the repository root, not from individual app directories.
# From the repository root npm install
This command:
Installs all root dependencies from package.json
Installs dependencies for all workspace packages (apps/*, libs/**/*)
Creates a single node_modules at the root with hoisted dependencies
Links workspace packages together
Runs the prepare script (sets up Husky git hooks)
Installation output The installation process will:
Download packages
Set up git hooks
Link workspaces
Downloads ~1.5 GB of dependencies: npm install # Output: # added 2847 packages in 2m # # 89 packages are looking for funding # run `npm fund` for details
Configures Husky for pre-commit hooks: # Runs automatically during install: # > @bitwarden/[email protected] prepare # > husky
This sets up:
pre-commit: Runs lint-staged (format + lint)commit-msg: Validates commit message format Links workspace packages: # Apps can import from libs using: import { CipherService } from '@bitwarden/common/vault/services/cipher.service' ; # Instead of relative paths: import { CipherService } from '../../../libs/common/src/vault/services/cipher.service' ;
Platform-specific post-install Some applications require additional setup after npm install:
Desktop (Electron)
Browser extension
Web vault
CLI
The desktop app requires rebuilding native modules for Electron: cd apps/desktop npm run postinstall
This runs automatically when you npm install in the desktop directory, but you may need to run it manually after:
Updating Electron version
Switching Node.js versions
Installing new native dependencies
For macOS native modules: cd apps/desktop/desktop_native ./autofill_provider/build.sh node build.js cross-platform
No additional setup required. The browser extension has no native dependencies. # Ready to build cd apps/browser npm run build:chrome
No additional setup required. # Ready to build cd apps/web npm run build:oss
No additional setup required. # Ready to build cd apps/cli npm run build:oss
Workspace structure After installation, your workspace will have this structure:
bitwarden/clients/ ├── node_modules/ # Shared dependencies (hoisted) ├── apps/ │ ├── browser/ │ │ └── node_modules/ # Browser-specific dependencies │ ├── cli/ │ │ └── node_modules/ # CLI-specific dependencies │ ├── desktop/ │ │ ├── node_modules/ # Desktop-specific dependencies │ │ └── desktop_native/ │ │ └── napi/ │ │ └── node_modules/ # Native module deps │ └── web/ │ └── node_modules/ # Web-specific dependencies ├── libs/ │ └── [individual library node_modules as needed] └── package-lock.json # Lockfile for all workspaces
Verify installation Run these commands to ensure everything is set up correctly:
Check versions
Run tests
Check build tools
# Verify Node.js version node --version # Expected: v22.12.0 or higher # Verify npm version npm --version # Expected: 10.x.x # Check installed packages npm list --depth=0 # Shows all root dependencies
Using Node Version Manager (nvm) If you use nvm, the repository includes an .nvmrc file:
# Install the specified Node version nvm install # Use the specified Node version nvm use # Output: Now using node v22.x.x (npm v10.x.x) # Set as default (optional) nvm alias default 22
Troubleshooting Installation fails with permission errors Never use sudo npm install. This can cause permission issues.
Solution: Configure npm to install global packages in your home directory:# Create a directory for global packages mkdir ~/.npm-global # Configure npm to use it npm config set prefix '~/.npm-global' # Add to your PATH (in ~/.bashrc or ~/.zshrc) export PATH =~ /. npm-global / bin : $PATH # Reload your shell source ~/.bashrc # or source ~/.zshrc
Node version mismatch # Error: The engine "node" is incompatible with this module # Solution: Use the correct Node version nvm use 22 # Or install it first nvm install 22
Native module build failures On Windows: # Install build tools npm install -- global windows - build-tools # Or install Visual Studio Build Tools manually # https://visualstudio.microsoft.com/downloads/
On macOS: # Install Xcode Command Line Tools xcode-select --install # For Rust-based native modules curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
On Linux: # Ubuntu/Debian sudo apt-get install build-essential # Fedora sudo dnf install gcc gcc-c++ make
Husky hooks not working If git hooks aren’t running:
# Reinstall Husky npm run prepare # Or manually npx husky install
Disk space issues The full installation requires ~10 GB of disk space. If you’re low on space:
# Clean npm cache npm cache clean --force # Remove old node_modules (if reinstalling) rm -rf node_modules apps/ * /node_modules libs/ * /node_modules # Reinstall npm install
Package lock conflicts If you encounter package-lock.json conflicts after pulling updates:
# Remove lock file and node_modules rm package-lock.json rm -rf node_modules # Reinstall npm install
This should be a last resort. Usually npm install will automatically resolve lock file issues.
Next steps Now that you’ve installed the repository:
Run tests
Verify your setup by running the test suite: Additional resources
Requirements Review detailed system requirements
Building Build and run applications
Architecture Understand the monorepo structure
Contributing Learn the development workflow