Skip to main content
The Proton WebClients monorepo contains a collection of packages that power all Proton web applications. This document provides an overview of the core packages and their relationships.

​
Core Packages

The monorepo is organized into several categories of packages:

@proton/shared

Core utilities, constants, API clients, and business logic shared across all Proton applications.

@proton/components

React component library with UI components and containers for building Proton applications.

@proton/hooks

Generic, business-agnostic React hooks for common use cases.

@proton/atoms

Atomic design system components - the foundational building blocks.

​
Package Dependencies

The packages follow a layered architecture where lower-level packages are dependencies of higher-level ones.

​
Dependency Flow

  1. @proton/hooks - Pure React hooks with no business logic dependencies
  2. @proton/atoms - Basic UI components using hooks
  3. @proton/shared - Business logic, API clients, utilities (peer dependency on hooks)
  4. @proton/components - Complex components and containers combining atoms, shared, and hooks

​
Additional Packages

The monorepo includes many other specialized packages:

​
Infrastructure & Tooling

  • @proton/eslint-config-proton - Shared ESLint configuration
  • @proton/prettier-config - Shared Prettier configuration
  • @proton/testing - Testing utilities and helpers
  • @proton/pack - Build tooling and webpack configurations

​
Design System

  • @proton/styles - SCSS styles and design tokens
  • @proton/colors - Color palette and theming
  • @proton/icons - SVG icon library

​
Application-Specific

  • @proton/account - Account management functionality
  • @proton/calendar - Calendar-specific logic
  • @proton/mail - Mail-specific logic
  • @proton/drive - Drive-specific logic
  • @proton/pass - Pass password manager logic
  • @proton/wallet - Wallet cryptocurrency functionality

​
Specialized Libraries

  • @proton/crypto - Cryptographic operations wrapper
  • @proton/srp - Secure Remote Password protocol implementation
  • @proton/metrics - Analytics and metrics collection
  • @proton/payments - Payment processing and subscriptions

​
Technology Stack

  • TypeScript - All packages are written in TypeScript
  • React 18 - UI framework
  • SCSS - Styling
  • Webpack 5 - Module bundler
  • Babel - JavaScript compiler
  • ts-loader - TypeScript loader for Webpack
  • Jest - Test runner
  • Testing Library - React component testing
  • Karma - Test runner for some packages
  • Yarn Workspaces - Monorepo management
  • Package references use workspace:^ protocol

​
Getting Started

To use these packages in a Proton application: 
# Install dependencies
yarn install

# Build all packages
yarn workspace @proton/shared build
yarn workspace @proton/components build

# Run tests
yarn workspace @proton/hooks test

​
Package Guidelines

Side Effects: All core packages set "sideEffects": false in package.json to enable optimal tree-shaking.
Imports: Use specific imports from packages rather than barrel imports for better tree-shaking:
// Good
import { useLoading } from '@proton/hooks';

// Also good for atoms (uses package.json exports)
import { Button } from '@proton/atoms/Button/Button';

​
Next Steps

Explore the individual package documentation:

Build docs developers (and LLMs) love

Get started for freeTalk to us