Project Structure - Proton WebClients

Overview

The Proton WebClients repository is a Yarn 4 monorepo that hosts all Proton web applications, shared packages, utilities, and development tooling. It uses Yarn Workspaces for dependency management and Turbo for build orchestration.

The monorepo uses unified versioning - all packages inside share the same version number.

Root Directory Structure

WebClients/
├── applications/          # Web applications
├── packages/             # Shared packages and libraries
├── utilities/            # Development utilities and scripts
├── vendor/               # Third-party vendored dependencies
├── tests/                # Test utilities and configurations
├── .yarn/                # Yarn 4 installation and plugins
├── package.json          # Root package configuration
├── turbo.json           # Turbo build configuration
├── tsconfig.base.json   # Base TypeScript configuration
└── yarn.lock            # Dependency lock file

Applications

The applications/ directory contains all user-facing Proton web applications. Each application is a separate workspace with its own dependencies and build configuration.

Available Applications

Proton Mail

Path: applications/mailFull-featured email client with end-to-end encryptionPackage: proton-mail

Proton Calendar

Path: applications/calendarEncrypted calendar applicationPackage: proton-calendar

Proton Drive

Path: applications/driveEncrypted cloud storage solutionPackage: proton-drive

Proton Account

Path: applications/accountAccount management and settingsPackage: proton-account

Proton VPN

Path: applications/vpn-settingsVPN configuration and managementPackage: proton-vpn-settings

Proton Pass

Path: applications/passPassword manager applicationPackage: proton-pass

Proton Wallet

Path: applications/walletCryptocurrency walletPackage: proton-wallet

Proton Lumo

Path: applications/lumoAI-powered assistantPackage: proton-lumo

Desktop Applications

Pass Desktop

applications/pass-desktop

Inbox Desktop

applications/inbox-desktop

Meet Desktop

applications/meet-desktop

Other Applications

Pass Extension: applications/pass-extension - Browser extension for Proton Pass
Meet: applications/meet - Video conferencing
Docs: applications/docs - Document editor
Docs Editor: applications/docs-editor - Document editing engine
Authenticator: applications/authenticator - 2FA authenticator
Verify: applications/verify - Email verification tool
Storybook: applications/storybook - Component documentation

Packages

The packages/ directory contains 55+ shared packages that provide reusable functionality across applications. These packages are organized by domain and functionality.

Core Packages

@proton/components - Reusable React components
@proton/atoms - Atomic design system components
@proton/icons - Icon library
@proton/colors - Color system and themes
@proton/styles - Shared styles and CSS utilities

Additional Packages

@proton/ai-assistant - AI assistant integration
@proton/llm - Large language model utilities
@proton/activation - Account activation flows
@proton/chargebee - Payment processing
@proton/payments - Payment management
@proton/features - Feature flags
@proton/unleash - Feature toggle integration
@proton/cross-storage - Cross-domain storage
@proton/recovery-kit - Account recovery
@proton/docs-core - Document core functionality
@proton/docs-proto - Document protocol
@proton/docs-shared - Shared document utilities
@proton/mail-renderer - Email rendering engine
@proton/sieve - Email filtering
@proton/wasm - WebAssembly modules

Workspace Configuration

The monorepo uses Yarn Workspaces, configured in the root package.json:

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

This configuration allows any package to reference another using the workspace: protocol in dependencies.

Example: Application Dependencies

Here’s how proton-mail references shared packages:

{
  "name": "proton-mail",
  "dependencies": {
    "@proton/account": "workspace:^",
    "@proton/components": "workspace:^",
    "@proton/crypto": "workspace:^",
    "@proton/hooks": "workspace:^",
    "@proton/icons": "workspace:^",
    "@proton/shared": "workspace:^",
    "@proton/styles": "workspace:^",
    "react": "^18.3.1",
    "react-dom": "^18.3.1"
  }
}

TypeScript Configuration

