Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed on your system:

Node.js

Version 22.14.0 or higher (< 23.6.0)

Yarn 4

Package manager (v4.12.0)

Git

Version control system
Check the package.json file for the exact version requirements:

​
Installation

1

Clone the Repository

Clone the Proton WebClients monorepo from GitHub:
git clone https://github.com/ProtonMail/WebClients.git
cd WebClients
2

Install Dependencies

Install all dependencies for the entire monorepo. This command will:
  • Install all npm packages
  • Symlink local dependencies to one another
  • Run postinstall scripts (including Husky hooks)
yarn install
The initial installation may take several minutes as it needs to install dependencies for all applications and packages in the monorepo.
3

Verify Installation

Check that the installation was successful by running:
yarn --version
You should see 4.12.0 or the version specified in package.json.

​
Running Applications

The monorepo hosts multiple Proton web applications. You can run any application using the yarn workspace command.

​
Available Applications

Proton Mail

yarn workspace proton-mail start

Proton Calendar

yarn workspace proton-calendar start

Proton Drive

yarn workspace proton-drive start

Proton Account

yarn workspace proton-account start

Proton VPN

yarn workspace proton-vpn-settings start

Proton Pass

yarn workspace proton-pass start

Proton Wallet

yarn workspace proton-wallet start

Proton Lumo

yarn workspace proton-lumo start
The development server will typically run on http://localhost:8080 or the port specified in the application’s configuration.

​
Start All Applications

To run all applications simultaneously with local SSO support: 
yarn start-all
This script runs the local SSO utility located in utilities/local-sso.

​
Building for Production

Build any application for production deployment: 
# Build a specific application
yarn workspace proton-mail build:web

# Analyze the bundle size
yarn workspace proton-mail analyze
Production builds use Turbo for caching and are configured in turbo.json. Output files are generated in the dist/ directory.

​
Common Tasks

​
Type Checking

Run TypeScript type checking across the workspace: 
# Check types for a specific application
yarn workspace proton-mail check-types

# Check types across all workspaces
yarn turbo run check-types

​
Linting

Lint code using ESLint: 
# Lint a specific application
yarn workspace proton-mail lint

# Lint all workspaces
yarn turbo run lint

​
Running Tests

yarn workspace proton-mail test

​
Troubleshooting

​
Installation Issues

Ensure you’re using the correct Node.js version:
node --version
If you’re using nvm, switch to the required version:
nvm install 22.14.0
nvm use 22.14.0
The project uses Yarn 4 with Corepack. Enable Corepack:
corepack enable
corepack prepare [email protected] --activate
If the postinstall script fails, you can run it manually:
yarn run config-app
Clear the Yarn cache and reinstall:
yarn cache clean
rm -rf node_modules
yarn install

​
Next Steps

Project Structure

Learn about the monorepo organization and architecture

Development Workflow

Understand the development process and best practices

Contributing

Learn how to contribute to the project

Architecture

Deep dive into the technical architecture

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us