How to Use pnpm Basics and Tutorial

Overview of pnpm

pnpm is a fast, disk space-efficient package manager for JavaScript that helps manage project dependencies. It is an alternative to npm and yarn, designed to solve some of the inefficiencies found in those tools. pnpm uses a unique approach to store packages in a global content-addressable store, which allows it to link dependencies efficiently. This means that when multiple projects depend on the same package, pnpm creates a single copy of that package on the disk, which is then symlinked into each project. This approach not only saves disk space but also speeds up installations.

Related Article: How To Upgrade Pnpm

Installing pnpm

To get started with pnpm, it must first be installed on your system. The recommended way to install pnpm is through npm or yarn. Here’s how you can do it:

Using npm:

npm install -g pnpm

Using yarn:

yarn global add pnpm

After installation, you can verify that pnpm is installed correctly by checking its version:

pnpm -v

This command will display the installed version of pnpm, confirming that the installation was successful.

Advantages of pnpm

Several advantages make pnpm a favorable choice among developers. The primary benefit is its efficient use of disk space. Since pnpm stores packages in a global store and symlinks them into projects, it avoids redundancy. This approach can significantly reduce the amount of disk space consumed by node modules, especially in projects with many shared dependencies.

Another advantage is the speed of installations. Because pnpm utilizes a global store, it can install packages faster than npm or yarn, as it avoids downloading the same package multiple times. Additionally, pnpm's strictness in package versioning helps to avoid dependency hell, ensuring that projects remain stable with predictable dependency trees.

Moreover, pnpm supports a workspace feature, allowing you to manage multiple packages in a monorepo efficiently. This feature makes it easier to develop and maintain large projects with multiple interconnected packages.

Handling Node Modules

Handling node modules with pnpm is quite different from traditional methods. When you install a package, pnpm creates a node_modules directory in your project that contains symlinks to the global store. This structure allows you to manage dependencies without cluttering your project with multiple copies of the same package.

For example, to install a package like lodash, you would run:

pnpm add lodash

After running this command, you would see a node_modules folder created in your project directory. However, instead of containing the actual lodash package, it contains a symlink pointing to the version stored in the global store.

This method of handling node modules means that there are fewer issues with conflicting versions of packages. If two packages require different versions of the same dependency, pnpm can resolve this by creating separate symlinks for each version, avoiding conflicts.

Related Article: How To Set Pnpm Version In Your Project

Creating a pnpm Project

To create a new project using pnpm, you start by initializing a new package. This can be done easily with the following command:

pnpm init

This command will prompt you to answer a series of questions, such as the project name, version, and description. After completing the prompts, a package.json file will be generated in your project directory.

Once the project is initialized, you can begin adding dependencies. For instance, if you need to add express, you can run:

pnpm add express

This command installs the express package and updates your package.json and pnpm-lock.yaml files accordingly. The details of the lockfile will be discussed further in the next section.

Using a pnpm Workspace

A pnpm workspace allows you to manage multiple related packages within a single repository. This feature is particularly useful for monorepos, where several packages are developed and maintained together. To set up a workspace, you need to create a pnpm-workspace.yaml file in the root of your repository.

Here is an example of what the pnpm-workspace.yaml file might look like:

packages:
  - 'packages/*'

In this example, all packages located in the packages directory will be included in the workspace. Each package can manage its dependencies independently, and pnpm will handle the symlinking automatically.

After setting up the workspace, you can add dependencies across all packages with a single command. For example:

pnpm install

This command installs all dependencies for all packages in the workspace, making dependency management seamless.

Updating Dependencies

Updating dependencies in pnpm is a straightforward process. To update a specific package, you can use the following command:

pnpm update <package-name>

For instance, if you want to update lodash to its latest version, you would run:

pnpm update lodash

pnpm will check for the latest version of the specified package and update it automatically. If you want to update all dependencies in your project to their latest versions, you can simply run:

pnpm update

This command will go through all packages listed in your package.json and update them as necessary, ensuring that your project is using the most recent versions of its dependencies.

pnpm Lockfile Details

When you install or update dependencies using pnpm, it creates a lockfile named pnpm-lock.yaml. This file is essential for ensuring that the same versions of dependencies are installed across different environments. It records the exact versions of packages installed in your project along with their dependencies.

The lockfile format is human-readable and provides a complete view of the dependency tree. Here’s an example of what a snippet from the pnpm-lock.yaml file might look like:

lockfileVersion: 5
packages:
  /lodash/4.17.21:
    resolution:
      integrity: sha512-...
    dev: false
    dependencies:
      ...

Related Article: How To Check Pnpm Version

Using pnpm in a Monorepo

When working with a monorepo setup, pnpm shines with its workspace feature. It allows developers to manage multiple packages in the same repository easily. In a monorepo, you typically have a structure with several packages that may depend on each other.

To start using pnpm in a monorepo, create a pnpm-workspace.yaml file as mentioned earlier. Each package should have its own directory under the defined structure. For example:

/my-monorepo
  /packages
    /package-a
      package.json
    /package-b
      package.json
  pnpm-workspace.yaml

You can run commands from the root of the monorepo that affect all packages. For instance:

pnpm install

This command installs dependencies for all packages in the monorepo simultaneously, making it easier to manage interdependencies.

npm Compatibility

pnpm is designed to be compatible with npm, which means you can use it alongside existing npm projects. If you have a project that already uses npm, you can switch to pnpm with minimal effort.

To convert an npm project to use pnpm, simply run:

pnpm install

This command will read the existing package-lock.json file and create a new pnpm-lock.yaml file, converting your project to pnpm. You can continue using the same commands you used with npm, such as pnpm install, pnpm update, and pnpm remove.