The monorepo uses a centralized TypeScript configuration in tsconfig.base.json with path mappings for all packages:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@proton/icons/icons/*": ["./packages/icons/icons/*"],
      "@proton/atoms/*": ["./packages/atoms/src/*"],
      "@proton/components/*": ["./packages/components/*"],
      "@proton/shared": ["./packages/shared/*"],
      "@proton/crypto/*": ["./packages/crypto/*"]
      // ... 40+ more mappings
    }
  }
}

Each application and package extends tsconfig.base.json and can override settings as needed.

Build System (Turbo)

The monorepo uses Turbo for efficient builds and caching. Configuration is in turbo.json:

Key Build Tasks

{
  "build:web": {
    "outputs": ["dist/**", "webapp-bundle.tar.gz"]
  }
}

Running Turbo Tasks

# Run a task across all workspaces
yarn turbo run build:web

# Run multiple tasks in parallel
yarn turbo run lint check-types test

# Run with filtered workspaces
yarn turbo run build:web --filter=proton-mail

Utilities

The utilities/ directory contains development scripts and tools:

local-sso - Local single sign-on for development
app-versions - Version management scripts
Additional build and deployment utilities

Running Utilities

# Check application versions
yarn app-versions

# Start local SSO environment
yarn start-all

# Create an atom component
yarn create-atom

Yarn 4 Configuration

The monorepo uses Yarn 4 with specific configurations in .yarnrc.yml:

nodeLinker: node-modules
yarnPath: .yarn/releases/yarn-4.12.0.cjs

npmPublishRegistry: https://nexus.protontech.ch/repository/web-npm/

npmScopes:
  proton:
    npmRegistryServer: 'https://nexus.protontech.ch/repository/foundation-npm/'

compressionLevel: mixed

The monorepo uses private npm registries for some scoped packages. External contributors should be aware that some internal packages may not be accessible.

Development Workflow

Working with a Single Application

# Navigate to root (not required, but recommended)
cd WebClients

# Run development server
yarn workspace proton-mail start

# Run tests
yarn workspace proton-mail test

# Build for production
yarn workspace proton-mail build:web

Working Across Multiple Packages

# Run type checking across all packages
yarn turbo run check-types

# Lint all packages
yarn turbo run lint

# Build all applications
yarn turbo run build:web

Adding Dependencies

yarn add -W package-name

File Organization Patterns

Typical application structure:

applications/mail/
├── src/
│   ├── app/                 # Main application code
│   │   ├── components/      # React components
│   │   ├── containers/      # Container components
│   │   ├── hooks/           # Custom hooks
│   │   ├── logic/           # Business logic
│   │   └── store/           # Redux store
│   ├── app.tsx              # App entry point
│   └── index.tsx            # Main entry point
├── package.json             # Package configuration
├── tsconfig.json            # TypeScript config
└── webpack.config.js        # Build configuration

Typical package structure:

packages/components/
├── components/              # Component implementations
│   ├── button/
│   ├── input/
│   └── modal/
├── hooks/                   # Shared hooks
├── index.ts                # Main export file
├── package.json            # Package configuration
└── tsconfig.json           # TypeScript config

Next Steps

Installation Guide

Set up the development environment

Development Workflow

Learn the development process

Package Development

Create and maintain packages

Build System

Understanding Turbo and builds

Getting Started

Applications

Development

Contributing

​Overview

​Root Directory Structure

​Applications

​Available Applications

Proton Mail

Proton Calendar

Proton Drive

Proton Account

Proton VPN

Proton Pass

Proton Wallet

Proton Lumo

​Desktop Applications

Pass Desktop

Inbox Desktop

Meet Desktop

​Other Applications

​Packages

​Core Packages

​Additional Packages

​Workspace Configuration

​Example: Application Dependencies

​TypeScript Configuration

​Build System (Turbo)

​Key Build Tasks

​Running Turbo Tasks

​Utilities

​Running Utilities

​Yarn 4 Configuration

​Development Workflow

​Working with a Single Application

​Working Across Multiple Packages

​Adding Dependencies

​File Organization Patterns

​Next Steps

Installation Guide

Development Workflow

Package Development

Build System

Build docs developers (and LLMs) love

Overview

Root Directory Structure

Applications

Available Applications

Desktop Applications

Other Applications

Packages

Core Packages

Additional Packages

Workspace Configuration

Example: Application Dependencies

TypeScript Configuration

Build System (Turbo)

Key Build Tasks

Running Turbo Tasks

Utilities

Running Utilities

Yarn 4 Configuration

Development Workflow

Working with a Single Application

Working Across Multiple Packages

Adding Dependencies

File Organization Patterns

Next Steps