ProtonMail/WebClients: What the Proton Web Monorepo Actually Is

Who the Proton web monorepo is for, and who it is not for

The README opens by calling this a monorepo that hosts the Proton web clients, and lists nine of them: Proton Mail, Calendar, Drive, Account, VPN, Pass, Wallet, Lumo and Meet. Each has its own entry under applications/, with a favicon path such as ./applications/mail/src/favicon.svg. The stated scope goes beyond the apps themselves: shared modules, the tooling around development, and what the README calls "some additional miscellaneous things".

That framing sets the audience. This is the build repository for a product company's front end, not a reusable package. If you maintain a webmail product and want to see how a team organises nine applications over one dependency graph, the layout is the interesting part. If you want to add PGP mail to your own app, this repository is the wrong starting point: the README never describes a published npm package, a supported embed, or a stable public API for the mail application. Some workspace packages do carry scoped names such as @proton/components, @proton/shared and @proton/atoms, and the README mentions @proton/version, but it presents them as internals of this monorepo, not as a distribution channel.

The topics list confirms the mix: monorepo, pgp, react, webmail, yarn, alongside product names. PGP appears as a topic, yet the README's own body says nothing about how encryption is wired into the clients. Anyone arriving for the cryptography will find the README silent on it.

How the Yarn workspaces and shared packages fit together

The README states that the monorepo is based on Yarn and Yarn Workspaces, with unified versioning for all packages inside. The root package.json backs that up: it is private, licensed GPL-3.0, and its workspaces array globs applications/*, packages/*, packages/wasm/*, tests, tests/mail-renderer, tests/packages/*, utilities/* and vendor/*/*. There is also a specific entry for applications/pass-desktop/native and one for packages/pass/docs/starlight.

The data flow is the ordinary workspace one. A single yarn install at the root resolves the whole graph and symlinks local dependents to one another, so a change in packages/shared is picked up by applications/mail without a publish step. Unified versioning means the applications move together rather than versioning independently, which is why the README offers a manual version command scoped to one application at a time.

Two things stand out as deliberate choices. First, the dependency graph is heavily pinned: the resolutions block in package.json fixes transitive versions such as @protontech/crypto and applies a patch to @pdf-lib/standard-fonts through a .yarn/patches entry. That is a maintenance commitment, not a convenience. Second, the repository carries its own tooling rather than relying on defaults: turbo.json, knip.json, semgrep and grype configs, stylelint and prettier configs, and a lint-staged hook. The root scripts expose app-versions, check:branch, config-app, create-atom, knip, knip:staged and version. A postinstall hook runs husky and config-app unless CI is detected, which means a fresh clone writes local configuration before you run anything.

Installing the monorepo and starting Proton Mail

The README lists three prerequisites: Node.js LTS, Yarn 4 and git, and points at package.json for the exact version requirements. Clone the repository, then install once at the root. The README gives two clone URLs, HTTPS and SSH.

git clone https://github.com/ProtonMail/WebClients.git
cd WebClients
yarn install

The install resolves dependencies for the entire monorepo and symlinks local dependents to one another, as the README describes it. Expect the postinstall step to run husky and the config-app script on a non-CI machine.

Applications start through a workspace command named after the package. The README's example is the mail client:

yarn workspace proton-mail start

