Working with multi-repos (linking during development)

[krmax44]

We're working on a multi-repo project, where each module lives in its own repository. Currently, we're stuck using pnpm v9, as it still has support for globally linking packages.

While we could use newer versions, pnpm link now changes the lockfile, which is cumbersome when committing and pushing changes (the links are only needed and only work locally during development).

Does pnpm offer some better way of working with multi-repo projects? I can only think of workarounds such as pre-commit hooks that undo the links before committing.

[ThiagoMafra-Integrare]

You hit this because of an intentional change in pnpm v10.0.0:

pnpm link command now adds overrides to the root package.json.

The team made linking explicit by design — anyone running pnpm install should reproduce the same dep graph, including local links. Great for reproducibility, painful for transient cross-repo dev work like yours.

For multi-repo development without lockfile pollution, three patterns work in the modern pnpm world:

1. .pnpmfile.cjs with env-gated overrides — in-tree, no third-party tools

Keep package.json clean, conditionally swap deps via a hook based on a local env var. The lockfile only changes when the env var is set, so it's a per-developer, per-session choice.

// .pnpmfile.cjs (or .pnpmfile.mjs in pnpm v11+)                                                                                                                                                                                   
function readPackage(pkg, context) {                                                                                                                                                                                               
  if (!process.env.PNPM_LOCAL_LINK) return pkg;                                                                                                                                                                                    
                                                                                                                                                                                                                                   
  const links = {                                                                                                                                                                                                                  
    'my-shared-lib': '../my-shared-lib',                                                                                                                                                                                           
    'design-tokens': '../design-tokens',                                                                                                                                                                                           
  };                                   
                                                                                                                                                                                                                                   
  for (const [name, path] of Object.entries(links)) {                                                             
    if (pkg.dependencies?.[name]) {                                                                                                                                                                                                
      pkg.dependencies[name] = `link:${path}`;
    }                                                                                                                                                                                                                              
    if (pkg.devDependencies?.[name]) {                                                                            
      pkg.devDependencies[name] = `link:${path}`;                                                                                                                                                                                  
    }                                                                                                             
  }                                    
  return pkg;                                                                                                                                                                                                                      
}
                                                                                                                                                                                                                                   
module.exports = { hooks: { readPackage } };                                                                      

Workflow:

PNPM_LOCAL_LINK=1 pnpm install   # local dev with links
pnpm install                      # regular install — clean lockfile                                                                                                                                                               

Gitignore the modified lockfile (pnpm-lock.yaml) only when working with PNPM_LOCAL_LINK=1 — practically, run git stash pnpm-lock.yaml before commits, or use a pre-commit hook to skip it. The advantage over your current
pre-commit-hook idea: nothing touches package.json, you don't have to undo anything; the pnpmfile is the source of truth and is intentional code.

2. yalc — most common community choice

yalc simulates a local publish flow, which sidesteps pnpm link entirely:

# in source repo                                                                                                  
cd ../my-shared-lib                                                                                                                                                                                                                
yalc publish
                                                                                                                                                                                                                                   
# in consumer repo                                                                                                
cd ../my-app                           
yalc add my-shared-lib    # gets stored in .yalc/, like a tarball install
pnpm install                                                                                                                                                                                                                       

It still modifies package.json (default behavior), but you can use yalc add --pure to keep package.json clean and only update .yalc/ + node_modules. Many pnpm multi-repo setups standardize on yalc precisely to escape
the pnpm link lockfile dance.

3. If you can consolidate — pnpm workspaces + inject-workspace-packages

Not always possible (you said multi-repo by choice), but if some of those repos are tightly coupled and would benefit from shared lockfile/release tooling, consolidating them under a workspace gives you workspace:* linking
with zero ceremony. The new inject-workspace-packages setting in v10+ hard-links workspace deps instead of symlinking, which mirrors how the consumer would see a
published version — useful when symlink behavior breaks something.

---

My recommendation: option 1 (.pnpmfile.cjs env-gated) if you want to stay 100% pnpm-native and have full audit trail.
Option 2 (yalc) if you want a more transparent "feels like a real install" experience and don't mind
one small extra tool in the loop.