meyverick PNPM Workspace Management
This skill governs the configuration and strict dependency resolution of pnpm monorepos. It prevents "ghost dependency" leaks and guarantees deterministic, highly cached builds across environments.
When to Use
- Use when initializing a new monorepo
pnpm-workspace.yaml. - Use when adding dependencies across multiple shared packages (
pnpm --filter). - NOT for standard
npmoryarnrepositories.
Core Process
Phase 1: Strict Boundaries
pnpmuses a symlinkednode_modulesstructure to prevent ghost dependencies (packages accessible without being explicitly inpackage.json).- If a package needs a dependency, it MUST be explicitly installed in that specific package's
package.json, not just at the monorepo root.
Phase 2: Workspace Filtering
- Never
cdinto a directory to run an install. - Always use workspace filtering from the root:
pnpm --filter @my-org/frontend add lodash.
Phase 3: Lockfile Integrity
- The
pnpm-lock.yamlis the ultimate source of truth. Never manually edit it. - In CI/CD pipelines, always run
pnpm install --frozen-lockfileto ensure deterministic builds.
Common Rationalizations
| Rationalization | Reality |
|---|---|
"I'll just run npm install because pnpm is throwing an error." |
Mixing package managers destroys the lockfile and creates bizarre symlink errors. In a pnpm workspace, npm install is strictly forbidden. |
| "It works locally, so the dependency must be there." | Ghost dependencies work locally if hoisted by accident. CI will fail. Explicitly define all imports in package.json. |
Red Flags
- The existence of a
package-lock.jsonoryarn.lockinside a pnpm workspace. - Using
cd packages/api && pnpm installinstead ofpnpm --filter.
Verification
Before concluding workspace management:
- Only a single
pnpm-lock.yamlexists at the root. - All packages define their exact dependencies explicitly (no relying on root hoisting).
- CI scripts enforce
--frozen-lockfile.