Substitute the matching workspace name for another application. The README does not list every workspace name, so read applications/*/package.json to confirm the one you want before running it.

There is a second path for running several applications at once, used in the VPN section:

yarn start-all --applications "proton-account"

That script changes into utilities/local-sso and runs run.sh, so the multi-application path brings up a local single sign-on service. If you only need one client, the single-workspace command avoids that.

The VPN split: two entry points and no shared local SSO

The most concrete architectural note in the README is about VPN. Proton VPN appears on both proton.me and protonvpn.com, and the two are served differently. Some parts are shared through @proton/components or @proton/shared, but the entry points differ: applications/vpn-settings is the entry for protonvpn.com, while account.proton.me/u/{X}/vpn is served from applications/account.

The consequence is stated plainly. Because the two domains are separate, there is no shared local SSO between them, so both applications must be served separately during development. The README gives one command with an explicit port for the vpn-settings path and a second command for the account path:

yarn workspace --port 8050 proton-vpn-settings start

Note the argument order here: the port flag sits between the workspace subcommand and the workspace name, which is not the shape most Yarn users expect. The README prints it that way, and the command is worth copying verbatim rather than reordering.

This is a good example of what the repository is really documenting: not a feature, but the local development topology that a shared front end forces on a team. Two domains, two entry points, shared components underneath, and an SSO boundary you have to reproduce on your machine.

Where the documentation stops short

The README is a starting point, not a manual, and several gaps are worth knowing before you clone.

There is no deployment documentation. Nothing describes how an application is built for production, where artifacts land, or what environment configuration is required. The config-app script and the packages/config/install path appear in package.json but are not explained in the README, so the reader has to infer their role from the file tree.

There is no rollback story. The README does not document rollback, and it does not describe a release process beyond a manual version bump. The version command is given as running from the main branch, "for a clean release", with an application and a four-part version:

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

What happens after that version is set, and how the artifact reaches users, is not in the README.

There is also no test walkthrough. The workspaces array includes tests, tests/mail-renderer and tests/packages/*, so test projects exist, but the README does not say how to run them. And the repository has no retrieved releases, so there is no changelog to fall back on for what changed between versions. For a codebase this size, that means reading source and commit history is part of onboarding, not an optional step.

The maintenance signal is the opposite kind of gap: the last push was on 2026-09-22, and the repository is not archived. Whatever the README omits, this is code that is being worked on now.

What a GPL-3.0 front end means for reuse

The root package.json declares GPL-3.0, and the README repeats it: the code and data files in this distribution are licensed under the GNU General Public License, version 3 or later, with a pointer to the LICENSE file.

For the intended audience, Proton's own engineers and contributors working on these clients, the licence is a given. For anyone else, it changes the calculus. GPL-3.0 is a copyleft licence, and the practical question of how it interacts with a proprietary product is a legal one that this article cannot answer. What can be said from the repository alone is narrower: the licence covers the code and data files in this distribution, and there is no separate permissive or commercial licensing option mentioned in the README. If you were hoping to lift @proton/components or a rendering module into a closed-source application, that is the point at which you need your own legal review, because the README offers no alternative path.

One adjacent note: the README links to a Proton blog post about the translation community. Translation contributions are routed through that process rather than through the repository's own documentation, so anyone planning to localise a fork should read the blog post first.

How this differs from a general-purpose web client library

The obvious comparison is Spring's WebClient, which dominates search results for the term. The two share a name and almost nothing else. Spring WebClient is a reactive, non-blocking HTTP client library that you add as a dependency and call from your own code. ProtonMail/WebClients is an application monorepo: it contains finished front ends, their components and their build tooling, and it is consumed by cloning and running it, not by importing it.

The difference in approach matters for evaluation. With a library, you judge the API surface, the release cadence and the dependency footprint. With this repository, you judge the workspace layout, the shared-package boundaries, and whether the build and local SSO setup fit your machine. A library answers "how do I make an HTTP call"; this repository answers "how do nine Proton web applications share components without forking each other".

If your actual need is an HTTP client, look at Spring WebClient or a comparable library and ignore this repository entirely. If your need is to understand or modify Proton's web front ends, no general-purpose library substitutes for it, because the value is in the specific arrangement of applications, packages and utilities that only exists here.

Editorial conclusion

Adopt this repository only if you are building or modifying a Proton web application itself, or need to read how Proton structures a large shared-component web monorepo. Do not adopt it if you want a mail client library, an embeddable PGP widget, or a drop-in replacement for your own webmail front end: nothing here is packaged for that, and the README documents no published artifact. Before you invest time, verify that Node.js LTS and Yarn 4 match the versions pinned in package.json, and check whether the SSO flow in utilities/local-sso is what your workflow needs, because the README states that the two VPN entry points do not share a local SSO between them.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. ProtonMail/WebClients on GitHub
4. README