Skip to main content

​
Contributing to Bitwarden Clients

Thank you for your interest in contributing to Bitwarden! This guide will help you get started with contributing to the clients repository.
The official Contributing Documentation is maintained at contributing.bitwarden.com. This page provides a quick overview and repository-specific guidance.

​
Getting started

1

Read the official guidelines

Visit contributing.bitwarden.com for comprehensive contributing guidelines covering:
  • Code of conduct
  • Development workflow
  • Code style and conventions
  • Testing requirements
  • Documentation standards
2

Set up your development environment

Follow the installation guide to clone the repository and install dependencies:
git clone https://github.com/bitwarden/clients.git
cd clients
npm install
3

Choose what to work on

  • Browse open issues
  • Look for issues labeled good first issue
  • Check the project boards for planned work
  • Propose your own improvements
4

Create a branch

Create a feature branch from main:
git checkout -b feature/my-contribution

​
Development workflow

​
1. Make your changes

Edit the code following the project’s conventions:
  • TypeScript - All new code must be TypeScript
  • Strict typing - Avoid any types when possible
  • Formatting - Code is auto-formatted with Prettier
  • Linting - Must pass ESLint checks

​
2. Test your changes

Run the relevant tests for your changes: 
# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

​
3. Build the application

Ensure your changes build successfully: 
# Browser extension
cd apps/browser
npm run build:chrome

# Desktop application
cd apps/desktop
npm run build

# Web vault
cd apps/web
npm run build:oss

# CLI
cd apps/cli
npm run build:oss

​
4. Commit your changes

Use clear, descriptive commit messages: 
git add .
git commit -m "feat: add password strength indicator to generator"
Commit message format:
  • feat: - New feature
  • fix: - Bug fix
  • docs: - Documentation changes
  • refactor: - Code refactoring
  • test: - Adding or updating tests
  • chore: - Maintenance tasks

​
5. Submit a pull request

Push your branch and create a pull request: 
git push origin feature/my-contribution
Then:
  1. Go to github.com/bitwarden/clients
  2. Click “New Pull Request”
  3. Select your branch
  4. Fill out the PR template with details about your changes
  5. Submit for review

​
Code style guidelines

​
TypeScript conventions

// Use interfaces for object shapes
interface User {
  id: string;
  email: string;
  name?: string;
}

// Use async/await instead of promises
async function getUser(id: string): Promise<User> {
  const response = await this.apiService.getUser(id);
  return response.data;
}

// Use proper typing, avoid 'any'
function processItems<T>(items: T[]): T[] {
  return items.filter(item => item !== null);
}

​
Angular conventions

// Component structure
@Component({
  selector: 'app-vault-items',
  templateUrl: './vault-items.component.html',
})
export class VaultItemsComponent implements OnInit, OnDestroy {
  private destroy$ = new Subject<void>();
  
  constructor(
    private cipherService: CipherService,
    private router: Router,
  ) {}
  
  async ngOnInit() {
    // Initialization logic
  }
  
  ngOnDestroy() {
    this.destroy$.next();
    this.destroy$.complete();
  }
}

​
Naming conventions

  • Files: kebab-case.ts (e.g., cipher-service.ts)
  • Classes: PascalCase (e.g., CipherService)
  • Interfaces: PascalCase (e.g., CipherView)
  • Variables/functions: camelCase (e.g., getCipher())
  • Constants: UPPER_SNAKE_CASE (e.g., MAX_TIMEOUT)

​
Testing guidelines

​
Unit tests

All new features should include unit tests: 
describe('CipherService', () => {
  let service: CipherService;
  let cryptoService: MockProxy<CryptoService>;
  
  beforeEach(() => {
    cryptoService = mock<CryptoService>();
    service = new CipherService(cryptoService);
  });
  
  it('should encrypt cipher data', async () => {
    const cipher = createTestCipher();
    const encrypted = await service.encrypt(cipher);
    
    expect(encrypted).toBeDefined();
    expect(cryptoService.encrypt).toHaveBeenCalled();
  });
});

​
Test coverage

  • Aim for high test coverage on business logic
  • Test edge cases and error conditions
  • Use mocks for external dependencies
  • Keep tests focused and isolated

​
Platform-specific guidelines

Each application has unique architectural requirements:
Critical rules:
  • Never use chrome.* or browser.* APIs directly - use BrowserApi abstraction
  • Always use BrowserApi.addListener() in popup context (Safari requires cleanup)
  • Use BrowserApi.tabsQueryFirstCurrentWindowForSafari() for tab queries
  • Service workers can be terminated anytime - avoid assuming persistence
See: apps/browser/src/platform/browser/browser-api.ts

​
Pull request guidelines

​
PR checklist

Before submitting, ensure:
  • Code builds without errors
  • All tests pass
  • Linting passes (npm run lint)
  • Code is formatted (npm run prettier)
  • Commit messages follow conventions
  • PR description explains the changes
  • Related issue is linked (if applicable)
  • Breaking changes are documented

​
PR review process

  1. Automated checks - CI runs tests and linting
  2. Code review - Maintainers review your code
  3. Feedback - Address review comments
  4. Approval - Maintainer approves the PR
  5. Merge - Changes are merged to main

​
Target branch

All pull requests must be submitted against the main branch.

​
Development tools

The repository includes recommended extensions in .vscode/extensions.json:
  • ESLint - Real-time linting
  • Prettier - Code formatting
  • Angular Language Service - Angular IntelliSense
  • Jest - Test runner integration

​
Workspace settings

VS Code workspace settings are provided in clients.code-workspace: 
# Open in VS Code
code clients.code-workspace

​
Git hooks

The repository uses Husky for git hooks:
  • pre-commit - Runs lint-staged (formats and lints staged files)
  • commit-msg - Validates commit message format
These run automatically when you commit.

​
Getting help

​
Resources

Official docs

Comprehensive contributing documentation

Gitter chat

Chat with the community

GitHub issues

Browse or report issues

Clients docs

Client-specific documentation

​
Questions?

If you have questions about contributing:

​
Security vulnerabilities

If you discover a security vulnerability, please follow the process outlined in SECURITY.md. Do not open a public issue.

​
License

By contributing to Bitwarden, you agree that your contributions will be licensed under the GPL-3.0 license. See LICENSE.txt for details.

​
We’re hiring!

Interested in contributing full-time? Bitwarden is hiring! Check out our careers page to see open positions.

​
Thank you!

Your contributions make Bitwarden better for everyone. We appreciate your time and effort in helping improve the project.

Build docs developers (and LLMs) love

Get started for freeTalk to us