pnpm Workspace Generator

pnpm-workspace.yaml is the configuration file that tells pnpm which directories in your repository contain workspace packages. By listing glob patterns such as 'packages/*' or 'apps/*', pnpm treats those directories as local packages and links them together automatically. Without this file, pnpm treats your repository as a single package and does not enable monorepo features like shared dependencies or cross-package linking.

Introduced in pnpm v9, the catalog feature lets you define a set of canonical dependency versions in pnpm-workspace.yaml under the 'catalog:' key. Individual packages in the workspace can then reference these versions using 'catalog:' as a version specifier in their package.json instead of hard-coding a version string. This keeps all packages in sync and makes version bumps a single-file change.

Use overrides when you need to force every package in the workspace to use a specific version of a transitive dependency — for example, to patch a security vulnerability in a deeply nested package, or to resolve conflicting peer dependency requirements between packages. Overrides are a last resort; prefer updating the direct dependency first.

Only enable shamefullyHoist if you have a tool or framework that relies on Node.js resolution finding packages directly in the root node_modules directory rather than through pnpm's isolated symlink layout. Examples include some older Webpack plugins or tools that use require.resolve without traversing symlinks. Enabling it trades strictness for compatibility and can hide missing dependency declarations.

All three fields serve the same purpose — forcing a specific version of a transitive dependency — but have different syntax and scope. npm uses 'overrides' in package.json, Yarn uses 'resolutions', and pnpm uses 'overrides' in either package.json or pnpm-workspace.yaml. Placing overrides in pnpm-workspace.yaml applies them workspace-wide across all packages, which is usually what you want in a monorepo.