tessl/npm-pnpm

Fast, disk space efficient package manager for Node.js with hard links, symlinks, and monorepo support

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Store Management

Name: tessl/npm-pnpm
Author: tessl

Manage the global package store, inspect cached packages, and optimize disk usage with pnpm's content-addressable storage operations.

Capabilities

Store Operations

Manage the global pnpm store where all packages are cached using content-addressable storage.

/**
 * Manage the global package store
 * Controls content-addressable storage for all packages
 */
pnpm store <command> [options]

Available Commands:

status - Show store status and statistics
path - Show store directory path
prune - Remove unreferenced packages from store
add - Add packages to store without installing

Usage Examples:

# Show store status
pnpm store status

# Show store path
pnpm store path

# Clean up unused packages
pnpm store prune

# Add package to store
pnpm store add react@18.2.0

Store Status

Get detailed information about store usage, size, and package counts.

/**
 * Show store status and statistics
 * Displays store size, package count, and cleanup recommendations
 */
pnpm store status [options]

Usage Examples:

# Show basic store status
pnpm store status

# Show detailed store information
pnpm store status --verbose

Store Path

Display the location of the global package store directory.

/**
 * Show store directory path
 * Returns absolute path to content-addressable store
 */
pnpm store path [options]

Usage Examples:

# Show store path
pnpm store path

# Use store path in scripts
STORE_PATH=$(pnpm store path)

Store Pruning

Remove unreferenced packages from the store to reclaim disk space.

/**
 * Remove unreferenced packages from store
 * Cleans up packages not used by any project
 */
pnpm store prune [options]

Options:

--force - Force removal without confirmation
--dry-run - Show what would be removed without doing it

Usage Examples:

# Prune unused packages (with confirmation)
pnpm store prune

# Force prune without confirmation
pnpm store prune --force

# Show what would be pruned
pnpm store prune --dry-run

Store Add

Add packages to the store without installing them to any project.

/**
 * Add packages to store without installing
 * Pre-populates store for faster subsequent installs
 */
pnpm store add <pkg>[@version] [options]

Usage Examples:

# Add package to store
pnpm store add react

# Add specific version
pnpm store add react@18.2.0

# Add multiple packages
pnpm store add react vue angular

Store Inspection

Inspect Files by Hash

View the contents of files in the store using their content hash.

/**
 * Show file contents from store by hash
 * Displays content of files using content-addressable hash
 */
pnpm cat-file <hash> [options]

Usage Examples:

# Show file contents by hash
pnpm cat-file 1a2b3c4d5e6f7890abcdef1234567890abcdef12

# Show file with specific encoding
pnpm cat-file --encoding=utf8 1a2b3c4d5e6f

Inspect Package Index

View the package index from the store showing package metadata and file structure.

/**
 * Show package index from store
 * Displays package metadata and file structure
 */
pnpm cat-index [options]

Options:

--package <name> - Show index for specific package
--registry <url> - Use specific registry

Usage Examples:

# Show package index
pnpm cat-index

# Show index for specific package
pnpm cat-index --package react

# Show index from specific registry
pnpm cat-index --registry https://registry.npmjs.org

Find Packages by Hash

Find packages in the store that contain a specific hash.

/**
 * Find packages containing specific hash
 * Searches store for packages with matching content hash
 */
pnpm find-hash <hash> [options]

Usage Examples:

# Find packages with hash
pnpm find-hash 1a2b3c4d5e6f7890

# Find with partial hash
pnpm find-hash 1a2b3c

Cache Management

Cache Operations

Manage package cache for improved performance and storage optimization.

/**
 * Manage package cache operations
 * Controls caching behavior for faster installs
 */
pnpm cache <command> [options]

Available Commands:

verify - Verify cache integrity
clean - Clean cache data

Usage Examples:

# Verify cache integrity
pnpm cache verify

# Clean cache
pnpm cache clean

Cache Verification

Verify the integrity of cached packages and metadata.

/**
 * Verify cache integrity
 * Checks cached packages for corruption or inconsistencies
 */
