And how do I preserve links in new installations of the repo?

I will be honest I have never been able to use pnpm link without any issues. So I always turn to pnpm pack

• How can we install deps when using pnpm link?

#3034

Even as a longtime user of pnpm, this is a critical issue for me, and apparently for many others because it is currently the most upvoted issue. While both npm and yarn have comprehensive docs in a guide/tutorial format that gives examples of everyday usage, PNPM's current docs don't provide even the most basic information needed for successful usage. I used to use npm link fairly regularly but almost never attempt to try to use pnpm link because of my prior bad experience.

NPM and yarn also have their respective tutorial blog posts and articles, usually as the second Google result after the official docs. Meanwhile this issue (to improve the docs) is the second result, not a good sign.

The most useful resources for me on pnpm link after writing this have been the StackOverflow post and a rather hilarious Twitter thread, specifically this answer.

This is a great project, and I appreciate everyone's work on it! I know eventually we'll have the docs we all want.

The stack overflow solution outlined here was what I was looking for.

There are three ways.

You may use the file protocol to reference your local lib:

{
  "dependencies": {
    "lib": "file:../lib"
  }
}

In this case, pnpm will create hard links to each file of lib. It will look like lib is copied to the node_modules of your app.

You may use the link protocol:

{
  "dependencies": {
    "lib": "link:../lib"
  }
}

In this case, pnpm will create a symlink to your lib in app/node_modules/lib.

Or you may pack your lib into a tarball with pnpm pack and then install it through the file protocol

{
  "dependencies": {
    "lib": "file:../lib/lib-1.0.0.tgz"
  }
}

There is no way to "publish to a local store".

With this context

• /home/projects/myapp : local git repo of myapp, containing in its dependencies "mylib": "https://mygitlab.tld/team/mylib.git"
• /home/projects/mylib : local git repo of mylib

I want to dev mylib with local live testing in myapp, without changing myapp:package.json dependencies.

To achieve this, in /home/projects/myapp I run pnpm link ../mylib and /home/projects/myapp/node_modules/mylib is now symlinked to /home/projects/mylib (instead of /home/projects/myapp/node_modules/.pnpm/mygitlab.tld+team+mylib…), so a pnpm start launched in myapp have a hot reload working fine on each change in /home/projects/mylib.

It works even if mylib name isn't mylib, if its name is @myteam/lib in its package.json, then the pnpm link ../mylib will symlink /home/projects/myapp/node_modules/@myteam/lib to /home/projects/mylib

To have the same result, you can also make the link global (register your local copy in your local pnpm store then using it)

• in /home/projects/mylib run pnpm link --global
• in /home/projects/myapp run pnpm link --global mylib (if mylib name is @myteam/lib it should be pnpm link --global @myteam/lib)

Using this way can be easier if mylib is used in many places and you want to switch quickly from a mylib git worktree to another one (just have to run pnpm link --global in the mylib dir you want to use, without having to relink all uses of it).

(same reply made on the stackoverflow post)

@nachoaldamav has improved the link and unlink command docs:

• docs: improve link docs pnpm.io#442
• docs: unlink improvements pnpm.io#443

Is there a difference between
pnpm link <dir>
and
pnpm link --dir <dir>?

The docs after the above PRs now have a confusing inconsistency between the description and example:
Links package from <dir> folder to node_modules of package from where you're executing this command or specified via --dir option.

For example, if you are inside ~/projects/foo and you execute pnpm link --dir ../bar, then foo will be linked to bar/node_modules/foo.

These seem to be saying the opposite thing. The description says "be inside the folder you want a package to be linked to, then tell the command where that package that you want linked is located"

The example is saying "be inside the package you want linked, and then tell the command where the package you want it linked to is located. Which is the opposite of what the descriptions says.

pnpm link <dir> will link <dir> inside the current directory, pnpm link --dir <dir> will link the current directory to the target directory (<dir>)

I made this diagram to show how it works

# The current directory is foo
pnpm link ../bar

- foo
  - node_modules
    - bar -> ../../bar
- bar

# The current directory is bar
pnpm link --dir ../foo

- foo
  - node_modules
    - bar -> ../../bar
- bar

# You can test it here https://stackblitz.com/edit/stackblitz-starters-1bwgba

I think the docs page could then benefit from another example that shows the opposite use, since right now the example is demonstrating only one of the two possible ways to use it while the description is talking about the other