Workspace Management

Overview

Proton WebClients is a Yarn 4 monorepo containing multiple web applications and shared packages. The workspace structure enables efficient dependency management and code sharing across projects.

Workspace Structure

The monorepo is organized into the following workspace categories:

{
  "workspaces": [
    "applications/*",
    "applications/pass-desktop/native",
    "packages/*",
    "packages/wasm/*",
    "tests",
    "tests/mail-renderer",
    "tests/packages/*",
    "utilities/*",
    "vendor/*/*"
  ]
}

Directory Layout

applications/ - Web applications (Mail, Drive, Calendar, Pass, etc.)
packages/ - Shared libraries and utilities
packages/wasm/ - WebAssembly modules
tests/ - Test utilities and configurations
vendor/ - Third-party dependencies

Managing Dependencies

Installing Dependencies

Install all dependencies for the entire monorepo:

yarn install

Yarn 4 uses the node_modules linker strategy as configured in .yarnrc.yml.

Adding Dependencies

To Workspace Root
To Specific Package
Dev Dependencies

Add a dependency to the root workspace:

yarn add <package-name> -W

Add a dependency to a specific workspace package:

yarn workspace <workspace-name> add <package-name>

Example:

yarn workspace proton-mail add lodash

Add a dev dependency:

yarn workspace <workspace-name> add -D <package-name>

Removing Dependencies

yarn workspace <workspace-name> remove <package-name>

Workspace Commands

List Workspaces

List all workspaces in the monorepo:

yarn workspaces list

List with location information:

yarn workspaces list --verbose

Run Commands in Workspaces

Single Workspace
All Workspaces

Run a script in a specific workspace:

yarn workspace <workspace-name> <script-name>

Examples:

yarn workspace proton-mail start
yarn workspace proton-drive build:web
yarn workspace @proton/components test

Run a command across all workspaces:

yarn workspaces foreach <command>

Example:

yarn workspaces foreach run lint

Workspace Naming

Workspace names follow these conventions:

Applications: proton-<app-name> (e.g., proton-mail, proton-drive)
Packages: @proton/<package-name> (e.g., @proton/shared, @proton/components)

Common Workspace Packages

Core Packages

Package	Description
`@proton/shared`	Shared utilities and business logic
`@proton/components`	React component library
`@proton/pack`	Build tooling (webpack configuration)
`@proton/i18n`	Internationalization utilities
`@proton/crypto`	Cryptography utilities
`@proton/styles`	Shared styles and themes
`@proton/icons`	Icon library

Application Packages

Package	Application
`proton-mail`	Proton Mail
`proton-calendar`	Proton Calendar
`proton-drive`	Proton Drive
`proton-pass`	Proton Pass
`proton-account`	Account settings
`proton-vpn-settings`	VPN settings

Version Management

Requirements

{
  "packageManager": "[email protected]",
  "engines": {
    "node": ">= 22.14.0 <23.6.0"
  }
}

Manual Versioning

Version an application manually from the root folder:

yarn workspace @proton/version run version --applications proton-X --version x.x.x.x

Turbo Configuration

The monorepo uses Turbo for task orchestration and caching:

{
  "tasks": {
    "build:web": {
      "outputs": ["dist/**", "webapp-bundle.tar.gz"]
    },
    "test:ci": {
      "dependsOn": ["transit"]
    },
    "lint": {},
    "check-types": {
      "dependsOn": ["transit"]
    }
  }
}

Troubleshooting

Dependency resolution issues

Clear the cache and reinstall:

yarn cache clean
rm -rf node_modules
yarn install

Workspace not found

Verify the workspace name:

yarn workspaces list | grep <workspace-name>

Check that the package exists in the correct directory.

Version conflicts

Check for dependency version mismatches:

yarn why <package-name>

Review resolutions in root package.json for pinned versions.

The monorepo uses workspace protocol (workspace:^) for internal dependencies. Do not manually modify these to version numbers.

Best Practices

Use Workspace Protocol

Always use workspace:^ for internal package dependencies

Run from Root

Execute workspace commands from the monorepo root directory

Check Dependencies

Use yarn why to understand dependency resolution

Leverage Turbo

Take advantage of Turbo’s caching for faster builds

Getting Started

Applications

Development

Contributing

Overview

Workspace Structure

Directory Layout

Managing Dependencies

Installing Dependencies

Adding Dependencies

Removing Dependencies

Workspace Commands

List Workspaces

Run Commands in Workspaces

Workspace Naming

Common Workspace Packages

Core Packages

Application Packages

Version Management

Requirements

Manual Versioning

Turbo Configuration

Troubleshooting

Best Practices

Use Workspace Protocol

Run from Root

Check Dependencies

Leverage Turbo

Build docs developers (and LLMs) love

Getting Started

Applications

Development

Contributing

​Overview

​Workspace Structure

​Directory Layout

​Managing Dependencies

​Installing Dependencies

​Adding Dependencies

​Removing Dependencies

​Workspace Commands

​List Workspaces

​Run Commands in Workspaces

​Workspace Naming

​Common Workspace Packages

​Core Packages

​Application Packages

​Version Management

​Requirements

​Manual Versioning

​Turbo Configuration

​Troubleshooting

​Best Practices

Use Workspace Protocol

Run from Root

Check Dependencies

Leverage Turbo

Build docs developers (and LLMs) love

Overview

Workspace Structure

Directory Layout

Managing Dependencies

Installing Dependencies

Adding Dependencies

Removing Dependencies

Workspace Commands

List Workspaces

Run Commands in Workspaces

Workspace Naming

Common Workspace Packages

Core Packages

Application Packages

Version Management

Requirements

Manual Versioning

Turbo Configuration

Troubleshooting

Best Practices