Link and Test Local Packages with pnpm link

When you're developing a JavaScript library, it often needs to be tested in a real project. pnpm link is an extremely useful tool that allows you to add your locally developed package to other projects, facilitating easy testing and debugging. This article will detail how to use pnpm link, including its two main linking modes, and address some potential issues with pnpm link.

Global Link

Global Link lets you "publish" a library to your local global environment, making it easy to add it to any other local project.

Step 1: "Publish" the library in the Global Environment

cd ~/projects/my-lib
pnpm link --global

Step 2: Add the Global Link Package to a Project

cd ~/projects/my-app
pnpm link --global my-lib

Unlink Globally

To unlink all projects from my-lib, execute pnpm remove --global my-lib from any location in the system.

Unlink from an Individual Project

If my-app's package.json already includes my-lib as a dependency, use the following command to unlink:

cd ~/projects/my-app
pnpm i # Restore all links
# Or
pnpm unlink my-lib # Restore only the link of my-lib

Issues with Global Binary

It's worth noting that there are currently issues with the Global binary feature of pnpm link. According to the official documentation, pnpm link -g should support packages with a bin section, allowing their binaries to be executed anywhere in the system. However, since May 2022, users have reported that this feature does not work properly in pnpm 7, and the problem persists in the latest version 8.12.1.

Therefore, if your package includes a bin section, you might not be able to use the link -g command to run its binary directly across the system. The current workaround is to add such packages to a specific project and execute the binary within that project.

Directory Link

Directory Link allows you to directly link a local package to another project, instead of through the global environment.

Method 1: Link the library in the target project

# Link my-lib in my-app
cd ~/projects/my-app
pnpm link ~/projects/my-lib

Method 2: Link from the library to the target project

# Link to my-app from my-lib
cd ~/projects/my-lib
pnpm link --dir ~/projects/my-app

Cancel Directory Link

Whether using Method 1 or 2 for Directory link, unlinking is done in the target project:

# Unlink my-lib in my-app
cd ~/projects/my-app

pnpm unlink ~/projects/my-lib
# Or using the package name
pnpm unlink my-lib

Summary

pnpm link is similar to npm link and yarn link, offering a convenient way to link packages in the local environment. While the official pnpm documentation provides basic usage instructions, it may not thoroughly explain practical application, detail handling, and specific use cases. This article aims to fill these gaps, offering a more comprehensive guide on using link for developers using pnpm.

Currently, certain features of pnpm link, like the Global binary, have some issues. These problems can inconvenience developers relying on specific functionalities. As pnpm continues to update and improve, we look forward to these issues being resolved in future versions.

As pnpm evolves, this article will be timely updated to provide the latest information, hoping to assist pnpm developers in achieving a more efficient development workflow.