pnpm

Overview

pnpm (performant npm) is a Node.js package manager that differentiates itself from alternatives like npm and Yarn through its unique approach to package storage and dependency resolution. Initiated in 2017, pnpm's primary goal is to enhance efficiency in several key areas: reducing disk space usage, speeding up installation times, and enforcing a stricter dependency model, which can prevent common issues in Node.js projects. Its design makes it particularly suitable for managing large-scale applications and monorepos.

At the core of pnpm's architecture is a content-addressable filesystem used for storing all installed packages. Instead of duplicating packages for each project, pnpm maintains a single, global store on the disk where all versions of all packages are saved. When a project declares a dependency, pnpm creates hard links from the project's node_modules directory to the packages in this global content-addressable store. This method significantly conserves disk space, especially in environments with multiple projects sharing common dependencies, such as monorepos, because each unique package version is stored only once globally. For instance, if twenty projects depend on the same version of React, pnpm will store React once and create twenty hard links, whereas other managers might install twenty separate copies. This approach is detailed in pnpm's official motivation documentation.

Beyond disk space savings, pnpm's linking strategy contributes to faster package installations. By avoiding the need to copy or download packages multiple times, the installation process can often resolve dependencies and set up project environments more quickly than traditional methods. This speed benefit is amplified in continuous integration (CI) environments and during local development where developers frequently switch between branches or initialize new projects.

Another significant aspect of pnpm is its strict dependency enforcement. Unlike npm and Yarn (with their default hoisting behavior), pnpm creates a node_modules structure that only allows direct dependencies to be accessed by the project code. Transitive dependencies are not hoisted to the top level of node_modules, meaning an application can only import packages explicitly listed in its package.json file. This strictness helps prevent issues such as "phantom dependencies" (where code relies on a dependency not explicitly declared) and "non-hoisted dependencies" (where a package expects a hoisted dependency that isn't available). This strictness aligns with practices that promote more reliable and maintainable codebases by making dependency relationships explicit, as discussed in best practices for JavaScript module management on platforms like MDN Web Docs.

While pnpm offers substantial benefits, its unique node_modules structure, which utilizes symlinks, can occasionally lead to compatibility challenges with certain tools that anticipate a flat node_modules layout. Developers considering pnpm, especially in existing projects, should evaluate potential integration challenges with their current build tools, bundlers, and testing frameworks. However, the pnpm team actively works to address these compatibility issues and provides guidance for common scenarios.

Key features

• Content-Addressable Store: Stores packages in a global, shared location on disk, using hard links to project node_modules directories. This reduces disk space usage by ensuring each unique package version is stored only once, regardless of how many projects depend on it.
• Faster Installations: Leverages the content-addressable store and optimized dependency resolution to accelerate package installation times, particularly beneficial for monorepos and CI environments.
• Strict Dependency Enforcement: Creates a non-flat node_modules structure that only exposes direct dependencies to the project, preventing access to undeclared transitive dependencies and reducing issues like phantom dependencies.
• Monorepo Support: Provides built-in features for managing multiple packages within a single repository, including workspace functionality, selective package execution, and efficient dependency linking across sub-projects.
• Disk Space Efficiency: Achieves significant disk space savings by using hard links from the global store rather than duplicating packages across projects.
• Hoisting Options: While strict by default, pnpm offers options to configure hoisting behavior for compatibility with tools that expect a flatter node_modules structure.
• Integrity Checks: Ensures package integrity by verifying checksums, preventing tampering or corruption of downloaded packages.

Pricing

pnpm is an open-source tool, distributed under the MIT License. There are no direct costs associated with its usage, installation, or integration into development workflows. All core features and functionalities are freely available.

Common integrations

• Node.js: pnpm is a package manager for Node.js projects, inherently integrating with the Node.js runtime and ecosystem. It manages dependencies for applications built with Node.js, as described on the Node.js official website.
• TypeScript: Fully supports TypeScript projects, managing devDependencies for TypeScript compilers and related tools, and ensuring type definitions are correctly linked.
• Web Frameworks (React, Vue, Angular, Svelte): Manages dependencies for popular frontend frameworks, ensuring efficient installation and linking of libraries like React, Vue.js, Angular, and Svelte.
• Build Tools (Webpack, Rollup, Vite): Integrates with common JavaScript build tools, handling their installation and ensuring they can resolve dependencies correctly from pnpm's node_modules structure.
• Monorepo Tools (Turborepo, Nx): Designed to work effectively with monorepo management tools, providing efficient package installation and linking across multiple projects within a single repository.
• Continuous Integration/Continuous Deployment (CI/CD) Systems: Compatible with CI/CD platforms like GitHub Actions, GitLab CI, and Jenkins, enabling fast and reliable dependency installation during automated build and deployment processes.

Alternatives

• npm: The default package manager for Node.js, widely used for its extensive package registry and robust feature set.
• Yarn: An alternative package manager known for its speed, reliability, and additional features like Workspaces for monorepos.
• Bun: A new JavaScript runtime, bundler, transpiler, and package manager designed for performance and all-in-one development.

Getting started

To begin using pnpm, you first need to install it globally on your system. Once installed, you can use it to create new projects or manage dependencies in existing ones. Below is a basic example of initializing a new Node.js project and adding a dependency.

# Install pnpm globally
npm install -g pnpm

# Verify installation
pnpm -v

# Create a new project directory
mkdir my-pnpm-app
cd my-pnpm-app

# Initialize a new Node.js project
pnpm init

# Add a dependency (e.g., Express.js)
pnpm add express

# You can then create an 'index.js' file:
# const express = require('express');
# const app = express();
# const port = 3000;
#
# app.get('/', (req, res) => {
#   res.send('Hello from pnpm app!');
# });
#
# app.listen(port, () => {
#   console.log(`App listening at http://localhost:${port}`);
# });

# Install all dependencies listed in package.json
pnpm install

# Run a script defined in package.json (e.g., a 'start' script)
pnpm start