1---
2name: pnpm-workspaces
3description: Monorepo support with workspaces for managing multiple packages
4---
5 
6# pnpm Workspaces
7 
8pnpm has built-in support for monorepos (multi-package repositories) through workspaces.
9 
10## Setting Up Workspaces
11 
12Create `pnpm-workspace.yaml` at the repository root:
13 
14```yaml
15packages:
16  # Include all packages in packages/ directory
17  - 'packages/*'
18  # Include all apps
19  - 'apps/*'
20  # Include nested packages
21  - 'tools/*/packages/*'
22  # Exclude test directories
23  - '!**/test/**'
24```
25 
26## Workspace Protocol
27 
28Use `workspace:` protocol to reference local packages:
29 
30```json
31{
32  "dependencies": {
33    "@myorg/utils": "workspace:*",
34    "@myorg/core": "workspace:^",
35    "@myorg/types": "workspace:~"
36  }
37}
38```
39 
40### Protocol Variants
41 
42| Protocol | Behavior | Published As |
43|----------|----------|--------------|
44| `workspace:*` | Any version | Actual version (e.g., `1.2.3`) |
45| `workspace:^` | Compatible version | `^1.2.3` |
46| `workspace:~` | Patch version | `~1.2.3` |
47| `workspace:^1.0.0` | Semver range | `^1.0.0` |
48 
49## Filtering Packages
50 
51Run commands on specific packages using `--filter`:
52 
53```bash
54# By package name
55pnpm --filter @myorg/app build
56pnpm -F @myorg/app build
57 
58# By directory path
59pnpm --filter "./packages/core" test
60 
61# Glob patterns
62pnpm --filter "@myorg/*" lint
63pnpm --filter "!@myorg/internal-*" publish
64 
65# All packages
66pnpm -r build
67pnpm --recursive build
68```
69 
70### Dependency-based Filtering
71 
72```bash
73# Package and all its dependencies
74pnpm --filter "...@myorg/app" build
75 
76# Package and all its dependents
77pnpm --filter "@myorg/core..." test
78 
79# Both directions
80pnpm --filter "...@myorg/shared..." build
81 
82# Changed since git ref
83pnpm --filter "...[origin/main]" test
84pnpm --filter "[HEAD~5]" lint
85```
86 
87## Workspace Commands
88 
89### Install dependencies
90```bash
91# Install all workspace packages
92pnpm install
93 
94# Add dependency to specific package
95pnpm --filter @myorg/app add lodash
96 
97# Add workspace dependency
98pnpm --filter @myorg/app add @myorg/utils
99```
100 
101### Run scripts
102```bash
103# Run in all packages with that script
104pnpm -r run build
105 
106# Run in topological order (dependencies first)
107pnpm -r --workspace-concurrency=1 run build
108 
109# Run in parallel
110pnpm -r --parallel run test
111 
112# Stream output
113pnpm -r --stream run dev
114```
115 
116### Execute commands
117```bash
118# Run command in all packages
119pnpm -r exec pwd
120 
121# Run in specific packages
122pnpm --filter "./packages/**" exec rm -rf dist
123```
124 
125## Workspace Settings
126 
127Configure in `.npmrc` or `pnpm-workspace.yaml`:
128 
129```ini
130# Link workspace packages automatically
131link-workspace-packages=true
132 
133# Prefer workspace packages over registry
134prefer-workspace-packages=true
135 
136# Single lockfile (recommended)
137shared-workspace-lockfile=true
138 
139# Workspace protocol handling
140save-workspace-protocol=rolling
141 
142# Concurrent workspace scripts
143workspace-concurrency=4
144```
145 
146## Publishing Workspaces
147 
148When publishing, `workspace:` protocols are converted:
149 
150```json
151// Before publish
152{
153  "dependencies": {
154    "@myorg/utils": "workspace:^"
155  }
156}
157 
158// After publish
159{
160  "dependencies": {
161    "@myorg/utils": "^1.2.3"
162  }
163}
164```
165 
166Use `--no-git-checks` for publishing from CI:
167```bash
168pnpm publish -r --no-git-checks
169```
170 
171## Best Practices
172 
1731. **Use workspace protocol** for internal dependencies
1742. **Enable `link-workspace-packages`** for automatic linking
1753. **Use shared lockfile** for consistency
1764. **Filter by dependencies** when building to ensure correct order
1775. **Use catalogs** for shared external dependency versions
178 
179## Example Project Structure
180 
181```
182my-monorepo/
183├── pnpm-workspace.yaml
184├── package.json
185├── pnpm-lock.yaml
186├── packages/
187│   ├── core/
188│   │   └── package.json
189│   ├── utils/
190│   │   └── package.json
191│   └── types/
192│       └── package.json
193└── apps/
194    ├── web/
195    │   └── package.json
196    └── api/
197        └── package.json
198```
199 
200<!-- 
201Source references:
202- https://pnpm.io/workspaces
203- https://pnpm.io/filtering
204- https://pnpm.io/npmrc#workspace-settings
205-->
206