package-management（包管理）

Package Management

Overview

This project uses pnpm as the package manager, with corepack to manage pnpm versions automatically.

Corepack Integration

How It Works

• pnpm version is specified in package.json under the packageManager field
• corepack automatically uses the exact version specified
• No need to manually install pnpm - corepack handles it

Example from package.json

{
  "packageManager": "pnpm@9.1.0"
}

When you run pnpm commands, corepack ensures version 9.1.0 is used.

Common Commands

Installing Dependencies

pnpm install

This installs all dependencies from package.json using the version specified in the packageManager field.

Adding New Dependencies

# Production dependency
pnpm add <package-name>

# Development dependency
pnpm add -D <package-name>

Upgrading pnpm

To upgrade pnpm to the latest version:

corepack use pnpm@latest

This command:

1. Updates to the latest pnpm version
2. Automatically updates package.json's packageManager field
3. Ensures the team uses the same version

Upgrading to Specific pnpm Version

corepack use pnpm@9.5.0

Troubleshooting

Signature Verification Errors

If you encounter signature verification errors when running pnpm commands:

npm install -g corepack@latest

This updates corepack itself, which can resolve verification issues.

pnpm Command Not Found

If pnpm is not recognized:

1. Enable corepack (if not already enabled): corepack enable
2. Install the project's pnpm version: corepack install

Wrong pnpm Version

If the wrong pnpm version is being used:

1. Check the version specified in package.json: {"packageManager": "pnpm@X.Y.Z"}
2. Ensure corepack is enabled: corepack enable
3. Re-run your command - corepack should download the correct version

Best Practices

1. Never install pnpm globally - Let corepack manage it
2. Use corepack use pnpm@latest to upgrade, not manual installation
3. Commit package.json changes when upgrading pnpm (the packageManager field)
4. Don't mix package managers - Always use pnpm, never npm or yarn

Why Corepack?

Benefits

• Version consistency - Everyone uses the same pnpm version
• No manual installation - Corepack handles pnpm installation
• Automatic switching - Different projects can use different pnpm versions
• Lockfile compatibility - Ensures pnpm-lock.yaml is compatible

How It's Different from Manual Installation

With corepack (this project):

# Just run pnpm - corepack handles the rest
pnpm install

Without corepack:

# Manual installation needed
npm install -g pnpm@9.1.0
pnpm install

Integration with CI/CD

In CI/CD environments, ensure corepack is enabled:

# Enable corepack first
corepack enable

# Then run pnpm commands
pnpm install
pnpm build

Most modern CI environments (GitHub Actions, etc.) have corepack pre-installed.

Common Workflows

First-time Setup

# 1. Enable corepack (if needed)
corepack enable

# 2. Install dependencies
pnpm install

# 3. Start development
pnpm dev

Upgrading All Dependencies

# Update all dependencies to latest versions
pnpm update --latest

# Or use interactive mode
pnpm update --interactive --latest

Checking Outdated Packages

pnpm outdated

Deduplicate Dependencies

pnpm dedupe

This removes duplicate packages from pnpm-lock.yaml, reducing installation size.

Key Reminders

• ✅ Use corepack use pnpm@latest to upgrade pnpm
• ✅ Commit package.json changes when pnpm version changes
• ✅ Enable corepack before using pnpm
• ❌ Don't install pnpm globally with npm
• ❌ Don't manually edit the packageManager field