pnpm cache verify [options]

Usage Examples:

# Verify all cached data
pnpm cache verify

# Verify with detailed output
pnpm cache verify --verbose

Cache Cleaning

Clean cached data to free up disk space and resolve cache issues.

/**
 * Clean cache data
 * Removes cached metadata and temporary files
 */
pnpm cache clean [options]

Options:

--force - Force cleaning without confirmation

Usage Examples:

# Clean cache (with confirmation)
pnpm cache clean

# Force clean without confirmation
pnpm cache clean --force

Store Configuration

Store Location

Configure the location of the global package store.

# Set store directory via config
pnpm config set store-dir /path/to/store

# Set via environment variable
export PNPM_STORE_PATH=/path/to/store

# Set via .pnpmrc file
store-dir=/path/to/store

Store Settings

Configure store behavior and optimization settings.

# Store configuration options
store-dir                    # Store directory path
verify-store-integrity      # Verify packages when adding to store
package-import-method       # How to import packages (hardlink, copy, clone)

Configuration Examples:

# Set store directory
pnpm config set store-dir ~/.pnpm-store

# Enable store verification
pnpm config set verify-store-integrity true

# Set package import method
pnpm config set package-import-method hardlink

Store Architecture

Content-Addressable Storage

Understanding pnpm's content-addressable storage system:

# Store structure
<store>/
├── v3/                    # Store format version
│   ├── files/            # Content-addressable files
│   │   ├── 00/           # Hash-based directory structure
│   │   │   └── 1a2b3c... # File content by hash
│   └── metadata/         # Package metadata
└── tmp/                  # Temporary files

Hard Links and Symlinks

pnpm uses hard links and symlinks to share packages efficiently:

# Installation structure
node_modules/
├── .pnpm/                    # Virtual store
│   ├── package@1.0.0/       # Actual package files (hard links to store)
│   └── node_modules/         # Dependency structure
└── package/                  # Symlink to .pnpm/package@1.0.0

Store Benefits

Key advantages of pnpm's store architecture:

# Performance benefits
- Faster installs (packages cached globally)
- Reduced disk usage (shared packages via hard links)
- Atomic installs (packages linked, not copied)
- Offline installs (cached packages available)

# Security benefits  
- Dependency isolation (hoisting limitations)
- Integrity verification (content-addressable hashing)
- Reproducible installs (deterministic linking)

Troubleshooting Store Issues

Store Corruption

Resolve store corruption issues:

# Verify store integrity
pnpm store status

# Prune corrupted packages
pnpm store prune --force

# Clear cache if needed
pnpm cache clean --force

# Reinstall if corruption persists
rm -rf node_modules pnpm-lock.yaml
pnpm install

Disk Space Issues

Manage disk space usage:

# Check store size
pnpm store status

# Remove unused packages
pnpm store prune

# Clean cache data
pnpm cache clean

# Move store to different location
pnpm config set store-dir /path/to/new/store

Permission Issues

Resolve store permission problems:

# Fix store permissions
chmod -R 755 $(pnpm store path)

# Use different store location
pnpm config set store-dir ~/.local/share/pnpm/store

# Run with specific user permissions
sudo -u $USER pnpm install

Store Server Operations

Store Server Management

Start and manage the pnpm store server for improved performance in development environments.

/**
 * Manage pnpm store server
 * Starts/stops background server for faster package operations
 */
pnpm server <command> [options]

Commands:

start - Start the store server
stop - Stop the store server
status - Check server status

Usage Examples:

# Start store server
pnpm server start

# Check server status
pnpm server status

# Stop store server
pnpm server stop

The store server provides:

Faster package resolution through background caching
Reduced startup time for repeated operations
Improved performance for workspace operations
Background dependency pre-fetching

Install with Tessl CLI

npx tessl i tessl/npm-pnpm

docs

configuration.md

index.md

package-inspection.md

package-management.md

script-running.md

store-management.md

workspace-management.md

tile.json

tessl/npm-pnpm