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.
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 questionsWhat 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.
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
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.
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
- Efficient package storage.
- Potentially faster installs when dependencies are cached.
- Support for workspaces and monorepos.
- Familiar commands for JavaScript developers.
- A lockfile for reproducible dependency installation.
- A dependency layout that helps expose undeclared dependencies.
- Compatibility with many projects using package.json.
Benefits vary depending on the project and its configuration.
pnpm vs npm
| Feature | pnpm | npm |
|---|---|---|
| Manages JavaScript packages | Yes | Yes |
| Project manifest | package.json | package.json |
| Default lockfile | pnpm-lock.yaml | package-lock.json |
| Workspace support | Yes | Yes |
| Package storage | Content-addressable store and links | Different installation and storage approach |
| Dependency layout | Uses a layout designed to reduce duplication and enforce clearer dependency access | Typically 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.
Useful pnpm Commands Cheat Sheet
| Command | Purpose |
|---|---|
pnpm --version | Show the installed version |
pnpm init | Initialize a project |
pnpm install | Install project dependencies |
pnpm add lodash | Add a dependency |
pnpm add -D typescript | Add a development dependency |
pnpm remove lodash | Remove a dependency |
pnpm update | Update packages within allowed ranges |
pnpm run dev | Run the dev script |
pnpm run build | Run the build script |
pnpm exec tsc | Run a locally installed executable |
pnpm dlx create-vite | Run 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
- Install Node.js and pnpm.
- Create a new project or open an existing one.
- Initialize the project if necessary.
- Install the dependencies you need.
- Write and test your application code.
- Run development or build scripts.
- Commit package.json and pnpm-lock.yaml to source control.
- 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.
Related Learning Resources
- TechLearn Hub Home
- What Is npm?
- JavaScript Guide
- Web Development Guide
- Programming Guide
- Contact TechLearn Hub
Make sure each related HTML file exists on your website before publishing the links.