Monorepo Best Practices: Implementing pnpm Workspaces and Changesets

Why choose pnpm

pnpm reduces disk usage and speeds up installations through hard links, enforces strict dependency management, and offers native monorepo support via workspaces.

Monorepo advantages

Code sharing, easier dependency management, atomic commits, and streamlined workflows improve development efficiency.

Monorepo disadvantages

Large repository size, complex permission management, and potential tight coupling can affect performance and flexibility.

Basic setup

Demo repository: https://github.com/huanmie913/sway-monorepo-pnpm-demo

Installation

// Install pnpm globally (recommended)
npm install -g pnpm
// Or install locally to a project
npm install pnpm

Initialize project

pnpm init

Script configuration

Add a preinstall script to package.json to enforce pnpm usage:

{
  "scripts": {
    "preinstall": "npx -y only-allow pnpm"
  }
}

Workspace configuration

Create pnpm-workspace.yaml at the repository root:

packages:
  - 'packages/**'
  - 'components/**'
  - '!**/test/**'

Common workspace commands

pnpm -w runs pnpm from the workspace root.

pnpm install -w installs dependencies to the root.

pnpm --filter <package> limits commands to specific packages.

Inter‑package dependencies

Use the workspace: protocol to reference local packages, e.g., add "@sway/monorepo-pkg-a": "workspace:^" to pkg-b 's dependencies .

{
  "dependencies": {
    "@sway/monorepo-pkg-a": "workspace:^"
  }
}

Building packages

Define a root build script that runs builds recursively:

{
  "scripts": {
    "build": "pnpm -r run build"
  }
}

Use pnpm run build at the root to build all packages in dependency order.

Watch mode

{
  "scripts": {
    "watch": "pnpm --parallel -r run watch"
  }
}

Changesets for versioning

Install Changesets:

pnpm i -Dw @changesets/cli

Initialize:

pnpm changeset init

Create a changeset when changes are ready:

pnpm changeset

Publish the first version:

pnpm changeset publish

For prereleases (alpha, beta, rc):

# alpha
pnpm changeset pre enter alpha
# beta
pnpm changeset pre enter beta
# rc
pnpm changeset pre enter rc

After testing, exit prerelease mode:

pnpm changeset pre exit

Finally, publish the official release:

pnpm changeset publish

References: Monorepo best practices with pnpm + Changesets