PNPM - Windows 11 Installation

pnpm Setup Guide for Windows 11 - BigCommerce Catalyst Development

A comprehensive guide to installing and using pnpm (Performant Node Package Manager) on Windows 11 for BigCommerce Catalyst development.

🎯 Why pnpm for Catalyst?

BigCommerce Catalyst uses pnpm as their preferred package manager for several key reasons:

• Disk Space Efficiency: Saves up to 80% disk space compared to npm
• Faster Installation: Significantly faster than npm and yarn
• Strict Node Modules: Prevents phantom dependencies
• Monorepo Support: Better handling of complex project structures
• Content-Addressable Storage: Shared dependencies across projects

🛠 Installation Options

Option 3: Using Chocolatey

Install Chocolatey first (if not already installed)

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

Install pnpm via Chocolatey

choco install pnpm

Verify installation

pnpm --version

⚙️ Windows 11 Configuration

PowerShell Execution Policy

If you encounter execution policy errors:

# Check current execution policy
Get-ExecutionPolicy

# Set execution policy for current user (if needed)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Or for all users (requires admin)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine

Environment Variables

Verify pnpm is in your PATH:

# Check if pnpm is in PATH
echo $env:PATH

# If needed, add pnpm to PATH manually
# Go to: System Properties > Environment Variables > User Variables
# Add to PATH: C:\Users\YourUsername\AppData\Roaming\npm

Windows Terminal Configuration

For the best development experience:

// Add to Windows Terminal settings.json
{
    "profiles": {
        "defaults": {
            "commandline": "powershell.exe",
            "startingDirectory": "C:\\dev\\projects"
        }
    }
}

🚀 Basic pnpm Commands

Package Management

# Install dependencies (equivalent to npm install)
pnpm install
# or simply
pnpm i

# Add a package (equivalent to npm install package)
pnpm add package-name

# Add dev dependency
pnpm add -D package-name

# Add global package
pnpm add -g package-name

# Remove package
pnpm remove package-name

# Update packages
pnpm update

Project Scripts

# Run scripts (same as npm run)
pnpm run dev
pnpm run build
pnpm run test

# Run script directly (no 'run' needed)
pnpm dev
pnpm build
pnpm test

# Run script in specific workspace
pnpm --filter workspace-name dev

Package Information

# List installed packages
pnpm list

# Show package info
pnpm info package-name

# Show outdated packages
pnpm outdated

# Check for security vulnerabilities
pnpm audit

🔄 Migration from npm

Command Comparison

npm	pnpm	Description
npm install	pnpm install	Install dependencies
npm install pkg	pnpm add pkg	Add package
npm install -D pkg	pnpm add -D pkg	Add dev dependency
npm install -g pkg	pnpm add -g pkg	Install globally
npm uninstall pkg	pnpm remove pkg	Remove package
npm run script	pnpm script	Run script
npm update	pnpm update	Update packages
npm list	pnpm list	List packages

Migrating Existing Projects

# Remove existing node_modules and package-lock.json
Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json

# Install with pnpm
pnpm install

🎯 BigCommerce Catalyst Workflow

Initial Project Setup

# Clone your Catalyst project
git clone [your-catalyst-repo-url]
cd [your-project-name]

# Install dependencies with pnpm
pnpm install

# Start development server
pnpm dev

# Build for production
pnpm build

# Run tests
pnpm test

Development Workflow

# Add packages commonly used in your stack
pnpm add @tailwindcss/typography
pnpm add -D @types/node

# Run development with hot reloading
pnpm dev

# Lint and format code
pnpm lint
pnpm format

# Type checking
pnpm type-check

🏗 Advanced pnpm Features

Workspace Management

pnpm-workspace.yaml

packages:
    - 'packages/*'
    - 'apps/*'
    - 'tools/*'

# Run command in all workspaces
pnpm -r run build

# Run command in specific workspace
pnpm --filter my-app dev

# Add dependency to specific workspace
pnpm --filter my-app add lodash

Configuration (.npmrc)

Create .npmrc in your project root:

# Enable strict peer dependencies
strict-peer-dependencies=true

# Hoist patterns for better compatibility
hoist-pattern[]=*eslint*
hoist-pattern[]=*prettier*

# Registry configuration
registry=https://registry.npmjs.org/

# Auto-install peer dependencies
auto-install-peers=true

Store Management

# Check store status
pnpm store status

# Cleanup unused packages
pnpm store prune

# Verify store integrity
pnpm store verify

🛠 VS Code Integration

Recommended Extensions

Install these VS Code extensions for optimal pnpm development:

{
    "recommendations": [
        "ms-vscode.vscode-typescript-next",
        "bradlc.vscode-tailwindcss",
        "esbenp.prettier-vscode",
        "ms-vscode.powershell"
    ]
}

VS Code Settings

Add to your VS Code settings.json:

{
    "npm.packageManager": "pnpm",
    "terminal.integrated.defaultProfile.windows": "PowerShell",
    "typescript.preferences.includePackageJsonAutoImports": "on"
}

🔧 Troubleshooting

Common Windows Issues

PowerShell Execution Policy Error

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

pnpm command not found

# Restart terminal after installation
# Or manually add to PATH

Permission Denied Errors

# Run PowerShell as Administrator
# Or use --force flag
pnpm install --force

Long Path Issues (Windows)

# Enable long paths in Windows
git config --system core.longpaths true

Performance Optimization

# Increase Node.js memory limit
$env:NODE_OPTIONS="--max-old-space-size=4096"

# Use faster registry mirror (if needed)
pnpm config set registry https://registry.npmjs.org/

# Enable network concurrency
pnpm config set network-concurrency 16

📊 Performance Benefits

Benchmark Comparison (Typical Results)

Operation	npm	pnpm	Improvement
Install (fresh)	45s	18s	60% faster
Install (cached)	12s	3s	75% faster
Disk Usage	150MB	30MB	80% smaller

Catalyst Project Benefits

• Faster CI/CD: Reduced installation time in deployment pipelines
• Lower Storage Costs: Significant disk space savings
• Better Development Experience: Faster dependency resolution
• Improved Reliability: Stricter dependency resolution prevents phantom dependencies

🎯 Next Steps

1. Install pnpm: Choose your preferred installation method
2. Verify Setup: Run pnpm --version to confirm installation
3. Configure Environment: Set up PowerShell and VS Code integration
4. Test with Catalyst: Clone and run your BigCommerce Catalyst project
5. Optimize Workflow: Configure .npmrc and workspace settings

📚 Additional Resources

• pnpm Official Documentation
• pnpm CLI Reference
• BigCommerce Catalyst with pnpm
• Windows Terminal Setup

🤝 Integration with Existing Workflow

pnpm integrates seamlessly with your existing development tools:

• Zapier/Make.com: Use in automation scripts
• CI/CD Pipelines: Faster build times
• Docker: Smaller container images
• Retool: Faster development environment setup

---

Ready to supercharge your BigCommerce Catalyst development with pnpm! ⚡