What Is pnpm?

A Beginner's Guide to the JavaScript Package Manager

Introduction to pnpm

If you are learning JavaScript or Node.js, you will eventually need a package manager. A package manager helps you install, update, remove, and manage the libraries your projects use.

pnpm is a package manager for JavaScript and Node.js projects. It is an alternative to npm and Yarn.

One of pnpm's key features is its efficient approach to storing and linking package files. This can reduce duplicated files and save disk space when several projects use the same packages.

Simple definition: pnpm is a JavaScript package manager designed to manage project dependencies efficiently.

Table of Contents

1. What does pnpm mean? 2. Why was pnpm created? 3. How pnpm works 4. Installing pnpm 5. Creating a project 6. Essential pnpm commands 7. package.json and lockfiles 8. Running scripts 9. pnpm dlx and exec 10. Workspaces and monorepos 11. pnpm vs npm vs Yarn 12. Build a Node.js project 13. Common mistakes 14. Frequently asked questions

What Does pnpm Mean?

The name pnpm is commonly associated with the phrase performant npm.

It offers familiar commands for managing JavaScript dependencies while using a different approach to package storage and linking.

Why Was pnpm Created?

JavaScript projects often depend on many external packages. When several projects use the same packages, storing separate copies of every file can consume significant disk space.

pnpm uses a content-addressable store. Package files can be stored centrally and linked into projects, reducing unnecessary duplication in many situations.

Installations may also be faster when required package data is already available locally. Actual performance depends on the project, network and machine.

How Does pnpm Work?

Imagine you have several JavaScript projects that use the same version of React. pnpm can store package content in a shared store and link that content into each project.

Project A
   |
   +---- React
          |
          v
   Shared pnpm Store
          ^
          |
   Project B

This can save storage space. pnpm also uses a dependency layout that helps make packages explicitly declare the dependencies they need.

The shared store does not mean every project has the same dependency versions. Different projects can use different versions of a package.

Installing pnpm

Installation depends on your operating system and Node.js setup. Check the official installation guide for the current recommended method.

One possible installation method is to use npm:

npm install --global pnpm

Then check whether pnpm is available:

pnpm --version

If a version number appears, pnpm is available in your terminal.

Modern Node.js setups may also support Corepack, depending on the Node.js version and installation. See the official pnpm documentation for current guidance.

Official pnpm installation guide

If the terminal says that pnpm is not recognized, check that Node.js and pnpm are installed correctly and that the relevant executable directory is in your PATH.

Create a New pnpm Project

Create a folder for your project and open a terminal inside it:

mkdir my-app
cd my-app
pnpm init

The initialization command creates a package.json file containing project information.

You can also use pnpm to install dependencies in an existing JavaScript project.

Installing a Package

Use pnpm add to add a package to your project:

pnpm add lodash

To install Express, for example:

pnpm add express

The package is added to your project's dependencies and becomes available to your application.

Installing a Development Dependency

Development dependencies are packages mainly used during development, testing or building.

pnpm add --save-dev typescript

You can use the shorter form:

pnpm add -D typescript

Installing All Dependencies

When you download or clone an existing project, its dependencies are often listed in package.json.

pnpm install

pnpm reads the project dependency information and installs the required packages. If a compatible lockfile is present, it helps keep the resolved versions consistent.

Removing a Package

Remove a package that your project no longer needs:

pnpm remove lodash

This removes the package from the project's dependency list and updates the lockfile.

Updating Packages

To update packages within the version ranges allowed by the project:

pnpm update

To update one package:

pnpm update express

Review changes and test your project after updates, particularly before deploying to production.

Understanding package.json

A basic JavaScript project might have a package.json file like this:

{
  "name": "my-app",
  "version": "1.0.0",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "express": "^5.0.0"
  }
}

The dependencies section lists packages needed by the application. The scripts section defines commands that developers can run.

The version range shown is an example. The actual installed version is recorded in the lockfile.

Understanding pnpm-lock.yaml

pnpm uses a lockfile named pnpm-lock.yaml. It records the resolved dependency graph and related information used for installation.

Keeping the lockfile in source control helps team members and build environments install consistent dependency versions.

Tip: For application projects, commit both package.json and pnpm-lock.yaml to your repository.

Running Project Scripts

If your package.json defines a script called start, run it with:

pnpm run start

To run a development script:

pnpm run dev

Many scripts can also be run using the shorter form:

pnpm dev

The exact commands available depend on the scripts defined by your project.

Using pnpm exec

The pnpm exec command runs an executable provided by your project's dependencies.

pnpm exec tsc

This is useful when a tool such as TypeScript is installed locally instead of globally.

Using pnpm dlx

The pnpm dlx command downloads and runs a package without permanently adding it as a dependency to the current project.

pnpm dlx create-vite

It is useful for running project generators and other temporary command-line tools. Check the package documentation before executing unfamiliar commands.

What Are pnpm Workspaces?

Workspaces let you manage multiple related packages in one repository. This is useful for teams that maintain several applications and shared libraries together.

For example, a repository might contain:

my-company/
├── apps/
│   ├── website/
│   └── mobile/
├── packages/
│   ├── ui/
│   └── shared/
└── pnpm-workspace.yaml

The applications and libraries can share code while remaining separate packages.

Configuring pnpm-workspace.yaml

A workspace configuration can define which folders contain packages:

