pnpm Workspace Cheatsheet — 60+ Commands for Monorepo Development

Root config file that declares which directories are workspace packages. Glob patterns under `packages:` select all matching directories.

packages:
  - "packages/*"
  - "apps/*"
  - "!**/__tests__/**"

(all subdirs of packages/ and apps/ become workspace packages)

⚠ Common pitfall: The file must live at the workspace root (same level as the root package.json). Putting it in a subdirectory silently does nothing.

# pnpm-workspace.yaml
packages:
  - "packages/*"
  - "apps/*"

# include a specific path too
packages:
  - "packages/*"
  - "tools/codegen"

Bootstrap the workspace root package.json. Add `"private": true` immediately — the root should never be published to npm.

⚠ Common pitfall: Forgetting `"private": true` on the root package means `pnpm publish` could accidentally publish your monorepo root.

pnpm init
# then add to package.json:
# "private": true

# root package.json minimum
{
  "name": "my-monorepo",
  "private": true,
  "version": "0.0.0"
}

Catalog pins shared dependency versions centrally in pnpm-workspace.yaml. Packages reference them with `catalog:` instead of a version string.

catalog:
  react: "^18.3.0"
  typescript: "^5.4.0"
# package.json in any workspace pkg:
# "react": "catalog:"

(all packages using "catalog:" get the same pinned version)

⚠ Common pitfall: catalog: requires pnpm 9+. On pnpm 8 or older, the field is silently ignored and packages get no version constraint, breaking installs.

# pnpm-workspace.yaml
catalog:
  react: "^18.3.0"
  vite: "^5.0.0"

# packages/ui/package.json
"dependencies": {
  "react": "catalog:"
}

Makes pnpm hoist all transitive deps to the root node_modules, mimicking npm/yarn. Fixes tools that reach into node_modules without declaring deps.

⚠ Common pitfall: shamefully-hoist hides phantom dependency bugs. Prefer `public-hoist-pattern[]=<pkg>` to hoist only the specific offending package.

# .npmrc
shamefully-hoist=true

# Better: only hoist the specific package
# .npmrc
public-hoist-pattern[]=*eslint*
public-hoist-pattern[]=*prettier*

Alternative to shamefully-hoist. Uses a flat hoisted node_modules layout without fully shameful hoisting — a middle ground for compatibility.

# .npmrc
node-linker=hoisted

# also useful for Next.js / Vercel deployments
# node-linker=hoisted
# strict-peer-dependencies=false

Installs all dependencies for every package in the workspace with a single command from the root.

pnpm install

# CI: fail if lockfile would change
pnpm install --frozen-lockfile

Print the built-in workspace command help. Useful for discovering subcommands.

pnpm workspace --help

pnpm --help | grep filter

Run a command only in the package whose `name` field in package.json matches exactly. The most common filter form.

pnpm --filter @myapp/ui run build

pnpm --filter my-backend run start:dev

Filter by directory path relative to the workspace root. The leading `./` is required to distinguish a path from a package name.

pnpm --filter "./apps/web" run dev

pnpm --filter "./packages/*" run test

Filter by a glob on the directory path. Curly braces wrap path globs in pnpm filter syntax.

pnpm --filter "{./packages/**}" run lint

pnpm --filter "{./apps/*}" run build

Trailing `...` adds the package AND all of its transitive dependencies. Useful to rebuild a package with everything it needs.

⚠ Common pitfall: The `...` is part of the filter string, not a shell glob. Quote it to prevent the shell from expanding it: `--filter "myapp..."` or `--filter 'myapp...'`.

pnpm --filter "@myapp/ui..." run build

pnpm --filter 'my-api...' run test

Select all packages that are dependants (consumers) of `<pkg>`. Run after changing a shared lib to re-test everything that imports it.

pnpm --filter '...^@myapp/utils' run test

pnpm --filter '...^@myapp/ui' run build

Select packages with files changed since the given git ref. The square brackets denote a git-based diff filter.

pnpm --filter "[main]" run build

pnpm --filter "[HEAD~1]" run test

pnpm --filter "[origin/main]" run lint

Select packages changed since git ref AND their dependants. Rebuilds everything that could be affected by the diff — the standard CI pattern.

⚠ Common pitfall: Without the leading `...`, only the changed packages run — their dependants may ship a broken build even though their dependencies changed.

