What is pnpm's global store and how to manage and clean it?

pnpm's global store is one of its core features, used to store dependency packages for all projects.

Store Location:

bash
# Default location
~/.pnpm-store

# Windows
%LOCALAPPDATA%/pnpm/store

# Custom location
# .npmrc
store-dir = /path/to/custom/store

Store Structure:

shell
~/.pnpm-store/
├── v3/                          # store version
│   ├── files/                   # Actual file storage
│   │   ├── 00/                  # Content-addressed directories
│   │   │   ├── abc123...        # File content
│   │   │   └── def456...
│   │   └── ...
│   └── index/                   # Index files
│       └── ...
└── metadata.json                # Metadata

Content-Addressable Storage:

pnpm uses content-addressable storage:

javascript
// File storage path based on content hash
const crypto = require('crypto');
const content = fs.readFileSync('lodash.js');
const hash = crypto
  .createHash('sha256')
  .update(content)
  .digest('hex');
// Storage path: ~/.pnpm-store/v3/files/00/abc123...

Store Management:

bash
# View store information
pnpm store status

# View store path
pnpm store path

# Clean unused packages
pnpm store prune

# Verify store integrity
pnpm store verify

Store Advantages:

1. Disk Space Saving

bash
# 10 projects using lodash@4.17.21
# npm: 10 × 1.4MB = 14MB
# pnpm: 1 × 1.4MB = 1.4MB

1. Installation Speed Improvement

bash
# First installation
pnpm install lodash  # Download to store, create hard link

# Second project installation
pnpm install lodash  # Create hard link directly from store, instant

1. Cross-Project Sharing

bash
# Project A
cd project-a
pnpm install  # Download to store

# Project B
cd project-b
pnpm install  # Reuse packages from store

Store Cleanup Strategy:

bash
# Clean unreferenced packages
pnpm store prune

# When to clean:
# 1. After upgrading pnpm version
# 2. When disk space is low
# 3. When not cleaned for a long time

Multi-Store Configuration:

bash
# Different projects use different stores
# project-a/.npmrc
store-dir = /path/to/store-a

# project-b/.npmrc
store-dir = /path/to/store-b

Relationship Between Store and Hard Links:

shell
Global Store:
~/.pnpm-store/v3/files/00/abc123 (Actual file)

Hard links in projects:
project-a/node_modules/.pnpm/lodash@4.17.21/lodash.js → abc123
project-b/node_modules/.pnpm/lodash@4.17.21/lodash.js → abc123
project-c/node_modules/.pnpm/lodash@4.17.21/lodash.js → abc123

# All hard links point to the same physical file

Important Notes:

1. Cross-Filesystem Issues

bash
# Hard links cannot cross filesystems
# If projects are on different partitions, configure store location
# .npmrc
store-dir = /same/filesystem/path

1. Permission Issues

bash
# Ensure store directory has correct permissions
chmod -R 755 ~/.pnpm-store