Resolve your PNPM symlinks without breaking builds — use your pnpm-lock.yaml as the single source of truth for module resolution.
resolve-pkglock hooks into Node.js’ modern module customization hooks to resolve your workspace dependencies directly from the PNPM store instead of through symlinks. This is especially useful in environments where symlinks cause issues (e.g. Docker, certain CI/CD setups, or read-only deployments).
- PNPM uses symlinks in workspaces to deduplicate modules.
- Some deployment environments don’t preserve them.
- Luckily, everything needed for resolution is already in your pnpm-lock.yaml.
By using resolve-pkglock, you can resolve dependencies directly from the PNPM store based on your lockfile — no symlinks required.
- Node.js v22.15.0 or newer (supports module hooks).
- A correctly maintained
pnpm-lock.yamlin your workspace root.
Load the module early in your entrypoint before other imports:
// eslint-disable-next-line antfu/no-import-dist, antfu/no-import-node-modules-by-path
import resolvePkgLock from './node_modules/.pnpm/resolve-pkglock.../node_modules/resolve-pkglock/dist/index.js';
// Initialize with the path to your workspace root (where pnpm-lock.yaml lives)
await resolvePkgLock(import.meta.dirname);
// Then import your local packages normally
import('your-local-package');
⚠️ Make sure you’re referencing the non-symlinked folder in the PNPM store when importingresolve-pkglock.
With resolve-pkglock, you can set this safely in your pnpm-workspace.yaml:
symlink: falseThis fully avoids the creation of symlinks while preserving the benefits of PNPM’s deterministic lockfile.
MIT © ameinhardt