pnpm --filter "...[origin/main]" run build

# GitHub Actions example:
pnpm --filter "...[origin/${{ github.base_ref }}]" run test

Multiple --filter flags are OR-ed together: the command runs in any package matching filter a OR filter b.

pnpm --filter @myapp/ui --filter @myapp/utils run lint

pnpm --filter "./apps/*" --filter "@myapp/shared" run build

Exclude a specific package from the filter set. The `!` negates the match.

pnpm --filter !@myapp/docs run build

pnpm -r --filter !legacy-package run test

List the dependency tree for a single workspace package.

pnpm ls --filter @myapp/ui

pnpm ls --filter @myapp/ui --depth 2

Filter all packages under a given scope using a wildcard. Matches any package whose name starts with @myapp/.

pnpm --filter "@myapp/*" run lint

pnpm --filter "@mycompany/*" run build

Run in specific package and a dependency together. Useful when you want to build a lib and its dependent consumer in one pass.

pnpm --filter @myapp/utils --filter @myapp/web run build

List every dependency across all workspace packages recursively. Helps audit what is installed where.

pnpm ls --recursive

pnpm ls -r --depth 0   # top-level only

Add a dependency to a specific workspace package from anywhere in the repo — no need to cd.

⚠ Common pitfall: Omitting --filter from the workspace root adds the dep to the ROOT package.json, not any child package. Usually wrong.

pnpm add react --filter @myapp/ui

pnpm add -D typescript --filter @myapp/utils

pnpm add lodash --filter "./packages/helpers"

Add a dependency to the workspace root (`-w` / `--workspace-root`). For shared dev tools like eslint, prettier, turbo.

⚠ Common pitfall: Root-level prod deps are unusual. Most root packages should be `"private": true`; add runtime deps to specific child packages instead.

pnpm add -Dw eslint prettier typescript turbo

pnpm add -Dw vitest

Fail if the lockfile would need to be updated instead of silently mutating it. Required in CI to detect out-of-sync lockfiles.

⚠ Common pitfall: Without --frozen-lockfile in CI, a developer who forgets to commit the updated lockfile will cause CI to silently install different versions than local.

# In CI (GitHub Actions, etc.)
pnpm install --frozen-lockfile

# Also equivalent:
pnpm ci

Install only the root workspace's own dependencies, skipping all child packages. Rarely needed; useful for a root-only tool install step.

pnpm install --ignore-workspace

Update a specific dependency in one workspace package to its latest allowed version.

pnpm update --filter @myapp/ui react

pnpm update --filter @myapp/api --latest

Update all dependencies across all workspace packages to their latest versions allowed by the semver ranges in each package.json.

⚠ Common pitfall: After pnpm update -r, always run the full test suite. A batch update can surface subtle incompatibilities between packages.

pnpm update -r

pnpm update -r --latest   # ignore semver ranges

Show why a package is installed in a specific workspace package — which dependency chain pulled it in.

pnpm why lodash --filter @myapp/web

pnpm why esbuild --filter @myapp/build

Reduce the number of packages in the lockfile by deduplicating dependency versions across the workspace.

pnpm dedupe

# check what would be deduped without changing anything:
pnpm dedupe --check

Remove a dependency from a specific workspace package and update its package.json.

pnpm remove lodash --filter @myapp/utils

pnpm remove -D eslint --filter @myapp/web

Run a script recursively in all workspace packages that define it. `-r` is short for `--recursive`.

⚠ Common pitfall: pnpm -r run exits non-zero if ANY package's script fails. Use --if-present to skip packages that don't have the script instead of erroring.

pnpm -r run build

pnpm -r run test

pnpm -r run lint

Recursively run a script but silently skip packages that don't define it. Prevents errors in heterogeneous monorepos.

pnpm -r run build --if-present

pnpm -r run generate --if-present

Run a script in a specific workspace package. Equivalent to cd-ing into the package and running `pnpm run <script>`.

pnpm run --filter @myapp/web dev

pnpm run --filter @myapp/api start

Run the script in all packages in parallel rather than respecting the dependency graph order. Faster for independent tasks; dangerous if packages depend on each other's build outputs.

⚠ Common pitfall: With --parallel, pnpm builds package A and B at the same time even if B imports A. If B's build starts before A's build finishes, B fails. Omit --parallel when there are build-order dependencies.