packages:
  - "apps/*"
  - "packages/*"

Save this configuration as pnpm-workspace.yaml in the workspace root. The patterns should match your actual folder structure.

Understanding Monorepos

A monorepo is a single repository containing multiple related projects or packages.

pnpm workspaces provide tools for managing dependencies and running commands across packages. This can make large repositories easier to maintain.

Monorepos are especially useful when multiple applications share UI components, utility functions or internal libraries.

Filtering Workspace Packages

In a large workspace, you may want to run a command against one package rather than every package.

For example, a workspace package named website can be targeted with a filter:

pnpm --filter website run build

The package selector must match the relevant package name or selection pattern in your workspace.

See the official pnpm filtering documentation for more advanced examples.

Why Developers Use pnpm

Benefits vary depending on the project and its configuration.

pnpm vs npm

Featurepnpmnpm
Manages JavaScript packagesYesYes
Project manifestpackage.jsonpackage.json
Default lockfilepnpm-lock.yamlpackage-lock.json
Workspace supportYesYes
Package storageContent-addressable store and linksDifferent installation and storage approach
Dependency layoutUses a layout designed to reduce duplication and enforce clearer dependency accessTypically uses a different node_modules layout

Both tools are widely used. The best choice depends on your project, workflow and team preferences.

pnpm vs Yarn

pnpm and Yarn are package managers used in the JavaScript ecosystem. Both support dependency management and workspaces.

One distinctive pnpm feature is its content-addressable store, which can reduce duplicated package files on disk.

Yarn also provides advanced workspace features and Plug'n'Play support in applicable versions and configurations.

For more information, visit the official Yarn documentation.

Example: Create a Small Express Application

This example shows a basic workflow for creating a Node.js application using pnpm.

Step 1: Create the project

mkdir my-app
cd my-app
pnpm init
pnpm add express

Step 2: Create index.js

const express = require("express");

const app = express();

app.get("/", (req, res) => {
  res.send("Hello from TechLearn Hub!");
});

app.listen(3000, () => {
  console.log("Server running on port 3000");
});

Step 3: Start the application

node index.js

Open http://localhost:3000 in your browser on the same device or environment where the server is running.

This example is a local development server. For a public deployment, configure hosting, security, logging and environment settings appropriately.

Useful pnpm Commands Cheat Sheet

CommandPurpose
pnpm --versionShow the installed version
pnpm initInitialize a project
pnpm installInstall project dependencies
pnpm add lodashAdd a dependency
pnpm add -D typescriptAdd a development dependency
pnpm remove lodashRemove a dependency
pnpm updateUpdate packages within allowed ranges
pnpm run devRun the dev script
pnpm run buildRun the build script
pnpm exec tscRun a locally installed executable
pnpm dlx create-viteRun a temporary package tool

Common Beginner Mistakes

1. Mixing Package Managers

Avoid switching randomly between npm, Yarn and pnpm in the same project. Choose a package manager and keep its lockfile consistent.

2. Ignoring the Lockfile

Do not casually delete pnpm-lock.yaml. It helps keep dependency versions consistent across installations.

3. Installing Everything Globally

Most project-specific tools and libraries should be installed locally so that the project can declare and manage its dependencies.

4. Ignoring Error Messages

Read terminal output carefully when a command fails. It may identify a missing package, incorrect script, version conflict or configuration issue.

5. Assuming Every Project Uses the Same Commands

The available scripts depend on each project's package.json. Check the scripts section before running commands such as pnpm dev.

A Simple pnpm Workflow

  1. Install Node.js and pnpm.
  2. Create a new project or open an existing one.
  3. Initialize the project if necessary.
  4. Install the dependencies you need.
  5. Write and test your application code.
  6. Run development or build scripts.
  7. Commit package.json and pnpm-lock.yaml to source control.
  8. Review and test dependency updates.

Frequently Asked Questions

Is pnpm free?

Yes. pnpm is an open-source package manager.

Can pnpm replace npm?

Yes. pnpm can manage dependencies for many JavaScript and Node.js projects that would otherwise use npm. Some project-specific workflows may require adjustments.

Can I use pnpm with React?

Yes. pnpm can manage React and other frontend dependencies.

Can I use pnpm with TypeScript?

Yes. You can install TypeScript as a development dependency and run its tools through pnpm.

Is pnpm suitable for beginners?

Yes. Beginners can use pnpm after learning the basics of project folders, dependencies, package.json and terminal commands.

Is pnpm only for Node.js?

pnpm is mainly used to manage packages in the JavaScript and Node.js ecosystem.

Does pnpm work with existing npm projects?

Often, yes. pnpm can use a project's package.json, but you should understand the lockfile and choose a consistent migration process.

What should I learn next?

Learn JavaScript modules, Node.js, package.json scripts, dependency management, testing and build tools such as Vite.

Official pnpm Resources

Conclusion

pnpm is a modern package manager for JavaScript and Node.js projects. Its storage system, familiar commands and workspace features make it useful for both small projects and larger codebases.

If you already understand npm, many pnpm commands will feel familiar. The key differences are how pnpm stores and links dependencies and how it organizes packages in a project.

Remember: pnpm helps you install and manage JavaScript dependencies efficiently. Practice with a small project before using it in a larger application.

Related Learning Resources

Make sure each related HTML file exists on your website before publishing the links.