Monorepo: what it is and how to set it up with pnpm
A monorepo stores the code of many projects in one repository. The other approach, called multi-repo, gives each project its own repository. The pnpm workspace documentation (opens in a new tab) also calls monorepos “monolithic repositories.”
Benefits of monorepos
Google’s 2016 article on keeping all of its code in one repository documents some of these benefits: Why Google stores billions of lines of code in a single repository (opens in a new tab).
- Code sharing: projects can use each other’s code directly. The code does not need to be copied to another repository.
- Large-scale refactoring: changes that touch many projects are easier to make.
- Simpler dependencies. The Google article names this benefit for its internal code. In pnpm, a
cataloginpnpm-workspace.yamlstores a dependency’s version range as a reusable constant. Packages use it throughcatalog:, which makes it easier to keep one version of each dependency across the workspace. - Collaboration: teams can read each other’s code and find APIs they can reuse.
- Atomic commits: one commit can hold changes across several projects.
Challenges of monorepos
- Repository size: the repository can grow over time. GitHub recommends that the
.gitfolder be no larger than 10 GB, because large repositories slow down fetches and lengthen clone times. - Build complexity: build tools have to handle many projects at once. Google lists investment in tooling as one of three categories of monorepo cost.
- One change can break other packages: packages that depend on a package with
workspace:use its latest code right away. - Access control: GitHub permissions apply to each repository. CODEOWNERS decides who is asked to review changes in a folder. If part of the code must be restricted, consider a separate repository.
- Git performance: Git operations can slow down at large scale. Git has sparse checkout to load only certain folders, and partial clone for very large repositories.
Setting up a monorepo with pnpm
pnpm has built-in workspace support for monorepos. The steps below are written for pnpm 12. The result is three packages: project-a, project-b, and shared-utils.
Create the root folder
mkdir my-monorepo
cd my-monorepo
pnpm initpnpm init creates package.json. The command also fills in the packageManager field with the pnpm version.
Create pnpm-workspace.yaml
Create a pnpm-workspace.yaml file in the root folder. The packages key holds the patterns for the package folders.
packages:
- 'packages/*'This pattern matches each folder one level below packages/.
Create the folders and packages
mkdir -p packages/project-a packages/project-b packages/shared-utils
cd packages/project-a
pnpm init
cd ../project-b
pnpm init
cd ../shared-utils
pnpm initThe package name follows the folder name. The shared-utils folder produces a package named shared-utils.
Link local packages
Declare dependencies on local packages with the workspace: protocol. By default, pnpm fetches a package from the registry when this protocol is not used.
Add this to packages/project-a/package.json:
{
"dependencies": {
"shared-utils": "workspace:*"
}
}Then run pnpm install from the root folder. The command links shared-utils to project-a and creates pnpm-lock.yaml in the root.
workspace:* accepts only local packages. When a package is published, pnpm replaces that value with a version number.
Add scripts at the root
Replace the contents of scripts in the root package.json with this:
{
"scripts": {
"dev": "pnpm -r --parallel run dev",
"build": "pnpm -r run build",
"test": "pnpm -r run test"
}
}The pnpm -r command runs a script in every package and skips the root folder. It also skips packages that do not have that script.
The build and test scripts run in dependency order. So shared-utils finishes building before project-a.
The dev script uses --parallel. Without this flag, pnpm waits for a dependency’s dev script to finish before it starts the packages that use it. If that dev script runs a server, it never finishes, so the packages that depend on it never start.
The default test script from pnpm init always fails with Error: no test specified. Replace it with a real test in packages that already have tests, or delete it from packages that do not. If the placeholder stays, pnpm test stops with an error. If no package has a test script, pnpm test finishes without an error but runs no tests.
Other tools
pnpm handles package linking and running scripts. The tasks setting (opens in a new tab) determines the order of scripts when one runs across many packages at once.
pnpm 12.4 adds the pnpm pipeline (opens in a new tab) command. It runs tasks only for projects that changed compared with origin/main. Projects that depend on them also run. For tasks that declare outputs, it uses cached results when they are available. The command needs a pipelines list in pnpm-workspace.yaml. The feature is still experimental, so its configuration and output may change. A plain pnpm -r run never uses this cache.
Turborepo (opens in a new tab) and Nx (opens in a new tab) also cache task results. Nx has nx affected, which runs only the tasks that a change affects.
Example folder structure
This structure uses pnpm. Only folders that match a pattern in pnpm-workspace.yaml become packages. So tools/ and docs/ are not pnpm packages.
my-monorepo/
├── package.json
├── pnpm-workspace.yaml
├── .gitignore
├── README.md
├── packages/
│ ├── project-a/
│ │ ├── package.json
│ │ ├── src/
│ │ │ └── index.js
│ │ └── tests/
│ │ └── index.test.js
│ ├── project-b/
│ │ ├── package.json
│ │ ├── src/
│ │ │ └── index.js
│ │ └── tests/
│ │ └── index.test.js
│ └── shared-utils/
│ ├── package.json
│ └── src/
│ └── utils.js
├── tools/
│ └── build-scripts/
│ └── build.js
└── docs/
├── project-a/
│ └── README.md
└── project-b/
└── README.mdpackages/holds all projects and packages.project-aandproject-bare separate example projects in the monorepo.shared-utilsis a package that other projects use.tools/holds build scripts and other utilities used across the monorepo.docs/holds documentation for each project.
Managing a monorepo with GitHub
GitHub has several features for managing monorepos.
GitHub Actions workflows
You can limit a GitHub Actions workflow with the paths filter under on.push. With this filter, the workflow runs only when files in certain folders change. The GitHub Actions documentation on path filters (opens in a new tab) describes the patterns you can use.
Branch protection rules
Branch protection rules control what can be merged into the main branch. You can require status checks to pass, or a review, before a merge. GitHub also offers rulesets as another way to manage branches.
The CODEOWNERS file
The CODEOWNERS file sets who is asked to review changes in a folder. Put it in .github/CODEOWNERS. The following line makes the team @org/tim-a the owner of the project-a folder:
/packages/project-a/ @org/tim-aThe owning team must be visible (a team setting on GitHub) and have write access to the repository, even when each of its members already has write access. When a pull request that is not a draft changes files in that folder, GitHub asks the owners to review it automatically. Approval from owners is required only if the branch rule enables “Require review from Code Owners”.
GitHub Projects
GitHub Projects helps you track work across packages in one table or board.
Good practices
-
Use Conventional Commits, for example
feat(ui): add copy button. This format makes it easier to generate changelogs and set versions automatically. -
Set up a linter and a formatter, such as ESLint and Prettier, so the code style stays consistent.
-
Automate as much as possible with GitHub Actions, for example for testing, builds, and deployment.
-
Write a clear README for each project and for the monorepo root.
-
Record release changes with
pnpm change. This command creates a Markdown file in the.changeset/folder. Then runpnpm version -rto bump the versions and write the changelogs. This workflow is built into pnpm. See the pnpm versioning documentation (opens in a new tab) for details.The files use the Changesets format. If you prefer the Changesets CLI, install
@changesets/cliin the root withpnpm add -Dw @changesets/cli, then runpnpm changeset init. After that,pnpm changesetcreates a changeset, andpnpm changeset versionupdates the versions and changelogs. The pnpm guide to Changesets (opens in a new tab) has the details.
When to use a monorepo
In my view, a monorepo is most useful for projects that depend on each other. For standalone projects, multi-repo can be simpler.
Google’s 2018 case study (opens in a new tab) also lists the strengths of multi-repo: freedom to choose tools, and benefits for access control and stability.