pnpm -r run test --parallel

pnpm -r run lint --parallel

Stream output from all packages to the terminal interleaved, prefixed with the package name. Default without --stream is to buffer per-package and print sequentially.

pnpm -r run dev --stream

pnpm -r run test --stream --parallel

Execute a shell command inside a specific package directory, with the package's node_modules/.bin on PATH.

pnpm exec --filter @myapp/web tsc --noEmit

pnpm exec --filter @myapp/api prisma migrate dev

Execute a shell command recursively in every workspace package directory.

pnpm -r exec -- node -e "console.log(process.env.npm_package_name)"

pnpm -r exec rm -rf dist

Pass extra arguments to a package script using `--` separator. Everything after `--` is forwarded to the script.

pnpm --filter @myapp/web run build -- --mode production

pnpm --filter @myapp/api run test -- --watch

Limit how many packages build in parallel. Default is 4. Lower it to reduce memory pressure on CI machines with many packages.

pnpm -r run build --workspace-concurrency 2

pnpm -r run test --workspace-concurrency 1   # serial

Reference a local workspace package and resolve at publish time to the exact version in that package's package.json. Best for apps that don't publish to npm.

# package.json of packages/web
"dependencies": {
  "@myapp/ui": "workspace:*"
}

# After `pnpm changeset publish` replaces workspace: refs:
"@myapp/ui": "2.1.0"

"@myapp/ui": "workspace:*"

"@myapp/utils": "workspace:*"

At publish time resolves to a caret range `^X.Y.Z` using the local version. Standard for publishable libraries that depend on sibling packages.

"@myapp/utils": "workspace:^"
# @myapp/utils is currently at 3.0.0

"@myapp/utils": "^3.0.0"   # in published package.json

⚠ Common pitfall: Using workspace:* on a publishable library publishes `"dep": "exact-version"` (no caret). Consumers are pinned to that exact version and can't get patches automatically.

"@myapp/types": "workspace:^"

"@myapp/core": "workspace:^"

At publish time resolves to a tilde range `~X.Y.Z` — allows patch updates but not minor. More conservative than workspace:^.

"@myapp/config": "workspace:~"

Pin to an explicit version that must exist as a workspace package. Rarely needed; prefer workspace:* for most cases.

"@myapp/legacy": "workspace:1.0.0"

pnpm pack automatically replaces workspace: protocol references with resolved version strings in the tarball's package.json — no manual step needed.

# From the package directory:
pnpm pack
# Inspect the tarball to verify resolved deps:
tar -tf my-package-1.0.0.tgz

Link a workspace package globally so other projects outside the monorepo can consume the local version during development.

⚠ Common pitfall: Global links are not tracked by git and break for teammates who clone fresh. Use the workspace protocol for inter-repo linking; global link is a personal dev hack.

pnpm link --filter @myapp/utils --global

# Then in the consumer project:
pnpm link --global @myapp/utils

Create a .tgz tarball for a specific workspace package to inspect what will actually be published, including resolved workspace: refs.

pnpm pack --filter @myapp/utils

# Inspect the tarball:
tar -tzf myapp-utils-1.0.0.tgz | head -30

Create a changeset file describing what changed and the intended version bump type (major / minor / patch). Run this when opening a PR with user-facing changes.

⚠ Common pitfall: changesets requires the @changesets/cli package installed at the workspace root. Add it with `pnpm add -Dw @changesets/cli`.

pnpm changeset
# interactive CLI: select packages, bump type, and description

# or with --empty for a no-bump changeset:
pnpm changeset --empty

Consume all pending changeset files, bump package.json versions accordingly, and update CHANGELOG.md files. Run after merging a release PR.

pnpm changeset version

# Preview what would change:
pnpm changeset status

Publish all packages whose version has changed to npm. Runs `pnpm build` (or the configured publish script) per package first.

⚠ Common pitfall: Requires npm login (`npm login`) or an NPM_TOKEN env var. Without it, publish fails with 401 Unauthorized.

pnpm changeset publish

# dry-run to see what would publish:
pnpm changeset publish --dry-run

Publish a single workspace package to npm without changesets. Useful for manual hotfix releases.

pnpm publish --filter @myapp/utils

pnpm publish --filter @myapp/utils --access public --no-git-checks

Publish all workspace packages to npm, setting them all to public access. Needed for scoped packages (@scope/name) which default to restricted.

⚠ Common pitfall: Scoped packages (@myorg/pkg) are private by default on npm. Without `--access public` you'll get a 402 Payment Required error.

pnpm -r publish --access public

pnpm -r publish --access public --no-git-checks

Bump the version of a single workspace package (patch / minor / major). Writes the new version to package.json.

pnpm version --filter @myapp/utils patch

pnpm version --filter @myapp/api minor

pnpm's default strict node_modules layout means packages can only import what they explicitly list in their own package.json. Importing a transitive dep that isn't declared causes a MODULE_NOT_FOUND error — but only at runtime.

⚠ Common pitfall: If `import "some-package"` works in your npm project but fails in pnpm, that's a phantom dependency. Fix it by adding `some-package` to the correct package.json devDependencies. Don't hide it with shamefully-hoist.

# To find which package actually owns some-package:
pnpm why some-package --filter @myapp/web

pnpm lockfile format changes across major versions. After upgrading pnpm, run `pnpm install` to regenerate the lockfile with the new format before committing.

⚠ Common pitfall: Committing a lockfile in the old format after a pnpm upgrade causes every team member (and CI) to get a "ERR_PNPM_LOCKFILE_MISSING_DEPENDENCY" or format mismatch error until they regenerate locally.

# After upgrading pnpm:
pnpm install
git add pnpm-lock.yaml
git commit -m "chore: regenerate lockfile for pnpm vX"

Renaming a workspace package (changing its `name` in package.json) without updating all `workspace:` references in sibling packages breaks the install.

⚠ Common pitfall: pnpm install will fail with "No matching version found for @old/name" because the workspace protocol looks for the name, not the directory.

# After renaming @myapp/foo to @myapp/bar:
# 1. Update all "workspace:*" refs from @myapp/foo → @myapp/bar
# 2. pnpm install
# grep to find all stale references:
grep -r "@myapp/foo" packages/ apps/

pnpm surfaces peer dependency issues more aggressively than npm. A `WARN … peer dependencies unmet` message may not break the build but can indicate real compatibility issues.

⚠ Common pitfall: Setting `strict-peer-dependencies=false` in .npmrc silences the warnings but doesn't fix the underlying issue. Investigate before silencing.

# To silence peer dep warnings globally (use sparingly):
# .npmrc
strict-peer-dependencies=false

# To see what peer deps are unmet:
pnpm ls --depth 1 --filter @myapp/web

Using `workspace:*` in a package you publish to npm means consumers get `"dep": "1.2.3"` (pinned exact). They can't receive patches without updating the whole parent — use `workspace:^` instead.

# Wrong for published libs:
"@myapp/utils": "workspace:*"
# Right for published libs:
"@myapp/utils": "workspace:^"

Running `pnpm run dev` from the workspace root when you mean to run it for one specific package runs the root package's `dev` script (often undefined) instead.

⚠ Common pitfall: If the root has no `dev` script you'll get "ERR_PNPM_NO_SCRIPT". Either use `--filter` or cd into the package directory first.

# Always use --filter from root:
pnpm run --filter @myapp/web dev
# Or cd first:
cd apps/web && pnpm run dev

Running plain `pnpm install` in CI lets pnpm update the lockfile silently if package.json drifted. Always use `pnpm install --frozen-lockfile` or `pnpm ci` in automated pipelines.

# .github/workflows/ci.yml
- run: pnpm install --frozen-lockfile

# equivalent shorthand:
- run: pnpm ci

The `catalog:` specifier in package.json is silently treated as an unknown version on pnpm < 9 — packages install with no version constraint, or the install fails outright.

⚠ Common pitfall: Run `pnpm --version` before adopting catalog:. If your team or CI has mixed pnpm versions, enforce a minimum with `engines.pnpm` in the root package.json.

# root package.json
"engines": {
  "pnpm": ">=9.0.0"
}

# Also add to .npmrc:
engine-strict=true

If you use Turborepo with pnpm workspaces, renaming a package or changing workspace: refs invalidates turbo's dependency graph hash. Run `turbo run build --force` to bust the cache after structural changes.

turbo run build --force

# Or delete the .turbo directory:
rm -rf .turbo && turbo run build